Top Values

The Top Values API returns an array of the most frequent non-null values in a given column. The resulting array is sorted in descending order of approximate frequency of values.

Use cases

You can use the Top Values API to populate UI filters, prompt AI agents with available values, or display trending values for a column.

Populate UI Filters	Prompt AI Agents	Display trending values
Populate dropdowns with the available values for a column.	Prompt LLMs with the available values to increase accuracy.	Easily show trending values for a given time range.

Features

• Fast response: 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.
• Access-Policy aware: The Top Values API respects row-based access control rules defined in Access Policies. This means that in multi-tenant applications, each tenant will only see the values corresponding to their records.

Usage

Arguments

The table below describes the input parameters for the Top Values API. These parameters allow you to specify the column name, time range, and the maximum number of values to return.

Field	Type	Required	Description
dataPool	DataPoolInput	Yes	The Data Pool to be queried. A Data Pool ID or unique name can be provided.
columnName	String	Yes	The column to fetch the unique values from.
timeRange	TimeRangeInput	No	The time range for calculating the top values.
timeZone	String	No	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	No	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.

Read more about TopValuesInput.

Response

The Top Values API responds with a TopValuesResponse object that includes a values array with the list of unique values. Null values will not be returned as part of the top values.

Field	Type	Nullable	Description
values	array of String	No	An array with the list of values.

Read more about TopValuesResponse.

Example

The following example demonstrates how to use the Top Values API to query trending tacos for this month.

GraphQL Query

Query:

query TopValuesQuery($input: TopValuesInput!) {
  topValues(input: $input) {
    values
  }
}

Variables:

{
  "input": {
    "dataPool": {
      "name": "TacoSoft Demo Data"
    },
    "columnName": "taco_name",
    "timeRange": {
      "relative": "THIS_MONTH"
    },
    "maxValues": 5
  }
}

JSON Response

{
  "data": {
    "topValues": {
      "values": [
        "Al Pastor",
        "Breakfast",
        "Carnitas",
        "Vegetarian",
        "Carne Asada"
      ]
    }
  }
}