Related instance specification

TypeScript type: RelatedInstanceSpecification.

Related instance specification is used in content and hierarchy specifications to "join" the primary instance with its related instance and allow using the related instance for:

• Filtering, when used in instanceFilter.
• Customization, when used in customization rules.
• Grouping, when used in grouping rules.

Attributes

Attribute: relationshipPath

Specifies a chain of relationship path specifications that forms a path from the primary instance to the related instances.

Attribute: targetInstances

Specifies a target class and IDs of its ECInstances to relate to the primary instance.

This may be useful when you want to use information of a completely unrelated (or related by means other than an ECRelationship) ECInstance in instance filter, conditions or grouping.

Attribute: alias

Specifies an an alias that given to the related instance. The alias can be used to reference the instance in instance filter and customization rules.

Note: The value must be unique per hierarchy specification. If there are multiple related instance specifications using the same alias, the library uses the first one and ignores the rest of them.

Attribute: isRequired

Specifies whether to omit the primary instance from the result if the other end of relationshipPath does not yield any related instances.

Examples

Using related instances with relationship path in instance filter

// This ruleset defines a specification that returns content for `bis.ViewDefinition` instances. In addition,
// there's a related instance specification, that describes a path to a related display style, and an
// instance filter that filters using its property.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "ContentInstancesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
          relatedInstances: [
            {
              relationshipPath: {
                relationship: { schemaName: "BisCore", className: "ViewDefinitionUsesDisplayStyle" },
                direction: "Forward",
              },
              alias: "display_style",
              isRequired: true,
            },
          ],
          instanceFilter: `display_style.CodeValue ~ "%View%"`,
        },
      ],
    },
  ],
};

	Result
Without instance filter
With instance filter

Using related instances with target instance IDs in instance filter

// This ruleset defines a specification that returns content for `bis.ViewDefinition` instances. In addition,
// there's a related instance specification for the root Subject, and an instance filter that filters using its property.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "Content",
      specifications: [
        {
          specType: "ContentInstancesOfSpecificClasses",
          classes: { schemaName: "BisCore", classNames: ["ViewDefinition"], arePolymorphic: true },
          relatedInstances: [
            {
              targetInstances: {
                class: { schemaName: "BisCore", className: "Subject" },
                instanceIds: [IModel.rootSubjectId],
              },
              alias: "root_subject",
              isRequired: true,
            },
          ],
          instanceFilter: `root_subject.Description = this.Description`,
        },
      ],
    },
  ],
};

Using related instances for customization

// This ruleset defines a specification that returns nodes for `meta.ECClassDef` instances. In addition,
// there's a related instance specification, that describes a path to the schema that the class belongs to.
// Finally, there's an extended data rule that sets full class name on each of the nodes. Full class name consists
// of schema and class names and the schema instance can be referenced through the alias specified in related
// instance specification.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "ECDbMeta", classNames: ["ECClassDef"] },
          groupByClass: false,
          groupByLabel: false,
          relatedInstances: [
            {
              relationshipPath: {
                relationship: { schemaName: "ECDbMeta", className: "SchemaOwnsClasses" },
                direction: "Backward",
              },
              alias: "schema",
              isRequired: true,
            },
          ],
        },
      ],
      customizationRules: [
        {
          ruleType: "ExtendedData",
          items: {
            fullClassName: `schema.Name & "." & this.Name`,
          },
        },
      ],
    },
  ],
};

// Every node should have its full class name in extended data
const { total, items } = await Presentation.presentation.getNodesIterator({
  imodel,
  rulesetOrId: ruleset,
});

expect(total).to.eq(417);
for await (const node of items) {
  const fullClassName = node.extendedData!.fullClassName;
  const [schemaName, className] = fullClassName.split(".");
  expect(schemaName).to.not.be.empty;
  expect(className).to.not.be.empty;
}

Using related instances for grouping

// This ruleset defines a specification that returns nodes for `meta.ECClassDef` instances. In addition,
// there's a related instance specification, that describes a path to the schema that the class belongs to.
// Finally, there's a grouping rule that requests grouping on `ECSchemaDef.Name` property. Because
// the `ECClassDef` instances are "linked" to related `ECSchemaDef` instances, the grouping takes effect
// and classes get grouped by related schema names.
const ruleset: Ruleset = {
  id: "example",
  rules: [
    {
      ruleType: "RootNodes",
      specifications: [
        {
          specType: "InstanceNodesOfSpecificClasses",
          classes: { schemaName: "ECDbMeta", classNames: ["ECClassDef"] },
          groupByClass: false,
          groupByLabel: false,
          relatedInstances: [
            {
              relationshipPath: {
                relationship: { schemaName: "ECDbMeta", className: "SchemaOwnsClasses" },
                direction: "Backward",
              },
              alias: "schema",
              isRequired: true,
            },
          ],
        },
      ],
      customizationRules: [
        {
          ruleType: "Grouping",
          class: { schemaName: "ECDbMeta", className: "ECSchemaDef" },
          groups: [
            {
              specType: "Property",
              propertyName: "Name",
              createGroupForSingleItem: true,
            },
          ],
        },
      ],
    },
  ],
};

	Result
Without related instance specification
With related instance specification