Creates a Group for an iModel data source Mapping. A Group is a collection of design elements from an iModel represented by an ECSQL query and defines one table in the output data of a report.
Group Query
The query
parameter of a Group supports ECSql and ECClassIds.
If a valid ECSql query is given and the selected class is bis.Element
, or if it is a descendant of the class bis.Element
, the only required column is ECInstanceId
.
SELECT * FROM bis.Element
is a valid query- Assuming that class
Building.Beam
is a descendant of the classbis.Element
, the querySELECT * FROM Building.Beam
is a valid query SELECT ECInstanceId FROM bis.Element
is a valid query- Assuming that class
Building.Beam
is a descendant of the classbis.Element
, the querySELECT ECInstanceId FROM Building.Beam
is valid SELECT ECClassId FROM bis.Element
is not a valid query because ECInstanceId column is missing- Assuming that class
Building.Beam
is a descendant of the classbis.Element
, the querySELECT ECClassId FROM Building.Beam
is not valid because ECInstanceId column is missing - Assuming that
Building.BeamAspect
is an aspect, the querySELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId
is not valid because the selectedECInstanceId
is of the aspect, not the element - Assuming that
Building.BeamAspect
is an aspect, the querySELECT A.Element.id FROM Building.BeamAspect
is not valid because the selected column's name is notECInstanceId
- Assuming that
Building.BeamAspect
is an aspect, the querySELECT A.Element.id ECInstanceId FROM Building.BeamAspect
is valid
In all other cases when providing an ECSql query it is required to select ECInstanceId
, ECClassId
, and all other columns that you are planning to use for mapping. If only ECInstanceId
and ECClassId
are selected and other columns are used for mapping, those columns will be filled with null
values. If either ECInstanceId
or ECClassId
column is not selected, the query will not produce any output.
If the query
parameter does not contain a valid ECSql query, then it must be equal to bis.Element
, bis.ElementAspect
, or any of their descendants.
The ECClassId format {schemaName}:{schemaItemName}
where schemaName
does not contain a 3-part version number is supported.
The ECClassId format {schemaName}.{schemaItemName}
is supported.
The ECClassId format {schemaAlias}:{schemaItemName}
where schemaAlias
is the alias of a schemaName
is supported.
The ECClassId format {schemaFullName}:{schemaItemName}
where schemaFullName
contains a 3-part version number is not supported.
When the given ECClassId is equal to bis.Element
or is one of its descendants, then all elements with the ECClassId will be selected.
When the given ECClassId is equal to bis.ElementAspect
or is one of its descendants, then all elements that have such aspect will be selected.
When the given ECClassId is none of the above, the query will not produce any output.
- If a class
Building.Beam
does not have any subclasses and thequery
parameter is set toBuilding.Beam
, then all elements with ECClassIds ofBuilding.Beam
will be selected - If there is a class
Building.StructuralMember
which has 2 subclassesBuilding.Beam
andBuilding.Column
, and thequery
parameter is set toBuilding.StructuralMember
, then all elements with ECClassIds ofBuilding.StructuralMember
,Building.Beam
, andBuilding.Column
will be selected - If a class
Building.BeamAspect
inherits from a classbis.ElementAspect
(is unique or multi aspect) and thequery
parameter is set toBuilding.BeamAspect
, then all elements that have aBuilding.BeamAspect
attached to them will be selected. This query will not select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId - If there is class
Building.StructuralMemberAspect
which has 2 subclassesBuilding.BeamAspect
andBuilding.ColumnAspect
, theBuilding.StructuralMemberAspect
class inherits from a classbis.ElementAspect
(is unique or multi aspect) and thequery
parameter is set toBuilding.StructuralMemberAspect
, then all elements that haveBuilding.StructuralMemberAspect
,Building.BeamAspect
, orBuilding.ColumnAspect
attached to them will be selected. This query will not select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.
Authentication
Requires Authorization
header with valid Bearer token for scope itwin-platform
.
For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.
Authorization
User must have imodels_write
permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.
Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.
An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.
Rate limits
All iTwin Platform API operations have a rate limit. For more documentation on that visit Rate limits and quotas page.
"Try it out" Limitations
When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.