AEC Data Model API: Distinct Property Values, Point Value and Updates to Filtering

In this blog, we would like to introduce three enhancements recently made to the AEC Data Model API:

1. new queries to retrieve distinct property values
2. new field "pointValue" in response data.extensions
3. updates to filtering 

Distinct Property Values

The first enhancement is about "Distinct Property Values". We have added the following two new queries that enable you to find and retrieve all distinct values of a given property within an element group. You can retrieve either by property definition ID or by property name:

• distinctPropertyValuesInElementGroupById
• distinctPropertyValuesInElementGroupByName

Here is an example usage:

Query

query ($elementGroupId: ID!, $propertyDefinitionId: ID!, $filter: ElementFilterInput) {
  distinctPropertyValuesInElementGroupById(elementGroupId: $elementGroupId, propertyDefinitionId: $propertyDefinitionId, filter: $filter) {
    values(limit: 200) {
      value,
      count
    }
  }
}

Variables

{
  "elementGroupId": "XXX",
  "propertyDefinitionId": "autodesk.revit.parameter:parameter.category-2.0.0"
}

Response

"values": [
    {
        "value": "Curtain Wall Mullions",
        "count": 2372
    },
    {
        "value": "Analytical Nodes",
        "count": 1410
    }
]

Point Value 

The second one is about "Point Value". "pointValue" field has been added to data.extensions in response. Point value is calculated based on the complexity of the query. A complex task and the retrieval of large amount of data will result in high point value. There is also a cap on the total number of points that an application can consume within a given minute, which is used as a rate limit with GraphQL API. "AEC Data Model Rate Limit" section of Developer Guide explains the detail of how the point value is calculated.    

  "extensions": {
    "pointValue": {
      "requestedQueryPointValue": 61
    }
  }

Enhanced Filtering 

Lastly, there is a change in the way fileUrn and name are used in ElementGroup filters.

• For standard filtering:  
  • fileUrn can only be used by itself and not in combination with other filters.
  • "name" can be used with only one value. It does not accept multiple values. 

• Similarly, for Advanced Filtering using RSQL: 
  • metadata.fileUrn can only be used by itself, and not in combination with other filters. 
  • metadata.name can be used with only one value. It does not accept multiple values.
  • metadata.name cannot be used with OR's. Only AND's are supported.  

Additionally, for element query, ElementFilterInput: 

• elementId and metadata.emenetId are added.  

For more detail about the ElementGroup filters updates, please refer to the following documentation pages: 

• Standard Filtering: Special Considerations for ElementGroup Filters 
• Advanced Filtering Using RSQL: Special Considerations for ElementGroup Filters 

There is also minor documentation update, mainly renaming Designs to ElementGroups for clarifications in wording.  

AEC Data Model API was a hot topic during this year's Autodesk University at San Diego. During our AEC Data Model class, we got quite a lot of interest from attendees. We continue to enhance AEC Data Model API. You can find change log here. We also suggest you to subscribe APS Developer News newsletter to receive future updates if you haven't done so.