ECDbMap (ECDb DB Mapping) Schema

Alias: ecdbmap

Version: 2.0.4

Custom attributes that customize ECDb's ECSchema to database mapping.

Table of contents

DbIndex Sealed StructClass

Specify a database index for an ECClass.

Properties

Name Description Label Category Read Only Priority
Name Name of the index. Must follow EC identifier rules. It needs to be globally unique in the database. false 0
IsUnique Default: false. If true, all values in the indexed properties must be unique. false 0
Properties List of properties that make up the index. Only properties of primitive type are supported. false 0
Where Where constraint for index false 0

Custom Attribute Classes

ClassMap Sealed CustomAttributeClass

Applies to: EntityClass, RelationshipClass

Properties

Name Description Label Category Read Only Priority
MapStrategy Defines how the ECClass is mapped to table(s). Values: OwnTable (default), TablePerHierarchy, ExistingTable, NotMapped false 0
TableName If MapStrategy is 'ExistingTable' provide the table name here. Must not be set in all other cases. false 0
ECInstanceIdColumn Optionally specify the name of custom 'primary key' column which must be of type Int64. false 0

DbIndexList Sealed CustomAttributeClass

Applies to: EntityClass, RelationshipClass

Properties

Name Description Label Category Read Only Priority
Indexes List of indexes on properties of this class. It can be use to improve query performance or to add unique constraint. false 0

ForeignKeyConstraint Sealed CustomAttributeClass

Creates a foreign key for this navigation property.

Applies to: NavigationProperty

Properties

Name Description Label Category Read Only Priority
OnDeleteAction Possible values: NoAction (default), Cascade (which deletes child rows when parent row is deleted), SetNull(foreign key property in child is set to NULL), Restrict (cannot delete parent if it still has children). false 0
OnUpdateAction Possible values: NoAction (default), Cascade (which updates child foreign key when parent primary key is updated). false 0

ForeignKeyView Sealed CustomAttributeClass

Flags a relationship to be an automatic view, based on navigation properties on the constraint classes.

Applies to: RelationshipClass

This CA can be applied to an abstract ECRelationship class which will then attempt to find a matching navigation property on one of the constraint classes and dynamically generate a view query based on that information. Basically turns the relationship into a view.

ImportRequiresVersion Sealed CustomAttributeClass

Causes a schema to only be imported by a specific ECDb version or higher.

Applies to: Schema

The ECDbRuntimeVersion value specifies which ECDb version is required to import this schema. This gets compared to the highest ECDb profile version known to the current ECDb runtime, which may be higher than the currently open file profile version. Older versions of ECDb will refuse to import schemas that have this CA (import will be rejected). If the schema is already in a file, older versions of ECDb are good to use it, if usage of things should be restricted, apply UseRequiresVersion instead.

Example usage:

<?xml version="1.0" encoding="utf-8" ?>
<ECSchema schemaName="Schema1" alias="s1" version="1.0.1" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
    <ECSchemaReference name="ECDbMap" version="02.00.02" alias="ecdbmap"/>
    <ECCustomAttributes>
        <ImportRequiresVersion xmlns="ECDbMap.02.00.02">
            <ECDbRuntimeVersion>4.0.0.5</ECDbRuntimeVersion>
        </ImportRequiresVersion>
    </ECCustomAttributes>
    <ECEntityClass typeName="Foo" >
        <ECProperty propertyName="Length" typeName="double" />
    </ECEntityClass>
</ECSchema>

Properties

Name Description Label Category Read Only Priority
ECDbRuntimeVersion Required. ECDb profile version number e.g. 4.0.0.3. Refers to the runtime version, not the file version. false 0

JoinedTablePerDirectSubclass Sealed CustomAttributeClass

Maps subclasses and their children to a joined table. Can only be applied to classes in a hierarchy using MapStrategy TablePerHierarchy.

Applies to: EntityClass

LinkTableRelationshipMap Sealed CustomAttributeClass

Applies to: RelationshipClass

Properties

Name Description Label Category Read Only Priority
SourceECInstanceIdColumn Optional. If not set, a default column name will be used false 0
TargetECInstanceIdColumn Optional. If not set, a default column name will be used false 0
CreateForeignKeyConstraints Default: true. If set to false, no foreign key constraints are created on the link table. In that case, deleting instance does not delete its relationships in the link table. false 0
AllowDuplicateRelationships Default: false. If set to true duplicate relationships are allowed. false 0

PropertyMap Sealed CustomAttributeClass

Applies to: PrimitiveProperty

Properties

Name Description Label Category Read Only Priority
ColumnName If not specified, the ECProperty name is used. It must follow EC Identifier specification. false 0
IsNullable If false, values must not be unset for this property. false 0
IsUnique Only allow unique values for this property. false 0
Collation Specifies how string comparisons should work for this property. Possible values: Binary (default): bit to bit matching. NoCase: The same as binary, except that the 26 upper case characters of ASCII are folded to their lower case equivalents before comparing. Note that it only folds ASCII characters. RTrim: The same as binary, except that trailing space characters are ignored. false 0

QueryView Sealed CustomAttributeClass

Flags a class as a view based on ECSQL.

Applies to: EntityClass

Allows defining an abstract entity class which is not backed by actual data but rather by an ECSql query which is executed to obtain instances of the class. Please see ECSqlReference for details on how to use views.

A view must return an ECInstanceId and ECClassId.

Example of a schema using a view:

<ECSchema schemaName="TestSchema" alias="ts" version="1.0.0" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
    <ECSchemaReference name='ECDbMap' version='02.00.03' alias='ecdbmap' />
    <ECEntityClass typeName="JsonObject">
        <ECProperty propertyName="json" typeName="string" extendedTypeName="Json" />
    </ECEntityClass>
    <ECEntityClass typeName="Pipe" modifier="Abstract">
        <ECCustomAttributes>
            <QueryView xmlns="ECDbMap.02.00.04">
                <Query>
                    SELECT
                        jo.ECInstanceId,
                        ec_classid('TestSchema', 'Pipe') as [ECClassId]
                        CAST(json_extract(jo.json, '$.diameter') AS INTEGER) [Diameter],
                        CAST(json_extract(jo.json, '$.length') AS INTEGER) [Length],
                        json_extract(jo.json, '$.material') [Material]
                    FROM ts.JsonObject jo
                    WHERE json_extract(jo.json, '$.type') = 'pipe'
                </Query>
            </QueryView>
        </ECCustomAttributes>
        <ECProperty propertyName="Diameter" typeName="int" />
        <ECProperty propertyName="Length"  typeName="int"/>
        <ECProperty propertyName="Material" typeName="string" />
    </ECEntityClass>
</ECSchema>

JsonObject could be filled with this data:

{"type": "pipe", "diameter": 10, "length": 100, "material": "steel"}
{"type": "pipe", "diameter": 15, "length": 200, "material": "copper"}
{"type": "pipe", "diameter": 20, "length": 150, "material": "plastic"}
{"type": "cable", "diameter": 5, "length": 500, "material": "copper","type": "coaxial"}
{"type": "cable", "diameter": 2, "length": 1000, "material": "fiber optic","type": "single-mode"}
{"type": "cable", "diameter": 3, "length": 750, "material": "aluminum","type": "twisted pair"}

Running this query:

SELECT Length, Diameter, Material FROM ts.Pipe

Will return this result:

Length   |Diameter |Material
----------------------------------------
100      |10       |steel
200      |15       |copper
150      |20       |plastic

Properties

Name Description Label Category Read Only Priority
Query ECSql query with only primitive types are allowed false 0

SchemaMap Sealed CustomAttributeClass

Applies to: Schema

Properties

Name Description Label Category Read Only Priority
TablePrefix Specifies a prefix for generated tables. If not specified, the alias of the ECSchema is used false 0

ShareColumns Sealed CustomAttributeClass

Allows to share columns amongst ECProperties. Can only be applied to MapStrategy TablePerHierarchy

Applies to: EntityClass, RelationshipClass

Properties

Name Description Label Category Read Only Priority
ApplyToSubclassesOnly False (Default):Columns are shared for the properties of the ECClass to which this CA is applied and all its subclasses. True: Columns are not shared for this ECClass but for all of its subclasses. false 0
MaxSharedColumnsBeforeOverflow Maximum number of shared columns to use before using an overflow table (optional). If not specified, ECDb will create as many shared columns until the table has 63 columns. false 0

UseRequiresVersion Sealed CustomAttributeClass

Causes ECDb to refuse to query a class which has this CA or a CA that has this CA if conditions are not met.

Applies to: AnyClass

Can be applied to a class which makes queries which use that class require a minimum ECDb or ECSql version. When applied to a custom attribute class, that custom attribute carries the information along to all classes to which it is being applied. (Nesting is also possible).

Applying this to anything other than a relationship, entity or custom attribute class has no effect.

ECSqlVersion specifies the minimum ECSql version which is maintained independend of the ECDb profile version and allows a second mechanism for tracking changes (the sql version is usually incremented more frequently than profile version)

ECSql queries which violate the restrictions set by this CA will fail to prepare and write a message to the ECDb issue reporter.

The use of this CA does not limit which ECDb versions can import the schemas. To restrict import apply the ImportRequiresVersion CA to the schema.

Example usage:

<?xml version="1.0" encoding="utf-8" ?>
<ECSchema schemaName="Schema1" alias="s1" version="1.0.1" xmlns="http://www.bentley.com/schemas/Bentley.ECXML.3.2">
    <ECSchemaReference name="ECDbMap" version="02.00.02" alias="ecdbmap"/>
    <ECCustomAttributeClass typeName="Bar" modifier="Sealed" appliesTo="EntityClass">
        <ECCustomAttributes>
            <UseRequiresVersion xmlns="ECDbMap.02.00.02">
                <ECDbRuntimeVersion>4.0.0.4</ECDbRuntimeVersion>
            </UseRequiresVersion>
        </ECCustomAttributes>
    </ECCustomAttributeClass>
    <ECEntityClass typeName="Foo" >
        <ECCustomAttributes>
            <Bar></Bar>
        </ECCustomAttributes>
        <ECProperty propertyName="Length" typeName="double" />
    </ECEntityClass>
</ECSchema>

Example for directly applying this to an entity class, restricting its ECSql version:

<ECEntityClass typeName="Foo" >
    <ECCustomAttributes>
        <UseRequiresVersion xmlns="ECDbMap.02.00.02">
            <ECSqlVersion>1.0.0.0</ECSqlVersion>
        </UseRequiresVersion>
    </ECCustomAttributes>
    <ECProperty propertyName="Length" typeName="double" />
</ECEntityClass>

<ECEntityClass typeName="Bar">
    <BaseClass>Foo</BaseClass>
</ECEntityClass>

Class Bar in the example above will also be affected by the restriction since it derives from Foo.

Properties

Name Description Label Category Read Only Priority
ECDbRuntimeVersion Optional. ECDb profile version number e.g. 4.0.0.3. Refers to the runtime version, not the file version. false 0
ECSqlVersion Optional. EC SQL profile version number e.g. 1.2.0.0. false 0

Last Updated: 15 May, 2024