Request

Response

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

    Retrieve Element Properties and Associated Reference Properties such as typeProperties

    In this tutorial, you will learn how to retrieve a list of elements in an exchange, filter them based on property name type and fetch reference properties of that element.

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

    • Retrieve a list of elements of a specified property name type from the exchange.
    • Apply filters on elements and retrieve its reference properties, like typeProperties.

    You will use the following queries in this tutorial:

    TypeOperationDescription
    Query GetElementsByExchangeId Retrieves a list of elements in an exchange by using the element ID.

    Step 1 - Request a list of Elements of a specified property from the exchange and also retrieve its reference properties

    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 GetReferenceElementsByExchangeId(
          $exchangeId: ID!
          $elementFilter: ElementFilterInput
          $elementPagination: PaginationInput
      ) {
          exchange(exchangeId: $exchangeId) {
              id
              name
              elements(filter: $elementFilter, pagination: $elementPagination) {
                  pagination {
                      pageSize
                      cursor
                  }
                  results {
                      id
                      name
                      properties(filter: { names: ["category", "type", "Element Name"] }) {
                          results {
                              name
                              value
                          }
                      }
                      references {
                          results {
                              name
                              value {
                                  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.
    3. Assign elementFilter with the category of your choice. For this exercise, we will assign category as “property.name.category==Windows”.
    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==Windows"
        },
        "elementPagination": {
            "limit": 1
        }
    }
    
    Show More
    1. Click Play. The query will return a list of elements of “category” “Windows” along with their specific properties. These elements will be displayed along with their specific properties like “category”, “type”, and “name”. The query will also fetch associated reference properties for these elements.

    For example, if you are looking for type reference properties of elements. You can find them in response with reference named as Type.

    Response

    {
        "data": {
            "exchange": {
                "id": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjkwMGM5ODY1LWI2ZmMtMzI0Ny04NWUxLTgxMmZhOGY1ZTJkNA",
                "name": "SHARE -Multi-Fam Apt-Wing 2",
                "elements": {
                    "pagination": {
                        "pageSize": 1,
                        "cursor": "70df33f1-8514-4a2e-89ba-1bccf287aacf"
                    },
                    "results": [
                        {
                            "id": "00F20DEBD19DDCE9130ED15C3C4DF92FB01B63DF",
                            "name": "1175245",
                            "properties": {
                                "results": [
                                    {
                                        "name": "type",
                                        "value": "01"
                                    },
                                    {
                                         "name": "Element Name",
                                         "value": "01"
                                    },
                                    {
                                        "name": "category",
                                        "value": "Windows"
                                    }
                                ]
                            },
                            "references": {
                                "results": [
                                    {
                                        "name": "Host Id",
                                        "value": {
                                            "id": "3E5589CF107DC161B5B2D8AD1EECBFE9B8BDCC3C",
                                            "name": "707055",
                                            "properties": {
                                                "results": [
                                                    {
                                                        "name": "Area",
                                                        "value": 298.1054587020523
                                                    },
                                                    {
                                                        "name": "type",
                                                        "value": "X - FMP 3/4 + AIR 1 1/2 + RIGID 3 _ GYP SHTG 5/8 + MS 6 _ GYP BD 5/8 (VERT)"
                                                    },
                                                    {
                                                        "name": "Base is Attached",
                                                        "value": false
                                                    },
                                                    {
                                                        "name": "Element Name",
                                                        "value": "X - FMP 3/4 + AIR 1 1/2 + RIGID 3 _ GYP SHTG 5/8 + MS 6 _ GYP BD 5/8 (VERT)"
                                                    },
                                                    {
                                                        "name": "Family Name",
                                                        "value": "Basic Wall"
                                                    },
                                                    {
                                                        "name": "Revit Category Type Id",
                                                        "value": "Walls"
                                                    },
                                                    {
                                                        "name": "family",
                                                        "value": "Basic Wall"
                                                    },
                                                    {
                                                        "name": "category",
                                                        "value": "Walls"
                                                    },
                                                    {
                                                        "name": "Length",
                                                        "value": 34.92499587150709
                                                    },
                                                    {
                                                        "name": "Volume",
                                                        "value": 93.00784049825333
                                                    },
                                                    {
                                                        "name": "Operation",
                                                        "value": "INSERT"
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    {
                                        "name": "To Room",
                                        "value": {
                                            "id": "DF90F99E14F05F597E769DF70A3C693123E837C7",
                                            "name": "Rooms__UNIT E-329__1066270",
                                            "properties": {
                                                "results": [
                                                    {
                                                        "name": "Revit Category Type Id",
                                                        "value": "Rooms"
                                                    },
                                                    {
                                                        "name": "Number of People",
                                                        "value": 0
                                                    },
                                                    {
                                                        "name": "category",
                                                        "value": "Rooms"
                                                    },
                                                    {
                                                        "name": "Operation",
                                                        "value": "INSERT"
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    {
                                        "name": "Level",
                                        "value": {
                                            "id": "F6BA047FAC35CDBDD48CC976EFC0C4FF849BD15B",
                                            "name": "394693",
                                            "properties": {
                                                "results": [
                                                    {
                                                        "name": "category",
                                                        "value": "Levels"
                                                    },
                                                    {
                                                        "name": "family",
                                                        "value": "Level"
                                                    },
                                                    {
                                                        "name": "Name",
                                                        "value": "03 THIRD - FINISH FLOOR"
                                                    },
                                                    {
                                                        "name": "Elevation",
                                                        "value": 7.87400000000334
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    {
                                        "name": "Level",
                                        "value": {
                                            "id": "F6BA047FAC35CDBDD48CC976EFC0C4FF849BD15B",
                                            "name": "394693",
                                            "properties": {
                                                "results": [
                                                    {
                                                        "name": "type",
                                                        "value": "3/32\" Head"
                                                    },
                                                    {
                                                        "name": "Structural",
                                                        "value": false
                                                    },
                                                    {
                                                        "name": "Element Name",
                                                        "value": "3/32\" Head"
                                                    },
                                                    {
                                                        "name": "category",
                                                        "value": "Levels"
                                                    },
                                                    {
                                                        "name": "family",
                                                        "value": "Level"
                                                    },
                                                    {
                                                        "name": "Name",
                                                        "value": "03 THIRD - FINISH FLOOR"
                                                    }
                                                ]
                                            }
                                        }
                                    },
                                    {
                                        "name": "Type",
                                        "value": {
                                            "id": "F565E4CCC850427F0E2CBE96D78B13086C2D76DA",
                                            "name": "01",
                                            "properties": {
                                                "results": [
                                                    {
                                                        "name": "Family Name",
                                                        "value": "PUNCHED OPENING - A2 LITEX"
                                                    },
                                                    {
                                                        "name": "Operation",
                                                        "value": "MODIFY"
                                                    }
                                                ]
                                            }
                                        }
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        }
    }
    
    Show More

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

    ../../../../_images/Advanced_Queries-Task-4.png