Querying Model Properties
The following step-by-step tutorial describes how to create a basic property index and run a simple query against this index.
Step 1: Specify the index
To create a basic index, call the batch status method, which allows you to check the status of one or more file version indexes. The batch status endpoint is lazy, meaning that if an indexing job for the file(s) specified in batch status check have not been executed, the service will automatically start the missing job(s). For the purposes of this tutorial, however, we will use the simple single file mode.
Example Request
In the request below a POST is made to the index batch status endpoint passing in a single model file. There are no query or columns properties set in the payload so no query results will be generated in response to this operation.
Example Response
The response to a batch status request is an array of status objects, one per file being indexed. The indexId on the status object is the unique identifier for this index and can be used in subsequent calls to check the progress of the indexing job and to later download the resources associated with the index. Calling the batch status endpoint multiple times will not result in multiple, duplicate indexes as long as the input parameters of the request do not change. Provided the array of objects in the versions set, query, and optionally columns properties passed to the endpoints remain unchanged, the caller will always be returned the same indexId.
In addition to the indexId the the status response object contains the status of the indexing job. Indexes once calculated are cached for 30 days on a rolling event horizon that is incremented every time the index is accessed. If an index is not accessed for 30 days it will fall out of the cache and will need to be subsequently recalculated. A status of PROCESSING indicates that the service is building the index. This could include waiting for SVF2 translation to complete. When the service has successfully created an index the status will be set to FINISHED. This indicates that the index and all its resources are available for download. The contract returned by the index service in response to an index status request also includes a suggested retryAt timestamp, which can be used to regulate status polling frequency.
The properties returned by this endpoint are as follows:
Step 2: Poll for progress
To track the progress of an indexing request, send a GET request to the index status endpoint using the indexId obtained in the batch status request. When the index has a status of FINISHED processing, the index is available for querying and download.
Example Request
Example Response
When an index has been successfully created (state equals FINISHED), it contains three downloadable json.gz resources: a manifest describing the files and SVF2 database resources that were used to create the index, a list of fields (dimensions) in the index, and the index property data. Each of these resources has a URL that can be used to fetch the corresponding resource. The response JSON is identical to the response returned by the POST to the batch status endpoint (step 1 above).
Step 3: (Optional) Download the manifest
To retrieve the index manifest make a GET to the manifest endpoint as described in the field guide
Example Request
Example Response
The structure of the manifest resource returned by this endpoint is described in the field guide page.
Step 4: (Optional) Download the fields
In order to query the index, download the fields resource, which describes the columns available in the index. The index fields are obtained by a call to the fieldsUrl returned either by a call to the batch status endpoint (Step 1) or by polling the state of a running indexing job (Step 2). If you already know the field keys you require for your query you can skip this step.
Example Request
Example Response
The structure of the fields resource returned by this endpoint is described in the field guide page.
Step 5: (Optional) Download the raw index
While the indexing service is designed to run SQL-like queries targeting the fields contained within the indexes it hosts, it is possible to download raw indexes created by the service in their entirety. The raw index properties are obtained by a call to the propertiesUrl returned either by a call to the batch status endpoint (Step 1) or by polling the state of a running indexing job (Step 2).
Example Request
Example Response
Index rows are returned as compressed (gzip) line-delimited JSON. The following is an example viewable index row, formatted as a single JSON document to make reading the property description table below easier.
The structure of the properties resource returned by this endpoint is described in the field guide page.
Step 6: Build and run a query
Once an index has been successfully created, it can be queried using the queries endpoint for the index via the indexId that can be obtained by a call to the index status tracking endpoints (Steps 1 or 2 above). Index queries are described using a custom JSON schema that is converted to a filter expression and applied line by line to the index. This documentation includes a comprehensive query language reference that describes how to form index and diff queries by example using this JSON schema.
Example Request
The query schema targets the structure of the JSON index rows. In the example POST to the queries endpoint below, only rows that have a views array with a count greater than 0 will be returned, i.e. only the rows in the index that are associated with a model element that can be viewed in the Viewer.
Example Response
The response from the queries endpoint is very similar to the response from the index status endpoints. The only additional property returned by this endpoint is a queryId value. This queryId is a unique identifier for the query execution and can be used to poll the progress of the query job. As with index status operations, a query is successful when its state is set to FINISHED. Index queries also have the standard manifestUrl, fieldsUrl, and propertiesUrl values that point to the index resources used when performing the query. In addition the queries endpoint also returns a queryResultsUrl property that points to a gzip’d, line delimited JSON resource that contains the filtered index rows that match the query filter expression when the query reaches the FINISHED state.
Step 7: Poll for query progress
The index queries endpoint follows the same pattern as the status endpoint. The queryId obtained in the POST to the queries endpoint can be used to poll the progress of the query.
Example Request
In this example request the queryId and indexId from the previous Step (5) are used to poll the progress of the query.
Example Response
The response to this status GET is identical to the response returned by the POST to the queries endpoint. In the example below the query state is set to FINISHED and the queryResultsUrl is not null, indicating that the query has been completed successfully and the results are available for download.
Step 8: Download the query results
The final step in the process is to use the queryResultsUrl to download the index rows which match the submitted query expression. These line delimited JSON result rows are a sub-set of the property index rows and have exactly the same format.
Example Request
Example Response
Imported from the Autodesk Platform Services documentation: https://aps.autodesk.com/en/docs/acc/v1/tutorials/model-properties/query.