Gets a Group for a Mapping.
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_read
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.
Request parameters
The iModel Id.
The Mapping Id.
The Group Id.
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v1+json
is recommended.
Response 200 OK
Retrieved a Group successfully.
{ "group": { "id": "08f252c4-ee78-4e2b-9280-f7365400b932", "groupName": "Physical elements", "description": "A group of physical elements", "query": "SELECT * FROM BisCore.PhysicalElement", "_links": { "imodel": { "href": "https://api.bentley.com/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a" }, "mapping": { "href": "https://api.bentley.com/insights/reporting/datasources/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a/mappings/f1fe5959-35ab-467e-83b8-a679b722d80f" } } } }
Response 401 Unauthorized
This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
Specified Group was not found.
{ "error": { "code": "GroupNotFound", "message": "Requested Group is not available.", "target": "id" } }
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
Response headers
The number of requests exceeds the rate-limit for the client subscription.
Group
Defines a single Group (collection of iModel elements) in an iModel Mapping.
The Group Id.
Name of the Group (OData v4 SimpleIdentifier).
Description of the Group.
Query string that will be executed against the target iModel to build this Group.
{ "title": "Group", "type": "object", "description": "Defines a single Group (collection of iModel elements) in an iModel Mapping.", "properties": { "id": { "type": "string", "description": "The Group Id." }, "groupName": { "type": "string", "description": "Name of the Group (OData v4 SimpleIdentifier)." }, "description": { "type": "string", "description": "Description of the Group." }, "query": { "type": "string", "description": "Query string that will be executed against the target iModel to build this Group." }, "_links": { "type": "object", "description": "Contains contextual hyperlinks to related data.", "properties": { "imodel": { "$ref": "#/components/schemas/Link", "description": "URL pointing to the related iModel." }, "mapping": { "$ref": "#/components/schemas/Link", "description": "URL pointing to the related Mapping." } } } }, "additionalProperties": false }
Group Response
Container for a Group object.
{ "title": "Group Response", "type": "object", "description": "Container for a Group object.", "properties": { "group": { "$ref": "#/components/schemas/Group", "description": "Group properties." } }, "additionalProperties": false }
Link
Hyperlink container.
Hyperlink to the specific entity.
{ "title": "Link", "type": "object", "description": "Hyperlink container.", "properties": { "href": { "type": "string", "description": "Hyperlink to the specific entity." } }, "additionalProperties": false }
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "type": "object", "description": "Contains error information.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error.", "nullable": true } }, "required": [ "code", "message" ], "additionalProperties": true }
Error Response
Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.
{ "type": "object", "title": "Error Response", "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.", "properties": { "error": { "description": "Error information.", "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "additionalProperties": false }
Was this page helpful?