Skip to main content

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 FiltersPrompt AI AgentsDisplay trending values
Data table exampleLog interface exampleLog interface example
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.

FieldTypeRequiredDescription
dataPoolDataPoolInputYes

The Data Pool to be queried. A Data Pool ID or unique name can be provided.

columnNameStringYes

The column to fetch the unique values from.

timeRangeTimeRangeInputNo

The time range for calculating the top values.

timeZoneStringNo

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".

maxValuesIntNo

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.

FieldTypeNullableDescription
values array of StringNo

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.


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
}
}