Geovisualization Developer's Guide

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.

Table 1. Queries Endpoints
Resource	Functions	Method	Response
`/queries`	List all queries	GET	`200 OK` with a response object containing a list of queries
`/queries`	Create a query on a dataset with one or more of the following capabilities: aggregation rules transformation rules filters or sorting as defined in the request body	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
`/queries/{QUERY_ID}/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.

Note: All the parameters below are required for authentication. For more information about authentication and authorization in general, see the authentication related topics under Getting Started.

Table 2. Request Parameters
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 `access_token` in the HTTP Header, see Getting Authentication Credentials.

The table below documents the optional request parameters that can be used by this resource.

Table 3. Optional Request Parameters
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".