Standard Filtering Capabilities
The AEC Data Model API provides a set of standard filtering options to enable filtering expressions as a core capability. They provide a simpler method for applying commonly-used filters, and can be used either as an alternative to or combined with Advanced Filtering Capabilities RSQL. These standard filtering options are available for ElementGroup and Element queries.
Supported Filtering Options
Following are the standard filtering options supported in AEC Data Model GraphQL ElementGroup queries:
Fields | Type of params | Sample ElementGroup Query Filter | Expected Response |
---|---|---|---|
Name | String | “name”: “Snowdon Towers Sample | Returns elementGroups with name “Snowdon Towers Sample Architectural.rvt |
fileUrn | String | “fileUrn”: “urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ” | Returns elementGroups with file URN “urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ” |
createdBy | String | “createdBy”: “first.last@autodesk.com” | Returns elementGroups created by the user with email “johndoer@autodesk.com” |
lastModifiedBy | String | “lastModifiedBy”: “first.last@autodesk.com” | Returns elementGroups that were last modified by the user with email “johndoer@autodesk.com” |
Following are the standard filtering options supported in AEC Data Model GraphQL Elements queries:
Fields | Type of params | Sample Element Query Filter | Expected Response | |
---|---|---|---|---|
Name | String | “name”: “2.5" x 5" rectangular (Orange)” |
Returns elements with name “2.5" x 5" rectangular (Orange)” | |
nameWithComparator | { “value”: String, “comparator”: Enum } | “nameWithComparator”: { “value”: “Wall”, “comparator”: “CONTAINS” } |
Returns elements whose name contains the string “Wall” | |
properties |
{ “name”: String, “value”: String, “valueWithComparator”: { “value”: String, “comparator”: Enum } } |
“properties”: { “name”: “Element Context”, “value”: “Instance” } |
Returns elements that are instances | |
“properties”: { “name”: “Family Name”, “valueWithComparator”: { “value”: “Main”, “comparator”: “STARTS_WITH” } } |
Returns elements with a “Family Name” that starts with the string “Main” | |||
{ “id”: String, “value”: String, “valueWithComparator”: { “value”: String, “comparator”: Enum } } |
“properties”: { “id”: “autodesk.revit.parameter:parameter.elementContext-1.0.0”, “value”: “Instance” } |
Returns elements that are instances | ||
“properties”: { “id”: “autodesk.revit.parameter:parameter.elementContext-1.0.0”, “valueWithComparator”: { “value”: “Instance”, “comparator”: “NOT_EQUAL” } } |
Returns elements that are NOT instances | |||
references | { “name”: String, “referenceId”: String } | “references”: { “name”: “Type”, “referenceId”: “YWVjZX5JR1TYdWROM2Qxd” } |
Returns elements with a “Type” reference to the element with id “YWVjZX5JR1TYdWROM2Qxd” | |
CreatedBY | String | “createdBy”: “john.doer@autodesk.com” |
Returns elements created by the user with email “john.doer@autodesk.com” | |
lastModifiedBy | String | “lastModifiedBy”: “john.doer@autodesk.com” |
Returns elements that were last modified by the user with email “john.doer@autodesk.com” | |
elementId |
String |
“elementId”: “YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ34xQ1dia2xtV1JTcTJ4bklhdkN4YzhRXzEw” |
Returns elements with id: “YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ34xQ1dia2xtV1JTcTJ4bklhdkN4YzhRXzEw” |
|
revitElementId | String | “revitElementId”: “1055109” |
Returns elements with specified Revit Element Id: “1055109” |
NOTE: The comparator Enum can be one of: CASE_SENSITIVE, CONTAINS, STARTS_WITH, ENDS_WITH, GREATER_THAN, GREATER_THAN_EQUAL_TO, LESS_THAN, LESS_THAN_EQUAL_TO, or NOT_EQUAL.
Compound Filtering Options
When multiple convenience fields are provided, the AND operator will be used to compare across fields.
NOTE: having multiple properties or references with different names are considered to be different fields. This can be done by defining an array of properties or references, with each property or reference having a different name/id.
Query Type | Sample Element Query Filter | Expected Response |
---|---|---|
ElementGroup |
“name”: “Tower Blueprints.rvt”, “createdBy”: “first.last@autodesk.com” |
Returns elementGroups with name “Tower Blueprints.rvt” and created by the user with email “first.last@autodesk.com” |
Element |
“name”: “HVAC Feed”, “properties”: [{ “name”: “Family Name”, “value”: “Linear - 3/32" Trebuchet MS” }, { “id”: “autodesk.revit.parameter:parameter.elementContext-1.0.0”, “value”: “Type”}] |
Returns elements with name “HVAC Feed”, part of the “Linear - 3/32" Trebuchet MS” family, and are types |
The convenience fields can be used alongside RSQL to perform more powerful queries. (To see how the use the query field, refer to Advanced Filtering Capabilities RSQL).
Query Type | Sample Element Query Filter | Expected Response |
---|---|---|
Element |
“name”: “Middle Flooring”, “query”: “property.name.Length >= 2.0” |
Returns elements with name “Middle Flooring” and property “Length” having
|
Matching Multiple Values
When multiple values for a single field are provided, the OR operator will be used to compare within the same field. This is useful when there are multiple acceptable values for a field. In these cases, provide a [String] as params instead of a single String.
Query Type | Sample Element Query Filter | Expected Response |
---|---|---|
ElementGroup |
“createdBy”: [”first.last@autodesk.com”, “test@autodesk.com”] |
Returns elementGroups created by the user with email “first.last@autodesk.com”” or with email “test@autodesk.com” |
Element |
“createdBy”: [”john.doer@autodesk.com”, “test@autodesk.com”], “lastModifiedBy”: “john.doer@autodesk.com” |
Returns elements created by the user with email “test@autodesk.com”” or with email “test@autodesk.com”, and last modified by the user with email “first.last@autodesk.com” |
NOTE: all String fields can accept a [String] instead, with the exception of property name, property id, reference name, and valueWithComparator value (see Compound Filters section). The nameWithComparator field can accept an array of name-comparator pairs as well, with each pair considered to be within the same field.
Standard Filtering Equivalent of RSQL
For reference, the following are the convenience field equivalents of some common RSQL filters:
RSQL Filter | Standard Field Filter |
---|---|
“metadata.name==x” | “name”: “x” |
“metadata.fileUrn==x” | “fileUrn”: “x” |
“metadata.createdBy.email==x” | “createdBy”: “x” |
“metadata.lastModifiedBy.email==x” | “lastModifiedBy”: “x” |
“metadata.elementId==x” | “elementId”: “x” |
“property.name.<y>==x” | “properties”: [{ “name”: “y”, “value”: “x” }] |
“property.id.<y>==x” | “properties”: [{ “id”: “y”, “value”: “x” }] |
“reference.<y>==x” | “references”: [{ “name”: “y”, “referenceId”: “x” }] |
Sample Queries
Querying for all elements that contain the word Pipes in their name:
{
...,
"filter": {
"nameWithComparator": {"name": "Pipes", "comparator": "CONTAINS"}
...
}
Querying all elements that have the following criteria:
- Named 2.5" x 5" rectangular (Orange)
- Are instances. This example uses the property id (autodesk.revit.parameter:parameter.elementContext-1.0.0), but the property name can be supplied instead
- Are part of the Rectangular Mullion family. The example uses the property name (Family Name), but the property id can be supplied instead
- Have a “Type” reference with the element with id YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ351LW5jRFM3Z1E2R2hwQjNyZ1pYS2VRX2UzPLIz
- Were created by user first.last@autodesk.com
{
...,
"filter": {
"name": "2.5\" x 5\" rectangular (Orange)"
"properties": [
{ "name": "Family Name", "value": "Rectangular Mullion" }
{ "id": "autodesk.revit.parameter:parameter.elementContext-1.0.0", "value": "Instance" }
]
"references": { "name": "Type", "referencedId": "YWVjZX5JR0JWdWROM2QxdW1kTkJZRnR2ZlpBX0wyQ351LW5jRFM3Z1E2R2hwQjNyZ1pYS2VRX2UzPLIz" }
"createdBy": "first.last@autodesk.com"
},
...
}
Special Considerations for ElementGroup Filters
fileUrn:
This filter can only be used by itself and not be used in combination with any other filter.
Accepted Sample Query:
{
...,
"filter": {
"fileUrn": ["urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ", "urn:adsk.wipstg:dm.lineage:R8YVGN61QDaLElL0YSfkKg"]
...
}
Rejected Sample Query:
{
...,
"filter": {
"fileUrn": "urn:adsk.wipstg:dm.lineage:u-ncDS7gX3ZhpB3rgZXKeQ",
"createdBy": "first.last@autodesk.com"
...
}
name:
This filter can only be used with one value and can not support multiple values.
Accepted Sample Query:
{
...,
"filter": {
"name": "Snowdon Towers East.rvt",
"createdBy": "first.last@autodesk.com"
...
}
Rejected Sample Query:
{
...,
"filter": {
"name": ["Snowdon Towers East.rvt", "Snowdon Towers West.rvt"]
...
}