Task 6 – Get Elements by using Instances or Reference
Learning objectives
In this task, you will learn how to retrieve all elements from all designs within a project. You will also learn how to filter the elements based on their materials or by element instances or by using reference type to fetch specific results that match your criteria.
By the end of this task, you will be able to:
- Fetch elements and information like id and properties.
- Make sense of the options and fields in the documentation on the elements query, elements object, Properties object, and references relationship.
- Learn to List all instances of concrete material elements in a design.
- Learn to List all instances of concrete material elements using instances.
- Learn to List all instances of concrete material elements by using reference parameter.
You will use the following queries in this task:
| Type | Operation | Description |
|---|---|---|
| Query | Elements | Retrieves designs in the given project using additional RSQL filters if provided. |
Step 1: List all Elements having Concrete material in a Design
First, list all concrete material elements under a design. This is done by fetching elements of category ‘Materials’ having an ‘Element Name’ property matching the string ‘Concrete’.
The Elements query returns Elements object, which contains an array of Elements objects.
For this exercise, we request all elements instances with - Elements id, name field, and properties. - Classification object. - Name and value fields in the properties object.
- In AEC Data Model Explorer, the query is populated by default in the Query Pane. You can also edit or update the query as per your requirement and run it.
Query
query GetConcreteMaterials($designId: ID!, $propertyFilter: String!) { elements( designId: $designId filter: {query: $propertyFilter} pagination: {limit: 20} ) { results { alternativeRepresentations { externalElementId } id name } } }Show MoreQuery Variables
- In the Query Variables Pane, replace the value of the designId variable with the designId that you used in task 3 of previous tutorial.
- In the Query Variables Pane, replace the value of the property filter with the property filter of your choice. For ease of understanding, here we have filtered based on property name from the category of windows.
Note: For information on the supported metadata filtering options, refer to the Advanced Filtering Capabilities page.
{ "designId": "YWVjZH5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3", "propertyFilter": "property.name.category==Materials and 'property.name.Element Name'=contains='Concrete'" } - Click Play. The list of elements available within that design of property ‘family’ and value ‘“Basic Wall” is displayed in the response. The response should be similar to the following code-block:
Response
{ "data": { "elements": { "results": [ { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzE1Nzc0Mw", "name": "Concrete, Precast Smooth, Light Grey" }, { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzFmYjFhNA", "name": "Concrete, Polished" }, { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzQ5ZmI", "name": "Concrete, Cast-in-Place gray" }, { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzQ5ZmM", "name": "Concrete, Precast" }, { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzQ5ZmU", "name": "Concrete Masonry Units" }, { "alternativeRepresentations": null, "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3XzVlOGE", "name": "Concrete, Lightweight" } ] } } }Show More
After working through the steps mentioned above, you should see a screen similar to the following image:
Note: In some designs, element instances may directly refer to material elements. In these cases, we use a query similar to step 2. However, in other designs, material elements are referenced by Type elements. In such cases, we use a query similar to step 3, where we list the Type that references the material.
Step 2- List Element instances having Concrete material
List the elements Instance having different types of concrete material. For this example, we will use the ‘Concrete, Precast’ and ‘Concrete, Precast Smooth, Light Grey’ ids.
- In AEC Data Model Explorer, the query is populated by default in the Query Pane. You can also edit or update the query as per your requirement and run it.
Query
query GetInstancesOfConcreteMaterial($designId: ID!, $propertyFilter: String!) { elements(designId: $designId, filter: { query: $propertyFilter}, pagination : { limit : 20 }) { results { id name properties { results { name value } } } } }Show MoreQuery Variables
- In the Query Variables Pane, replace the value of the
designIdvariable with the design ID that you used in task 3 of previous tutorial. - In the Query Variables Pane, replace the value of the
property filterwith the property filter of your choice. For ease of understanding, here we have filtered based on property filter as reference.structural Material.
Note: For information on the supported metadata filtering options, refer to the Advanced Filtering Capabilities page.
{ "designId" : "YWVjZH5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3", "propertyFilter" : "('reference.Structural Material'==YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzQ5ZmU or 'reference.Structural Material'==YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzVlOGE) and 'property.name.Element Context'==Instance" } - In the Query Variables Pane, replace the value of the
- Click Play. The list of elements available for the design property is retrieved. The response should be similar to the following code-block:
Note: In this query result, you might see blank responses because the system could not find matching elements for the specified filters. However, it is important to note that this does not apply to all cases, and the responses may differ for other queries based on the availability of elements.
Response
{ "data": { "elements": { "results": [] } } }
After working through the steps mentioned above, you should see a screen similar to the following image: |
Step 3- List Elements having Concrete material by using Reference type
In some cases, the material elements are referenced by Type elements which are in turn referenced by Instance elements. In such case, we would use a query like the following where we list the Type elements referencing the material elements and, for each Type element, list the Instance element referencing it through ‘Type’:
- In AEC Data Model Explorer, the query is populated by default in the Query Pane. You can also edit or update the query as per your requirement and run it.
Query
query GetInstancesOfConcreteMaterial($designId: ID!, $propertyFilter: String!) { elements( designId: $designId filter: {query: $propertyFilter} pagination: {limit: 20} ) { results { id name referencedBy(name: "Type") { results { id name properties { results { name value } } } } } } }Show MoreQuery Variables
- In the Query Variables Pane, replace the value of the
designIdvariable with thedesignIdthat you used in task 3 of previous tutorial. - In the Query Variables Pane, replace the value of the property filter with the property filter of your choice. For ease of understanding, here we have filtered based on property filter as reference.structural Material.
Note: For information on the supported metadata filtering options, refer to the Advanced Filtering Capabilities page.
{ "designId" : "YWVjZH5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35iaEtKQV8zdFIxbW5LVTVVVTRjTkV3", "propertyFilter" : "('reference.Structural Material'==YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzQ5ZmU or 'reference.Structural Material'==YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzVlOGE) and 'property.name.Element Context'==Type" } - In the Query Variables Pane, replace the value of the
- Click Play. The list of element available within that design of property. The response should be similar to the following code-block:
Response
{ "data": { "elements": { "results": [ { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzEyYTVlYg", "name": "Interior - CMU 8\"", "referencedBy": { "results": [ { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzEyYTdkMQ", "name": "Interior - CMU 8\"", "properties": { "results": [ { "name": "Revit Category Type Id", "value": "Walls" }, { "name": "Family Name", "value": "Basic Wall" }, { "name": "Element Name", "value": "Interior - CMU 8\"" }, { "name": "Element Context", "value": "Instance" }, { "name": "Length", "value": 4.330700000000138 }, { "name": "Design Option", "value": "Main Model" }, { "name": "Area", "value": 13.498037520000462 }, { "name": "Volume", "value": 2.614232416686092 }, { "name": "Export to IFC", "value": "By Type" }, { "name": "IfcGUID", "value": "3hI3j47xLFP97ZPHNL_W8v" }, { "name": "Related to Mass", "value": false }, { "name": "Room Bounding", "value": true }, { "name": "Base Offset", "value": 0 }, { "name": "Base Extension Distance", "value": 0 }, { "name": "Base is Attached", "value": false }, { "name": "Cross-Section", "value": "Vertical" }, { "name": "Location Line", "value": 2 }, { "name": "Structural", "value": false }, { "name": "Structural Usage", "value": 0 }, { "name": "Top Extension Distance", "value": 0 }, { "name": "Top is Attached", "value": false }, { "name": "Top Offset", "value": 0 }, { "name": "Unconnected Height", "value": 3.3528000000000002 } ] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBX2MwY2Vj", "name": "Interior - CMU 8\"", "properties": { "results": [ { "name": "Revit Category Type Id", "value": "Walls" }, { "name": "Family Name", "value": "Basic Wall" }, { "name": "Element Name", "value": "Interior - CMU 8\"" }, { "name": "Element Context", "value": "Instance" }, { "name": "Length", "value": 2.4002999999999526 }, { "name": "Design Option", "value": "Main Model" }, { "name": "Area", "value": 4.329023599999853 }, { "name": "Volume", "value": 0.8384236457299769 }, { "name": "Export to IFC", "value": "By Type" }, { "name": "IfcGUID", "value": "3aJHYCIlHAIBfmGnzR8dfj" }, { "name": "Related to Mass", "value": false }, { "name": "Room Bounding", "value": true }, { "name": "Base Offset", "value": 0 }, { "name": "Base Extension Distance", "value": 0 }, { "name": "Base is Attached", "value": false }, { "name": "Cross-Section", "value": "Vertical" }, { "name": "Location Line", "value": 2 }, { "name": "Structural", "value": false }, { "name": "Structural Usage", "value": 0 }, { "name": "Top Extension Distance", "value": 0 }, { "name": "Top is Attached", "value": false }, { "name": "Top Offset", "value": 0 }, { "name": "Unconnected Height", "value": 3.3528000000000002 } ] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBX2MwZDU5", "name": "Interior - CMU 8\"", "properties": { "results": [ { "name": "Revit Category Type Id", "value": "Walls" }, { "name": "Family Name", "value": "Basic Wall" }, { "name": "Element Name", "value": "Interior - CMU 8\"" }, { "name": "Element Context", "value": "Instance" }, { "name": "Length", "value": 4.3307000000001095 }, { "name": "Design Option", "value": "Main Model" }, { "name": "Area", "value": 8.530305520000374 }, { "name": "Volume", "value": 1.6521069215860678 }, { "name": "Export to IFC", "value": "By Type" }, { "name": "IfcGUID", "value": "3aJHYCIlHAIBfmGnzR8dlO" }, { "name": "Related to Mass", "value": false }, { "name": "Room Bounding", "value": true }, { "name": "Base Offset", "value": 0 }, { "name": "Base Extension Distance", "value": 0 }, { "name": "Base is Attached", "value": false }, { "name": "Cross-Section", "value": "Vertical" }, { "name": "Location Line", "value": 2 }, { "name": "Structural", "value": false }, { "name": "Structural Usage", "value": 0 }, { "name": "Top Extension Distance", "value": 0 }, { "name": "Top is Attached", "value": false }, { "name": "Top Offset", "value": 0 }, { "name": "Unconnected Height", "value": 3.3528000000000002 } ] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBX2MwZGI5", "name": "Interior - CMU 8\"", "properties": { "results": [ { "name": "Revit Category Type Id", "value": "Walls" }, { "name": "Family Name", "value": "Basic Wall" }, { "name": "Element Name", "value": "Interior - CMU 8\"" }, { "name": "Element Context", "value": "Instance" }, { "name": "Length", "value": 3.0575249999998992 }, { "name": "Design Option", "value": "Main Model" }, { "name": "Area", "value": 9.60191627999966 }, { "name": "Volume", "value": 1.859651135528927 }, { "name": "Export to IFC", "value": "By Type" }, { "name": "IfcGUID", "value": "3aJHYCIlHAIBfmGnzR8diu" }, { "name": "Related to Mass", "value": false }, { "name": "Room Bounding", "value": true }, { "name": "Base Offset", "value": 0 }, { "name": "Base Extension Distance", "value": 0 }, { "name": "Base is Attached", "value": false }, { "name": "Cross-Section", "value": "Vertical" }, { "name": "Location Line", "value": 2 }, { "name": "Structural", "value": false }, { "name": "Structural Usage", "value": 0 }, { "name": "Top Extension Distance", "value": 0 }, { "name": "Top is Attached", "value": false }, { "name": "Top Offset", "value": 0 }, { "name": "Unconnected Height", "value": 3.3528000000000002 } ] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBX2MxNmZj", "name": "Interior - CMU 8\"", "properties": { "results": [ { "name": "Revit Category Type Id", "value": "Walls" }, { "name": "Family Name", "value": "Basic Wall" }, { "name": "Element Name", "value": "Interior - CMU 8\"" }, { "name": "Element Context", "value": "Instance" }, { "name": "Length", "value": 5.002518104446733 }, { "name": "Design Option", "value": "Main Model" }, { "name": "Area", "value": 20.651874001489745 }, { "name": "Volume", "value": 3.987020302295162 }, { "name": "Export to IFC", "value": "By Type" }, { "name": "IfcGUID", "value": "3aJHYCIlHAIBfmGnzR8c1z" }, { "name": "Related to Mass", "value": false }, { "name": "Room Bounding", "value": true }, { "name": "Base Offset", "value": 0 }, { "name": "Base Extension Distance", "value": 0 }, { "name": "Base is Attached", "value": false }, { "name": "Cross-Section", "value": "Vertical" }, { "name": "Location Line", "value": 2 }, { "name": "Structural", "value": false }, { "name": "Structural Usage", "value": 0 }, { "name": "Top Extension Distance", "value": 0 }, { "name": "Top is Attached", "value": false }, { "name": "Top Offset", "value": 0 }, { "name": "Unconnected Height", "value": 5.1562 } ] } } ] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzZiYzZm", "name": "Generic - 12\" Masonry", "referencedBy": { "results": [] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzZiYzcw", "name": "Generic - 8\" Masonry", "referencedBy": { "results": [] } }, { "id": "YWVjZX5xcTdtR2JYNVV4NDNNVmJES3cwZGVuX0wyQ35yR2g0WmJJZVFNaUlDVlNIYWtoZzlBXzZiYzcx", "name": "Generic - 6\" Masonry", "referencedBy": { "results": [] } } ] } } }Show More
After working through the steps mentioned above, you should see a screen similar to the following image:
