Creates a group. A group is a collection of design elements from an iModel represented by an ECSQL query. When used for reporting a group represents a single output data table in a report. There are two ways to create a group.
Create a group without properties
To create a group without properties do not provide the source
property.
Create a group from an existing group
To create a group from another group provide the source
property. The server will create a new group and copy over all properties from the group referenced by the source
property. User must have imodels_read
permissions to the iModel containing the source group. Changing source group or its properties will not change the copies of them.
Provided groupName
, description
, query
, metadata
request body properties will overwrite the properties on the copied group.
Note
The query
request body property must be provided even when copying a group. Provide the source group query in the request when copying a group if you want to keep the same query.
Group Query
The query
parameter of a Group must be a valid ECSQL query.
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
. However, it is recommended to always select at least ECInstanceId
and ECClassId
columns.
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, ECClassId FROM bis.Element
is a valid query- Assuming that class
Building.Beam
is a descendant of the classbis.Element
, the querySELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect
is valid
In all other cases the provided ECSQL query is required to select ECInstanceId
and ECClassId
. If ECClassId
is omitted, the service assumes that query selects elements from the bis.Element
class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying bis.ElementAspect
but you only select ECInstanceId
so the service only selects the elements that have a matching ECInstanceId
. Because of this it is always recommended to select both ECInstanceId
and 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 properties of groups with the same name. The result rows will be concatenated one after another. If groups are overlapping and multiple groups select the same element the result will contain duplicates.
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 iTwin 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 iTwin 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}.
Was this page helpful?