Data Lens Developer's Guide

Retrieving Statistics for a Query

The Data Lens 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 Data Lens 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 will receive a response body that includes a list of values representing the statistical data for the query.

To do this in Postman (see Using Postman):

  1. Paste the URL above into Postman's URL bar, replacing [query_id] with the ID of the query for which you want to retrieve statistics.
  2. Set the request type (next to the URL bar) to POST.
  3. Select Body and switch to raw.
  4. Enter the request payload with the stats definition (as described above) into the Body input field.
  5. Click Send.

Example ($drop)

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

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

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 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, we 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, we 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}}]}
      ]
}

Consider the following statistics request:

{
      "stats": [{
          "column_stats": {
              "col1": ["$max", "$min", "$count_distinct"],
              "col2": ["$max"]
          },
          "dynamic": {
              "some_user_value": 10
          }
      }, {
          "column_stats": {
              "col1": ["$min"]
          },
          "dynamic": {
              "some_user_value": "$drop"
          }
      }]
}

Post this statistics request to the following resource:

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

The response would look something like this:

{
        "stats": [{
      "column_stats": {
        "col1": [10, 2, 4],
        "col2": [15]
      }
    }, {
      "column_stats": {
        "col1": [5]
      }
    }]
}

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.