Request

Response

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

    Retrieve Elements by Category

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

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

    • Retrieve a list of elements of an exchange.
    • Filter elements based on a category and retrieve 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.

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

    1. In the Data Exchange Explorer, enter the following query in the Query Pane.

      Query

      query GetElementsOfCategoryWalls(
    $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 to Navigate to Exchanges within a Folder. Assign property filter with the category of your choice.

      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"
    },
    "elementPagination": {
        "limit": 2,
        "cursor": ""
    }
}
      Show More
    3. Click Play. A list of elements and its associated properties is displayed in the response.

      Response

      {
    "data": {
        "exchange": {
            "id": "ZXhjfnlwdWFzY1NicWlIT0R1R0s4OUkwTHdfTDJDfjkwMGM5ODY1LWI2ZmMtMzI0Ny04NWUxLTgxMmZhOGY1ZTJkNA",
            "name": "SHARE -Multi-Fam Apt-Wing 2",
            "elements": {
                "pagination": {
                    "pageSize": 2,
                    "cursor": "26bef7c0-9141-4f42-8be3-28ee6e2ffd52"
                },
                "results": [
                    {
                        "id": "0035F6FC1E195ECB479AC714FB33DAC21E7A3AC5",
                        "name": "2212392",
                        "properties": {
                            "results": [
                                {
                                    "name": "Revit Category Type Id",
                                    "value": "Walls"
                                },
                                {
                                    "name": "Unconnected Height",
                                    "value": 3.2511999999999963
                                },
                                {
                                    "name": "family",
                                    "value": "Basic Wall"
                                },
                                {
                                    "name": "category",
                                    "value": "Walls"
                                },
                                {
                                    "name": "Length",
                                    "value": 5.40544796403661
                                },
                                {
                                    "name": "Volume",
                                    "value": 0.965724399929636
                                }
                            ]
                        }
                    },
                    {
                        "id": "002EDE9A075642C3535288AE5F37AF324462AC7D",
                        "name": "1026226",
                        "properties": {
                            "results": [
                                {
                                    "name": "Family Name",
                                    "value": "Basic Wall"
                                },
                                {
                                    "name": "IfcGUID",
                                    "value": "2SRowrC2HE89xO3mxQAe_t"
                                },
                                {
                                    "name": "Revit Category Type Id",
                                    "value": "Walls"
                                },
                                {
                                    "name": "Unconnected Height",
                                    "value": 3.2512000000046593
                                },
                                {
                                    "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-1.png