[Experimental] Related instance API allow traversal of instance in forward/backward/both directions

[khanaffan]

[Experimental] & [Wip]

The API allows the generically traverse of a graph of instances using relationships

The API introduces a virtual class that takes an instance key and direction and will return a table of related instances along with relationship ID and direction.

rel1.related_instances(<instanceid>, <eclassid>, 'forward' | 'backward' | 'both')

Related instances use internally cached ECSQL statements to give you related instances and can be slow at first when these statements get prepared. The performance also varies depending on the number of relationships for a given instance key.

It can be used in conjunction with other classes in ECSQL as follows.

 SELECT
    Bis.Element.ECInstanceId, 
    g.* 
 FROM
     Bis.Element e, 
     rel1.related_instances(Bis.Element.ECInstanceId, Bis.Element.ECClassId) g
 WHERE Bis.Element.ECINstanceId = 0x30000001ddf;

Table

ECInstanceId	ECInstanceId	ECClassId	RelECClassId	Direction
0x30000001ddf	1	244	91	1
0x30000001ddf	3298534891276	252	160	1
0x30000001ddf	3298534890841	211	164	1