Advanced Filtering Capabilities
The filtering expressions utilized by the Data Exchange GraphQL API are inspired 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 Data Exchange GraphQL API endpoints require filter expressions similar to RSQL.
For more information, see RSQL grammar and syntax.
The advantages of using RSQL are highlighted as follows:
- Offers a simple and easily understandable approach for defining query filters.
- Enhances the effectiveness of complex query definitions when compared to other query languages like GraphQL.
- Allows for extension by incorporating custom operators to meet specific requirements.
Supported operators
Following are the operators supported in Data Exchange GraphQL queries, with some examples:
Actors |
Type of params |
Operation |
Operator |
Note |
|---|---|---|---|---|
Property name-value |
String |
Equality (case-insensitive): |
== |
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 “‘property.name.Element Name’==’Concrete, Precast Smooth, Light Grey’” “property.name.category==’Slab Edges’”. |
| Number | ==, !=, <, >, <=, >= | |||
| Boolean | Equality | == | ||
| Property Name | String | Exact match | == | |
Metadata (exchanges, elements) |
Name |
== |
||
Compound operations
Currently, we are supporting AND and OR compound operations.
Examples:
- ‘property.name.category’==’Pipes’ and ‘property.name.Element Name’==’HVAC FM Boiler Feed’
- (property.name.category==Walls or property.name.category==Windows) and property.name.Length>5.0
Examples
The following table illustrates how to use RSQL to filter queries based on different filter types.
| Filter type | Query | Expectation |
|---|---|---|
Property exists |
“elementFilter”: { “query”: “property.name==Perimeter” } |
Returns elements those have “Perimeter” property (case-sensitive). |
By name and value |
“elementFilter”: { “query”: “property.name.category==Walls” } |
Returns elements those have property “category”. that has value “Walls” (case-sensitive) |
By multiple values |
“elementFilter”: { “query”: “‘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 case-sensitive) |
By metadata (elements) |
“elementFilter”: { “query”: “metadata.id=in=(‘ID_1’, ‘ID_2’)” } |
Returns elements with id either “ID_1” or “ID_2” or both. (This filter is incompatible with the combination of other filters) |
By metadata (elements) |
“elementFilter”: { “query”: “metadata.name==’HVAC Feed’” } |
Returns elements with name “HVAC Feed”. |
By metadata (exchange) |
“exchangeFilterInput” : { “query”: “version.fromId==’latest-1’ and version.toId==’latest’” } |
Returns exchange and its elements in the provided range, for example, latest-1 to latest. (Only latest-1 to latest is supported currently.) |
By range |
“elementFilter”: { “query”: “property.name.area >= 100.0 and property.name.area < 200.0” } |
Returns elements with property area in the provided range. |
