Our Derivative Services team continues to improve the capabilities of the Model Derivative service. We recently introduced the ability to perform more granular queries on the properties of a model under a public beta release. You can find the docs here, and a deployed sample here, with source code here. Please provide comments and feedback here. For general help requests, please use the Forge Help.
Update: the demo sample is available now at
- GitHub: https://github.com/autodesk-platform-services/properties-query
- Demo link: https://properties-query.autodesk.io/
To get started, let’s look at the Model Derivative (MD) service in Forge, and how it enables users to represent and share the designs in a format of structured metadata. One of the metadata structures is object properties. MD API provides the way to fetch properties on the cloud, without the Forge Viewer . The endpoint GET: {urn}/metadata/{guid}/properties returns the list of properties for each object contained in the model view. By default, it will return properties of all objects in JSON in one chunk. Obviously, the larger size of the model, the more data that will be extracted.
Therefore, the query parameter forceget was introduced a while back. It forcibly fetches the data when it exceeded 20M. Even with this query parameter, the performance may suffer because of the massive amount of data to be transferred when it is a large model. Also there may be more data than what you care about. So, a workaround was to download the sql-lite database (also extracted by MD service), but this means additional step, and disconnection from the current data on the cloud. In addition, in many cases, the users only want to filter objects that contain specific properties, or find limit objects that have relationships, or check objects that match a formula and so on.
The newly released endpoint supports advanced query options and returns paginated results!
POST {urn}/metadata/{modelGuid}/properties:query
The new endpoint allows you to specify the request body with the items below:
- Pagination: this new endpoint supports to return JSONdata in pagination. The limit specifies max 20-1000 objects in one page, and offset specifies the number of properties in this page
- Query: a customized query DSL(Domain Specific Languages) defined in JSON format. It defines the clause with the conditions in an sql-like format. Several conditions are supported.
- Fields: keyword defines a set of object fields that will be included in the response body.
- Payload: specifies the format for numeric values in the response body. The format can be in text (the default), or in the format of ##<VALUE_OF_PROPERTY><UNIT_OF_VALUE><PRECISION><SYSTEM_UNIT>
In this blog, we will introduce Query. To begin with, let us take a look at a sample properties of the object:
Inside the properties, we call the “Dimensions” as a direct category, the “Area” as a leaf property. The “Version”, “Component Name” as a direct child property. Please note, the value type of the properties is basically a JSON that contains multiple nested key-value pairs. To locate the specific property, a JSON-path styled key is composed like properties.{category}.{property}. e.g. we can use properties.Dimensions.Area to refer to “Area” property. Query supports a search by basic attributes, direct child property and leaf property.
In Query, you can define the clause that is to match the condition. This new endpoint accepts a few conditions(rules) such as $contains, $gt, $between etc. Note: In current release, only one clause (with one condition) is supported in the request body.
- $in: this is a clause of a list query. It contains a list of exact values for a specific field. The query results returns objects that must contain the specified field and the values of the filed should match one of the defined values. The basic attribute objectId (numeric) and externalId (string) are supported in this release. For example, the below query will return those objects whose values are 123 or 789 :
{
"$in": ["objectid",123, 789 ]
}- $prefix: this is a clause to match the objects whose field contains a specific prefix string (case insensitive). Only the basic attribute name is supported. e.g. if to search the object whose name starts with “System Panel”, define the clause like:
{
"$prefix": ["name", 'System Panel']
}
- $contains: this clause specifies multiple terms for a specific property. The result returns objects that should contain the specified field and values of the field should contain one or more terms defined(case insensitive). Each term needs be separated by the ASCII whitespace. The maximum of 50 terms is allowed in one query. e.g. in the demo below, the text matching rule “Aluminum Steel” will be converted into separate terms: Aluminum and Steel. So the above query means to return objects whose properties JSON should contain a leaf property (Material ) and the value of the value should contain sub string “Aluminum” or “Steel”, or both.
{
"$contains":["properties.Constrains.Material", "Aluminum Steel"]
}
- $eq: this condition accepts the basic attributes name, or a unit property. If it is name, the condition is to match the string of the name exactly. e.g.
{
"$eq":["name ", “Door [34567]” ]
}
If it is a unit property, the second value must be numeric. In addition, the value is always in standard (united) unit.e.g. length unit is meter (m). Assume the exact value in source model is in centimeter (cm), the value is 500. To use $eq to find the object whose properties.Constrains.height =500, you must use standard unit (value =5) to search.
{
"$eq":["properties.Constrains.height", 5]
}
- $between: this condition accepts a unit property only. It returns the objects whose value is between two values( boundary values are included). The same to $eq, it searches by standard(united) unit. e.g. find objects with height that is >=34.567 meter and <=123.789 meter:
{
"$between": ["properties.Constrains.height ",34.567, 123.789]
}
- $le query: this condition accepts a unit property only. It returns the objects whose value is less than a value ( boundary values are included). The same, it searches by standard(united) unit. e.g. find objects with height that <=123.789 meter:
{
"$le": ["properties.Constrains.height",123.789]
}
- $ge query: this condition accepts a unit property only. It returns the objects whose value is less than a value ( boundary values are included). The same, it searches by standard(united) unit. e.g. find objects with height that >=34.567 meter:
{
"$ge": ["properties.Constrains.Length",34.567]
}
In the internal mechanism, all field of any types will have string index for $contains. If the original type is numeric, it will be also indexed for $le,$ge, $between, $eq.
WIn addition, in the next blog, we will introduce Fields and Payload.