Get Started For Free Get Started For Free

Geovisualization

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
Create a query on a dataset with one or more of the following capabilities: 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
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".