Request

Response

    Beta APIs are subject to change. Please avoid using them in production environments.

    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 typeQueryExpectation

    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.