Request

Response

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

    Retrieve Elements by Category and Property Name and Value

    In this tutorial, you will learn how to retrieve a list of elements in an exchange, filter them based on a category and Property Name and Value.

    By the end of this tutorial, you will be able to:

    • Retrieve a list of elements in an exchange.
    • Apply complex filters on elements and retrieve all of its properties.

    You will use the following queries in this tutorial:

    TypeOperationDescription
    Query exchange Retrieves a list of elements in an exchange.

    Step 1 - Request a list of Elements which belongs to the “Walls” category and whose area is greater than 10

    The following steps demonstrate how you can run the exchange query to retrieve a list of Elements of an Exchange.

    1. Enter the following query in the Query Pane of the Data Exchange Explorer.

      Query

      query GetWallElementWithAreaGreaterThan10(
          $exchangeId: ID!
          $elementFilter: ElementFilterInput
          $elementPagination: PaginationInput
      ) {
          exchange(exchangeId: $exchangeId) {
              id
              name
              elements(filter: $elementFilter, pagination: $elementPagination) {
                  pagination {
                      pageSize
                      cursor
                  }
                  results {
                      id
                      name
                      properties {
                          results {
                              name
                              value
                          }
                      }
                  }
              }
          }
      }
      
      Show More
    2. In the Query Variables pane, enter the value of the exchangeId. To know how to obtain the exchangeId, refer Navigate to Exchanges within a Folder.

      Assign elementFilter with the category of your choice. For this exercise, we will assign category as “property.name.category==Walls” and Area is greater than 10.0

      Note: Refer to the Advanced Filtering Capabilities page to see the list of supported filtering options.

      Additionally, set the pagination limit to any required value. You can traverse to subsequent pages by setting the cursor to the value returned in cursor field in the response.

      Query Variables

      {
          "exchangeId": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjkwMGM5ODY1LWI2ZmMtMzI0Ny04NWUxLTgxMmZhOGY1ZTJkNA",
          "elementFilter": {
              "query": "property.name.category==Walls and property.name.Area>10.0"
          },
          "elementPagination": {
              "limit": 2,
              "cursor": ""
          }
      }
      
      Show More
    3. Click Play. A list of elements whose category is “Walls” and Area greater than “10.0” is displayed in the response.

      Response

      {
          "data": {
              "exchange": {
                  "id": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjkwMGM5ODY1LWI2ZmMtMzI0Ny04NWUxLTgxMmZhOGY1ZTJkNA",
                  "name": "SHARE -Multi-Fam Apt-Wing 2",
                  "elements": {
                      "pagination": {
                          "pageSize": 2,
                          "cursor": "4499e1db-b090-4194-a703-88c787e7339d"
                      },
                      "results": [
                          {
                              "id": "0035F6FC1E195ECB479AC714FB33DAC21E7A3AC5",
                              "name": "2212392",
                              "properties": {
                                  "results": [
                                      {
                                          "name": "Cross-Section",
                                          "value": 1
                                      },
                                      {
                                          "name": "Area",
                                          "value": 16.898064740675814
                                      },
                                      {
                                          "name": "Element Name",
                                          "value": "I - GYP BD 5/8 / MS 1 5/8"
                                      },
                                      {
                                          "name": "Family Name",
                                          "value": "Basic Wall"
                                      },
                                      {
                                          "name": "FIRE RATING (HR)",
                                          "value": 0.5
                                      },
                                      {
                                          "name": "Export to IFC",
                                          "value": 0
                                      },
                                      {
                                          "name": "Revit Category Type Id",
                                          "value": "Walls"
                                      },
                                      {
                                          "name": "Phase Created",
                                          "value": "New Construction"
                                      },
                                      {
                                          "name": "family",
                                          "value": "Basic Wall"
                                      },
                                      {
                                          "name": "category",
                                          "value": "Walls"
                                      },
                                      {
                                          "name": "Length",
                                          "value": 5.40544796403661
                                      },
                                      {
                                          "name": "Volume",
                                          "value": 0.965724399929636
                                      },
                                      {
                                          "name": "Operation",
                                          "value": "INSERT"
                                      }
                                  ]
                              }
                          },
                          {
                              "id": "0064BAE03728FED3C1866DBEEA90D2A4639629B3",
                              "name": "4245328",
                              "properties": {
                                  "results": [
                                      {
                                          "name": "Area",
                                          "value": 17.279965440024778
                                      },
                                      {
                                          "name": "type",
                                          "value": "I - GYP BD 5/8 / MS 1 5/8"
                                      },
                                      {
                                          "name": "Base is Attached",
                                          "value": false
                                      },
                                      {
                                          "name": "Element Name",
                                          "value": "I - GYP BD 5/8 / MS 1 5/8"
                                      },
                                      {
                                          "name": "Family Name",
                                          "value": "Basic Wall"
                                      },
                                      {
                                          "name": "Structural",
                                          "value": false
                                      },
                                      {
                                          "name": "Room Bounding",
                                          "value": true
                                      },
                                      {
                                          "name": "Phase Created",
                                          "value": "New Construction"
                                      },
                                      {
                                          "name": "family",
                                          "value": "Basic Wall"
                                      },
                                      {
                                          "name": "category",
                                          "value": "Walls"
                                      }
                                  ]
                              }
                          }
                      ]
                  }
              }
          }
      }
      
      Show More

    Once the query runs successfully, your explorer should resemble the following image.

    ../../../../_images/Advanced_Queries-Task-3.png