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
Name | Required? | Type | Default |
---|---|---|---|
relationshipPath |
Yes, if targetInstances not specified |
RelationshipPathSpecification |
|
targetInstances |
Yes, if relationshipPath not specified |
{ class: SingleSchemaClassSpecification; instanceIds: Id64String[] } |
|
alias |
Yes | string |
|
isRequired |
No | boolean |
false |
Attribute: relationshipPath
Specifies a chain of relationship path specifications that forms a path from the primary instance to the related instances.
Type | RelationshipPathSpecification |
Is Required | Yes, if targetInstances is not specified |
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.
Type | { class: SingleSchemaClassSpecification; instanceIds: Id64String[] } |
Is Required | Yes, if relationshipPath is not specified |
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.
Type | string |
Is Required | Yes |
Attribute: isRequired
Specifies whether to omit the primary instance from the result if the other end of relationshipPath
does not yield any related instances.
Type | boolean |
Is Required | No |
Default Value | false |
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 |
Last Updated: 13 May, 2024