Skip to main content

​
Use cases

Populate UI filters

Populate filters with unique values.

AI Agents

Prompt LLMs with available values.

Display trending values

Display most frequent values.

​
Features

All the common API features, plus:
The Top Values API uses the Filtered Space-Saving algorithm to analyze top values for a column.This is based on the reduce-and-combine method from Parallel Space Saving that uses the approximate frequency to optimize for query speed.
Filter unique values for a given time range.
Query
query TopValuesExample {
  topValues(input: {
    ...
    timeRange: {
      relative: LAST_N_DAYS,
      n: 3
    }
  }) {
    values
  }
}
Specify the maximum number of values to return.
  • Use maxValues to specify the maximum number of values to return. It can be a number between 1 and 1,000. If the parameter is omitted, the default value of 10 is used.
Query
query TopValuesExample {
  topValues(input: {
    ...
    maxValues: 5
  }) {
    values
  }
}

​
Example

​
Example 1: Simple time series query

An example of a query to get the total taco sales for the last 3 days, filtered by the restaurant name “El Buen Sabor”. 
query TimeSeriesExample1 {
  timeSeries(input: {
    metric: {
      sum: {
        dataPool: {
          name: "TacoSoft Demo Data"
        },
        measure: {
          columnName: "taco_total_price"
        }
      }
    },
    granularity: DAY,
    timeRange: {
      relative: LAST_N_DAYS,
      n: 3
    },
    filterSql: "restaurant_name = 'El Buen Sabor'"
  }) {
    labels
    values
  }
}

​
Usage

​
Arguments

The fields for querying the top values in a given column.
​
dataPool
DataPoolInput
required
The Data Pool to be queried. A Data Pool ID or unique name can be provided.
​
columnName
String
required
The column to fetch the unique values from.
​
timeRange
TimeRangeInput
The time range for calculating the top values.
​
timeZone
String
The time zone to use. Dates and times are always returned in UTC, but setting the time zone influences relative time ranges and granularities.You can set this to “America/Los_Angeles”, “Europe/Berlin”, or any other value in the IANA time zone database. Defaults to “UTC”.
​
maxValues
Int
The maximum number of values to return. It can be a number between 1 and 1,000. If the parameter is omitted, default value 10 is used.

​
Response

​
values
[String!]
required
An array with the list of values.

​
Embeddable UI components

Simple Filter component

A React component for rendering top values in a UI filter.

useTopValues

A React Hook for fetching unique values from the Top Values API.
⌘I