Get Element Instances in a Category by Version
In this guide, you will learn how to retrieve all instances of a particular category from an elementGroup at a specific version. Also, you can request only those instances that match your filter criteria.
Let’s try to retrieve all instances of the category Walls from the second version of the model Snowdon Towers Sample Architecture.rvt.
By the end of this guide, you will be able to:
- Fetch Instance Elements of a category
Wallsfrom a specific version of the elementGroup and define the property filter withversionNumber. - Use advanced operators like
greater than,less than,and, andor.
You will use the following queries in this guide:
| Type | Operation | Description |
|---|---|---|
| Query | ElementsByElementGroup | Retrieves elementGroups in the given project, using additional RSQL filters if provided. |
Step 1: Request elements matching the specified classification filter
The ElementsByElementGroup query returns Elements object, which contains an array of Elements objects.
- For this exercise, we request all elements instances that contain:
- Elements id, name field, and properties.
- 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 GetWallsElementsByElementGroupIdAtVersion($elementGroupId: ID!, $versionNumber: Int!, $propertyFilter: String!) { elementsByElementGroupAtVersion(elementGroupId: $elementGroupId, versionNumber: $versionNumber, filter: { query: $propertyFilter}, pagination : { limit : 5 }) { pagination { cursor } results { id name properties { results { name value displayValue } } } } }Show MoreQuery Variables
- In the Query Variables Pane, replace the value of the
elementGroupIdvariable with the elementGroup ID that you used in Navigate to Elementgroups. - 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 added the filter based on property name and category asWalls.Note: To know the list of supported metadata filtering options, refer Advanced Filtering Capabilities page.
{ "elementGroupId" : "YWVjZH42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVB", "versionNumber": 1, "propertyFilter": "property.name.category==Walls and 'property.name.Element Context'==Instance" }
- In the Query Variables Pane, replace the value of the
- Click Play. The list of elements available within that elementGroup of property ‘family’ and category ‘“Walls” is displayed in the response. The response should be similar to the following code-block:
Response
{ "data": { "elementsByElementGroupAtVersion": { "pagination": { "cursor": "Y3Vyc341fjU" }, "results": [ { "id": "YWVjZX42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVBXzEwMTc5NQ", "name": "_Not Defined", "properties": { "results": [ { "name": "Comments", "value": null, "displayValue": null }, { "name": "Angle", "value": 0, "displayValue": "0" }, { "name": "Angle", "value": 0, "displayValue": "0" }, { "name": "Offset", "value": 0, "displayValue": "0" }, { "name": "Offset", "value": 0, "displayValue": "0" }, { "name": "Length", "value": 1.0668000000000002, "displayValue": "1.0668000000000002" }, { "name": "Design Option", "value": "Main Model", "displayValue": "Main Model" }, { "name": "Mark", "value": null, "displayValue": null }, { "name": "External ID", "value": "049439b4-5467-47c4-a72e-459e7fd736c2-00101795", "displayValue": "049439b4-5467-47c4-a72e-459e7fd736c2-00101795" }, { "name": "Area", "value": 2.4928982400006445, "displayValue": "2.4928982400006445" }, { "name": "Export to IFC", "value": "By Type", "displayValue": "By Type" }, { "name": "Export to IFC As", "value": null, "displayValue": null }, { "name": "IFC Predefined Type", "value": null, "displayValue": null }, { "name": "IfcGUID", "value": "04b3cqL6T7nASkHPv$no5N", "displayValue": "04b3cqL6T7nASkHPv$no5N" }, { "name": "Revit Category Type Id", "value": "Walls", "displayValue": "Walls" }, { "name": "Family Name", "value": "Curtain Wall", "displayValue": "Curtain Wall" }, { "name": "Element Name", "value": "_Not Defined", "displayValue": "_Not Defined" }, { "name": "Element Context", "value": "Instance", "displayValue": "Instance" }, { "name": "Related to Mass", "value": false, "displayValue": "false" }, { "name": "Justification", "value": "Beginning", "displayValue": "Beginning" }, { "name": "Justification", "value": "Beginning", "displayValue": "Beginning" }, { "name": "Number", "value": 2, "displayValue": "2" }, { "name": "Number", "value": 4, "displayValue": "4" }, { "name": "Room Bounding", "value": true, "displayValue": "true" }, { "name": "Base Offset", "value": 0.8128000000000001, "displayValue": "0.8128000000000001" }, { "name": "Base is Attached", "value": false, "displayValue": "false" }, { "name": "Cross-Section", "value": "Vertical", "displayValue": "Vertical" }, { "name": "Structural", "value": false, "displayValue": "false" }, { "name": "Structural Usage", "value": 0, "displayValue": "0" }, { "name": "Top is Attached", "value": false, "displayValue": "false" }, { "name": "Top Offset", "value": -2.3368, "displayValue": "-2.3368" }, { "name": "Unconnected Height", "value": 2.3368000000006037, "displayValue": "2.3368000000006037" }, { "name": "Revit Element ID", "value": "1054613", "displayValue": "1054613" } ] } }, { "id": "YWVjZX42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVBXzEwMTdhNQ", "name": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud", "properties": { "results": [ { "name": "Comments", "value": null, "displayValue": null }, { "name": "Length", "value": 1.4383160862420683, "displayValue": "1.4383160862420683" }, { "name": "Design Option", "value": "Main Model", "displayValue": "Main Model" }, { "name": "Mark", "value": null, "displayValue": null }, { "name": "External ID", "value": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a5", "displayValue": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a5" }, { "name": "Area", "value": 3.2317665212142757, "displayValue": "3.2317665212142757" }, { "name": "Volume", "value": 0.9860739215865809, "displayValue": "0.9860739215865809" }, { "name": "Export to IFC", "value": "By Type", "displayValue": "By Type" }, { "name": "Export to IFC As", "value": null, "displayValue": null }, { "name": "IFC Predefined Type", "value": null, "displayValue": null }, { "name": "IfcGUID", "value": "04b3cqL6T7nASkHPv$no5d", "displayValue": "04b3cqL6T7nASkHPv$no5d" }, { "name": "Revit Category Type Id", "value": "Walls", "displayValue": "Walls" }, { "name": "Family Name", "value": "Basic Wall", "displayValue": "Basic Wall" }, { "name": "Element Name", "value": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud", "displayValue": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud" }, { "name": "Element Context", "value": "Instance", "displayValue": "Instance" }, { "name": "Related to Mass", "value": false, "displayValue": "false" }, { "name": "Room Bounding", "value": true, "displayValue": "true" }, { "name": "Base Offset", "value": 0, "displayValue": "0" }, { "name": "Base Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Base is Attached", "value": false, "displayValue": "false" }, { "name": "Cross-Section", "value": "Vertical", "displayValue": "Vertical" }, { "name": "Location Line", "value": 2, "displayValue": "2" }, { "name": "Structural", "value": false, "displayValue": "false" }, { "name": "Structural Usage", "value": 0, "displayValue": "0" }, { "name": "Top Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Top is Attached", "value": false, "displayValue": "false" }, { "name": "Top Offset", "value": -0.9398000000000002, "displayValue": "-0.9398000000000002" }, { "name": "Unconnected Height", "value": 4.546600000000602, "displayValue": "4.546600000000602" }, { "name": "Revit Element ID", "value": "1054629", "displayValue": "1054629" } ] } }, { "id": "YWVjZX42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVBXzEwMTdhNg", "name": "Solar Wall (Parapet)", "properties": { "results": [ { "name": "Comments", "value": null, "displayValue": null }, { "name": "Length", "value": 1.6460776368749865, "displayValue": "1.6460776368749865" }, { "name": "Design Option", "value": "Main Model", "displayValue": "Main Model" }, { "name": "Mark", "value": null, "displayValue": null }, { "name": "External ID", "value": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a6", "displayValue": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a6" }, { "name": "Area", "value": 1.376465981556736, "displayValue": "1.376465981556736" }, { "name": "Volume", "value": 0.687905392562603, "displayValue": "0.687905392562603" }, { "name": "Export to IFC", "value": "By Type", "displayValue": "By Type" }, { "name": "Export to IFC As", "value": null, "displayValue": null }, { "name": "IFC Predefined Type", "value": null, "displayValue": null }, { "name": "IfcGUID", "value": "04b3cqL6T7nASkHPv$no5a", "displayValue": "04b3cqL6T7nASkHPv$no5a" }, { "name": "Revit Category Type Id", "value": "Walls", "displayValue": "Walls" }, { "name": "Family Name", "value": "Basic Wall", "displayValue": "Basic Wall" }, { "name": "Element Name", "value": "Solar Wall (Parapet)", "displayValue": "Solar Wall (Parapet)" }, { "name": "Element Context", "value": "Instance", "displayValue": "Instance" }, { "name": "Related to Mass", "value": false, "displayValue": "false" }, { "name": "Room Bounding", "value": true, "displayValue": "true" }, { "name": "Base Offset", "value": -0.9398000000000002, "displayValue": "-0.9398000000000002" }, { "name": "Base Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Base is Attached", "value": false, "displayValue": "false" }, { "name": "Cross-Section", "value": "Tapered", "displayValue": "Tapered" }, { "name": "Location Line", "value": 3, "displayValue": "3" }, { "name": "Structural", "value": false, "displayValue": "false" }, { "name": "Structural Usage", "value": 0, "displayValue": "0" }, { "name": "Exterior Angle", "value": 0.17453292519943278, "displayValue": "0.17453292519943278" }, { "name": "Interior Angle", "value": 0, "displayValue": "0" }, { "name": "Enable Angle Overrides", "value": false, "displayValue": "false" }, { "name": "Bottom Width", "value": 0.6387870964698155, "displayValue": "0.6387870964698155" }, { "name": "Top Width", "value": 0.47307500000000025, "displayValue": "0.47307500000000025" }, { "name": "Top Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Top is Attached", "value": false, "displayValue": "false" }, { "name": "Top Offset", "value": 0, "displayValue": "0" }, { "name": "Unconnected Height", "value": 0.9397999999999986, "displayValue": "0.9397999999999986" }, { "name": "Revit Element ID", "value": "1054630", "displayValue": "1054630" } ] } }, { "id": "YWVjZX42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVBXzEwMTdhNw", "name": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud", "properties": { "results": [ { "name": "Comments", "value": null, "displayValue": null }, { "name": "Length", "value": 1.0626540981910537, "displayValue": "1.0626540981910537" }, { "name": "Design Option", "value": "Main Model", "displayValue": "Main Model" }, { "name": "Mark", "value": null, "displayValue": null }, { "name": "External ID", "value": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a7", "displayValue": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a7" }, { "name": "Area", "value": 3.768650122285474, "displayValue": "3.768650122285474" }, { "name": "Volume", "value": 1.1019842226549768, "displayValue": "1.1019842226549768" }, { "name": "Export to IFC", "value": "By Type", "displayValue": "By Type" }, { "name": "Export to IFC As", "value": null, "displayValue": null }, { "name": "IFC Predefined Type", "value": null, "displayValue": null }, { "name": "IfcGUID", "value": "04b3cqL6T7nASkHPv$no5b", "displayValue": "04b3cqL6T7nASkHPv$no5b" }, { "name": "Revit Category Type Id", "value": "Walls", "displayValue": "Walls" }, { "name": "Family Name", "value": "Basic Wall", "displayValue": "Basic Wall" }, { "name": "Element Name", "value": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud", "displayValue": "Exterior - 12 5/8\" Rainscreen w Insultation on Metal Stud" }, { "name": "Element Context", "value": "Instance", "displayValue": "Instance" }, { "name": "Related to Mass", "value": false, "displayValue": "false" }, { "name": "Room Bounding", "value": true, "displayValue": "true" }, { "name": "Base Offset", "value": 0, "displayValue": "0" }, { "name": "Base Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Base is Attached", "value": false, "displayValue": "false" }, { "name": "Cross-Section", "value": "Vertical", "displayValue": "Vertical" }, { "name": "Location Line", "value": 2, "displayValue": "2" }, { "name": "Structural", "value": false, "displayValue": "false" }, { "name": "Structural Usage", "value": 0, "displayValue": "0" }, { "name": "Top Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Top is Attached", "value": false, "displayValue": "false" }, { "name": "Top Offset", "value": -0.9398000000000002, "displayValue": "-0.9398000000000002" }, { "name": "Unconnected Height", "value": 4.546600000000602, "displayValue": "4.546600000000602" }, { "name": "Revit Element ID", "value": "1054631", "displayValue": "1054631" } ] } }, { "id": "YWVjZX42SUpGQXdONExWTG5JZXZiQk5GNU1IX0wyQ35yRWRKT0NPcVIwZWt5SkJCWWxSOUVBXzEwMTdhOA", "name": "Solar Wall (Parapet)", "properties": { "results": [ { "name": "Comments", "value": null, "displayValue": null }, { "name": "Length", "value": 1.2009675475581287, "displayValue": "1.2009675475581287" }, { "name": "Design Option", "value": "Main Model", "displayValue": "Main Model" }, { "name": "Mark", "value": null, "displayValue": null }, { "name": "External ID", "value": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a8", "displayValue": "049439b4-5467-47c4-a72e-459e7fd736c2-001017a8" }, { "name": "Area", "value": 0.901755704546776, "displayValue": "0.901755704546776" }, { "name": "Volume", "value": 0.43464459760001195, "displayValue": "0.43464459760001195" }, { "name": "Export to IFC", "value": "By Type", "displayValue": "By Type" }, { "name": "Export to IFC As", "value": null, "displayValue": null }, { "name": "IFC Predefined Type", "value": null, "displayValue": null }, { "name": "IfcGUID", "value": "04b3cqL6T7nASkHPv$no5g", "displayValue": "04b3cqL6T7nASkHPv$no5g" }, { "name": "Revit Category Type Id", "value": "Walls", "displayValue": "Walls" }, { "name": "Family Name", "value": "Basic Wall", "displayValue": "Basic Wall" }, { "name": "Element Name", "value": "Solar Wall (Parapet)", "displayValue": "Solar Wall (Parapet)" }, { "name": "Element Context", "value": "Instance", "displayValue": "Instance" }, { "name": "Related to Mass", "value": false, "displayValue": "false" }, { "name": "Room Bounding", "value": true, "displayValue": "true" }, { "name": "Base Offset", "value": -0.9398000000000002, "displayValue": "-0.9398000000000002" }, { "name": "Base Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Base is Attached", "value": false, "displayValue": "false" }, { "name": "Cross-Section", "value": "Tapered", "displayValue": "Tapered" }, { "name": "Location Line", "value": 3, "displayValue": "3" }, { "name": "Structural", "value": false, "displayValue": "false" }, { "name": "Structural Usage", "value": 0, "displayValue": "0" }, { "name": "Exterior Angle", "value": 0.17453292519943278, "displayValue": "0.17453292519943278" }, { "name": "Interior Angle", "value": 0, "displayValue": "0" }, { "name": "Enable Angle Overrides", "value": false, "displayValue": "false" }, { "name": "Bottom Width", "value": 0.6387870964698155, "displayValue": "0.6387870964698155" }, { "name": "Top Width", "value": 0.47307500000000025, "displayValue": "0.47307500000000025" }, { "name": "Top Extension Distance", "value": 0, "displayValue": "0" }, { "name": "Top is Attached", "value": false, "displayValue": "false" }, { "name": "Top Offset", "value": 0, "displayValue": "0" }, { "name": "Unconnected Height", "value": 0.9397999999999986, "displayValue": "0.9397999999999986" }, { "name": "Revit Element ID", "value": "1054632", "displayValue": "1054632" } ] } } ] } } }Show More
After working through the steps mentioned above, you should see a screen similar to the following image: