Geovisualization Developer's Guide

Retrieving Statistics for a Query

The Geovisualization REST API provides a mechanism that allows you to retrieve statistics about column values from the results of your query. For example, you may want to determine the minimum, maximum and average values of certain columns to determine how to distribute the colors in a heat map.

There are several use cases for using statistics. You may want to call your query, then fetch statistics about the query results, and then modify your query to take this statistical information into account. You may also want statistical data only to complement the query data; for example, you could use statistics inside a map legend.

To fetch statistical data, you construct a stats JSON object that you send in the request body to the Geovisualization REST API, along with the query ID. The stats object represents a nested list containing column names and dynamic parameters:

column_stats: This object contains column names, each of which is a facet or metric defined in the query, followed by a list of statistical functions ($min, $max, $count_distinct, $count, $average or $sum) to be run on them. (See Query Statistics.)
dynamic: This object contains dynamic parameters, each of which is defined in the query, or $drop to remove that parameter from the filters. (See Using Dynamic Parameters.)

A complete stats JSON object would be structured as follows:

{
  "stats": [{{
    "column_stats": { <column_name>: [<stats_function, stats_function, ...>],
    <
        <column_name>: [<stats_function, stats_function, ...>]
    ...
      },
      "dynamic": {
        <dynamic_parameter>: <value> OR "$drop",
    <
        <dynamic_parameter>: <value> OR "$drop",
      }
    }
  ...
  ]
}

To get the statistics, include the object above as the request body in an authenticated POST to the following resource:

https://datalens.api.here.com/v1/queries/{QUERY_ID}/stats?app_code={YOUR_APP_CODE}&app_id={YOUR_APP_ID}

You can also use the queries/_ID_ endpoint in the 07. Query CRUD folder of our Postman collection.

You will receive a response body that includes a list of values representing the statistical data for the query.

Example ($drop)

To retrieve statistics for a query on a dataset containing measurements of earthquake magnitudes, we could POST the following request body to the following resource:

https://datalens.api.here.com/v1/queries/{QUERY_ID}/stats?app_code={YOUR_APP_CODE}&app_id={YOUR_APP_ID}

{

  "stats": [{
    "column_stats": {"Magnitude": ["$min","$max"]},
    "dynamic": {"min":"$drop", "max":"$drop"}}
]}

You can also use the queries/_ID_ endpoint in the 07. Query CRUD folder of our Postman collection.

This requests the minimum and maximum values of the Magnitude column of the query. Since the query contains dynamic parameters, we need to specify those values. If we set these parameters to constant values, for example, min to 1 and max to 3, the returned statistics would be 1 and 3 because the dynamic parameters are used as filters on the very column for which we want the true range. Clearly, this is not very helpful, and we need to avoid using those parameters.

To do this, pass the value $drop in the request. This eliminates the need for values for the dropped parameters, and every filter action that depends on them will be ignored. In this way, you can get the true maximum and minimum values of the Magnitude column.

Example

Assume you have the following query:

{
  "dataset": "test",
  "facets": ["col1"],
  "metrics": ["val1"],
  "namespace": {
  "val1": {
    "source": ["col2", "user_value"],
    "apply": [{
    "fn": "round",
    "type": "transform"
    }, {
    "fn": "count",
    "type": "aggregate"
    }]
  },
  "user_value": {
    "source": [{
    "$input": "some_user_value"
    }]
  }
  },
  "filters": [{
    "col1": {
    "$eq": 1
    }
  },
  {
    "val1": {
    "$gt": 2
    }
  },
  {
    "$and": [{
    "col2": {
      "$lt": 1
    }
    }, {
    "val1": {
      "$lt": 111
    }
    }]
  }
  ]
}

To the following resource:

https://datalens.api.here.com/v1/queries/{QUERY_ID}/stats?app_code={YOUR_APP_CODE}&app_id={YOUR_APP_ID}

This requests the minimum and maximum values of the Magnitude column of the query. Since the query contains dynamic parameters, we need to specify those values. If we set these parameters to constant values, for example, min to 1 and max to 3, the returned statistics would be 1 and 3 because the dynamic parameters are used as filters on the column for which we want the true range. This is not helpful, and you need to avoid using those parameters.