Advanced Filtering Using RSQL
AEC Data Model API’s filtering expressions are influenced by the RESTful Service Query Language (RSQL), which is used to define filter expressions to limit the results for REST endpoints. The filter query string parameters used with the AEC Data Model API endpoints require filter expressions similar to RSQL.
For more information, see RSQL grammar and syntax.
Benefits of using RSQL are listed as follows:
- Provides a simple and easily understandable method of defining query filters.
- Makes complex query definitions more effective than the other query languages such as GraphQL.
- Can be extended using custom operators.
Supported operators
Following are the operators supported in AEC Data Model GraphQL queries, with some examples:
Actors |
Type of params |
Operation |
Operator |
Note |
---|---|---|---|---|
property name-value |
String |
Equality (case-insensitive): Equality (case-sensitive) |
== =caseSensitive= |
When comparing values or keys that contain spaces, it is necessary to enclose both the left-hand side (LHS) and the right-hand side (RHS) in single quote
|
InEquality | != | |||
contains, startsWith, endsWith | =contains=, =startsWith=, =endsWith= | |||
number, DateTime | ==, !=, <, >, <=, >= | Float comparison values need to be specified using decimal digits. | ||
Boolean |
Equality | == | ||
Inequality | != | |||
property name | String | Exact match | == | |
property id-value |
String |
Equality (case-insensitive): Equality (case-sensitive) |
== =caseSensitive= |
Properties with enum values can be searched by property id-value, where the value must be provided as the exact name of the enum
|
InEquality | != | |||
contains, startsWith, endsWith | =contains=, =startsWith=, =endsWith= | |||
number, DateTime | ==, !=, <, >, <=, >= | Float comparison values need to be specified using decimal digits. | ||
Boolean |
Equality | == | ||
Inequality | != | |||
property id | String | Exact match | == | |
metadata (On elementGroups) |
DateTime |
==, !=, <, >, <=, >= |
Supported ISO 8601 formats (precision supported up to seconds):
|
|
Compound operations
Following is the list of supported compound operators, such as AND and OR operations:
- ‘property.name.category’=contains=’Pipes’ and ‘property.name.Element Name’=contains=’HVAC FM Boiler Feed’.
- Order of operations is Supported
- (property.name.category==Walls or property.name.category==Windows) and property.name.Length>5.0.
Examples
Following filters are supported for all elements queries:
Filter type | Query | Expectation |
---|---|---|
Property exists by name | “property.name==Perimeter” | Returns elements with Perimeter property (case-sensitive). |
Property does not exist by name | “property.name!=Perimeter” | Returns elements without the property Perimeter (case-sensitive). |
By range | “property.name.area >= 100 and property.name.area < 200” | Returns elements with property area in the provided range. |
By name and value | “property.name.category==Area” | Returns elements with the property category equal to Area (case-insensitive). |
“‘property.name.Element Name’==’HVAC Feed’” | Returns elements with name “HVAC Feed” (case insensitive). | |
“property.name.Length >= 2.0 | Returns elements with property Length having values greater or equal to 2.0. | |
By multiple values | “‘property.name.Family Name’==’Rectangular Mullion’ or ‘property.name.Family Name’==’Window-Fixed’” | Returns elements with property “Family Name” having values “Rectangular Mullion” or “Window-Fixed”. (all value comparisons are not case-sensitive). |
Property exists by id | “property.id==autodesk.revit.parameter:curveElemLength-1.0.0” | Returns elements with property of id “autodesk.revit.parameter:curveElemLength-1.0.0”. |
By id and value | “property.id.autodesk.revit.parameter:curveElemLength-1.0.0>3.0” | Returns elements with property of id “autodesk.revit.parameter:curveElemLength-1.0.0” having values greater than 3.0 |
“property.id.autodesk.revit.parameter:parameter.elementContext-1.0.0==Instance” | Returns elements with property of id “autodesk.revit.parameter:parameter.elementContext-1.0.0” with value “Instance” | |
By metadata (elements) | “metadata.createdBy.email== First.Last@autodesk.com” | Returns elements with the createdBy user metadata with the email address. |
“metadata.lastModifiedBy.email== First.Last@autodesk.com” | Returns elements with the lastModifiedBy user metadata with the email address. | |
“metadata.elementId==’YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ34xQ1dia2xtV1JTcTJ4bklhdkN4YzhRXzEw’” | Returns elements with id “YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ34xQ1dia2xtV1JTcTJ4bklhdkN4YzhRXzEw” | |
“metadata.revitElementId==’1055109’” | Returns elements with specified Revit Element Id: “1055109” | |
Inequality | “property.name.room!=1” | Returns elements of property “room” that does not have value 1. |
Wild card (starts with) | “property.name.room=startsWith=boiler” | Returns elements that have property name “room” beginning with value “boiler” (case-sensitive) |
by metadata, where Date/Time is greater than,less than or range |
“metadata.createdOn>=2020-01-20T14:00:00Z and metadata.createdOn<2020-12-20T14:00:00Z” | Returns elements with createdOn metadata in the provided range |
“metadata.lastModifiedOn>2020-01-01T01:00:00Z and metadata.lastModifiedOn<2020-12-01T01:00:00Z” | Returns elements with lastModifiedOn metadata in the provided range |
Following filters are only supported for getting elements in an elementGroup:
Filter type | Query | Expectation |
---|---|---|
Wild card (ends with and contains) | “property.name.room=endsWith=boiler” “property.name.room=contains=Fire | Returns elements which have property name “room” ending with value “boiler” (case insensitive). Returns elements which have property “room” containing value “Fire” (case insensitive) |
case-sensitivity | “property.name.comment=caseSensitive=Vertical” | Returns elements which have property “comment” with value “Vertical” (case-sensitive check on “Vertical”) |
Following filters are supported for all elementGroups queries:
Filter type | Query | Expectation |
---|---|---|
By metadata (elementGroups) | “metadata.createdOn>=2020-01-20T14:00:00Z and metadata.createdOn<2020-12-20T14:00:00Z” | Returns elementGroups with createdOn metadata in the provided range. |
“metadata.lastModifiedOn>2020-01-01T01:00:00Z and metadata.lastModifiedOn<2020-12-01T01:00:00Z” | Returns elementGroups with lastModifiedOn metadata in the provided range. | |
“metadata.createdBy.email== First.Last@autodesk.com” | Returns elementGroups with the createdBy user metadata with the email address. | |
“metadata.lastModifiedBy.email== First.Last@autodesk.com” | Returns elementGroups with the lastModifiedBy user metadata with the email address. | |
“metadata.name==’Snowdon Towers Sample Architectural.rvt’” | Returns elementGroups with name “Snowdon Towers Sample Architectural.rvt” | |
“metadata.fileUrn==’urn:adsk.wipprod:dm.lineage:mgQk-s7vRy2I6BL7Ed1IYw’” | Returns elementGroups with specified file urn. |
Special Considerations for ElementGroup Filters
metadata.fileUrn:
This filter can only be used by itself and not be used in combination with any other filter.
Accepted Sample Query:
{
...,
"filter": {
"query": "metadata.fileUrn=='urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ' or metadata.fileUrn=='urn:adsk.wipstg:dm.lineage:R8YVGN61QDaLElL0YSfkKg'"
...
}
Rejected Sample Query:
{
...,
"filter": {
"query": "metadata.fileUrn=='urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ' and metadata.createdBy.email=='first.last@autodesk.com'"
...
}
{
...,
"filter": {
"query": "metadata.fileUrn=='urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ'"
"createdBy": "first.last@autodesk.com"
...
}
metadata.name:
- This filter can only be used with one value and can not support multiple values (including coupling with convenience filter for name).
- This filter can not be used with ORs, only ANDs are supported.
Accepted Sample Query:
{
...,
"filter": {
"query": "metadata.name=='Snowdon Towers East.rvt' and metadata.createdBy.email=='first.last@autodesk.com'"
...
}
{
...,
"filter": {
"query": "metadata.name=='Snowdon Towers East.rvt'",
"createdBy": "first.last@autodesk.com"
...
}
Rejected Sample Query:
{
...,
"filter": {
"query": "metadata.name=='Snowdon Towers East.rvt'",
"name": "Snowdon Towers West.rvt"
...
}
{
...,
"filter": {
"query": "metadata.name=='Snowdon Towers East.rvt' or metadata.createdBy.email=='first.last@autodesk.com'"
...
}