Queries
Use this resource to create, retrieve, update, run and delete queries.
A query represents a defined set of rules, composed in the Geovisualization query language, that reads, aggregates, transforms, sorts and filters data in a dataset and returns the resulting data to a visualization. Each query is a JSON object and is represented by a unique query ID.
For more information on the query language used to define Geovisualization queries, see Query Language API Reference.
The table below summarizes the available endpoints supported by the queries
resource along with their HTTP methods and responses.
Resource | Functions | Method | Response |
---|---|---|---|
/queries | List all queries | GET | 200 OK with a response object containing a list of queries |
Create a query on a dataset with one or more of the following capabilities:
| POST | 201 Created if successful and the query does not require data processing; and 202 Accepted if successful and the query requires data processing; with a response object containing the query ID | |
/queries?dataset=... | List all queries that match the dataset IDs and tags that you specify in the URL. See the examples. | GET | 200 OK with a response body with a summary list of all the queries matching the filters set in the URL |
/queries/{QUERY_ID} | Fetch a query definition | GET | 200 OK with a response object with the query ID |
Update a query with a new definition defined in the request body | POST | 200 OK with a response object with the query ID | |
Delete a query | DELETE | 200 OK and a response object with the query ID | |
/queries/{QUERY_ID}/tags | Fetch query tags | GET | 200 OK with a response object with the query tags |
Label a query with tags defined in the request body | POST | 200 OK with a response object with the query tags | |
/queries/{QUERY_ID}/data | Fetch the results of a query on a dataset | GET | 200 OK with a response object with the query ID |
/queries/{QUERY_ID}/clone | Clone a query | POST | 201 Created if successful and the query does not require data processing; and 202 Accepted if successful and the query does require data processing; with a response object containing the query ID |
/queries/{QUERY_ID}/stats | Retrieve statistics from the query identified by its ID and based on the request body | POST | 200 OK with a response object with the values |
/queries/{QUERY_ID}/permissions | Fetch the permissions for a query | GET | 200 OK if successful and a response body for the permissions. |
/queries/{QUERY_ID}/permissions | Create the permissions for a query with a request body specifying a role and an array of user IDs. See Datasets Permissions for more details | POST | 200 OK if successful and a response body of each role and the users with that role. |
/queries/{QUERY_ID}/permissions | Delete the permissions for a query with a request body specifying a role and an array of user IDs. See Datasets Permissions for more details | DELETE | 200 OK if successful and a response body of each role and the remaining users with that role. |
/queries/materialize | Create a new dataset using an arbitrary query specified in a request body | POST | 200 OK with a response object with the new dataset ID |
Example
Example of filtering for queries that match the dataset IDs and tags that you specify in the URL:
GET https://datalens.api.here.com/v1/queries?dataset={DATASET_ID}&tag={tag1}&tag={tag2}&tag_op={or|and}...
Request Parameters
The table below documents the mandatory request parameters required by this resource.
Parameter | Datatype | Description |
---|---|---|
app_id | String | A 20-byte Base64 URL-safe encoded string used for the authentication of the client application |
app_code | String | A 20-byte Base64 URL-safe encoded string used for the authentication of the client application |
access_token | String | A temporary string used for authentication. Tokens are valid for one hour. We recommend that the token be included in the HTTP Header when sending requests. For more information on setting up the |
The table below documents the optional request parameters that can be used by this resource.
Parameter | Datatype | Description |
---|---|---|
dataset | String | Filter to limit the number of queries returned based on the specified dataset ID |
tag | String | Filter to limit the selection of queries returned, based on tags defined for the query. For example, if you specify ...?tag=earthquakes&tag=depths&tag_op=and , then the response includes only the queries that are labeled with "earthquakes" and "depths" . |
tag_op | String | An operator that indicates whether the request should match queries having all the tags specified with the tag parameter ("and") or if the request should match queries having at least one of the tags ("or"). Note that tag_op is optional; when it is not present, the default behavior is to set it to "and". |