> ## Documentation Index
> Fetch the complete documentation index at: https://www.propeldata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Top values

> Get the most frequent non-null values in a column.

<div />

## Use cases

<CardGroup cols={2}>
  <Card title="Populate UI filters">
    Populate filters with unique values.

    <br />

    <Frame>
      <img src="https://mintcdn.com/propeldocs/7MySejCVmSGgOSJb/images/docs/2023-01-11-top-values-use-case-1.png?fit=max&auto=format&n=7MySejCVmSGgOSJb&q=85&s=f007e46bbab63ac1218f690f8b7aefb3" width="1648" height="1052" data-path="images/docs/2023-01-11-top-values-use-case-1.png" />
    </Frame>
  </Card>

  <Card title="AI Agents">
    Prompt LLMs with available values.

    <br />

    <Frame>
      <img src="https://mintcdn.com/propeldocs/7MySejCVmSGgOSJb/images/docs/2023-01-11-top-values-use-case-2.png?fit=max&auto=format&n=7MySejCVmSGgOSJb&q=85&s=073fb6201ad714a1a156c90f60316c4d" width="430" height="300" data-path="images/docs/2023-01-11-top-values-use-case-2.png" />
    </Frame>
  </Card>

  <Card title="Display trending values">
    Display most frequent values.

    <br />

    <Frame>
      <img src="https://mintcdn.com/propeldocs/7MySejCVmSGgOSJb/images/docs/2023-01-11-top-values-use-case-3.png?fit=max&auto=format&n=7MySejCVmSGgOSJb&q=85&s=c3b3290932940ca13d97af30712db522" width="1536" height="1056" data-path="images/docs/2023-01-11-top-values-use-case-3.png" />
    </Frame>
  </Card>
</CardGroup>

## Features

All the [common API features](/docs/query-apis/overview#common-features), plus:

<AccordionGroup>
  <Accordion title="Fast response" icon="bolt">
    The Top Values API uses the [Filtered Space-Saving](https://doi.org/10.1016/j.ins.2010.08.024) algorithm to analyze top values for a column.

    This is based on the reduce-and-combine method from [Parallel Space Saving](https://doi.org/10.1016/j.ins.2015.09.003) that uses the approximate frequency to optimize for query speed.
  </Accordion>

  <Accordion title="Time range filtering" icon="clock">
    Filter unique values for a given time range.

    ```graphql Query theme={"system"}
    query TopValuesExample {
      topValues(input: {
        ...
        timeRange: {
          relative: LAST_N_DAYS,
          n: 3
        }
      }) {
        values
      }
    }
    ```
  </Accordion>

  <Accordion title="Max values" icon="list-ol">
    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.

    ```graphql Query theme={"system"}
    query TopValuesExample {
      topValues(input: {
        ...
        maxValues: 5
      }) {
        values
      }
    }
    ```
  </Accordion>
</AccordionGroup>

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

<CodeGroup>
  ```graphql Query theme={"system"}
  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
    }
  }
  ```

  ```json Response theme={"system"}
  {
    "timeSeries": {
      "labels": [
        "2024-10-06T00:00:00Z",
        "2024-10-07T00:00:00Z",
        "2024-10-08T00:00:00Z"
      ],
      "values": [
        "382",
        "977.25",
        "0"
      ]
    }
  }
  ```
</CodeGroup>

## Usage

## Arguments

The fields for querying the top values in a given column.

<ParamField path="dataPool" type="DataPoolInput" required>
  The Data Pool to be queried. A Data Pool ID or unique name can be provided.

  <Expandable title="DataPoolInput">
    <ParamField path="id" type="ID">
      The ID of the Data Pool.
    </ParamField>

    <ParamField path="name" type="String">
      The name of the Data Pool.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="columnName" type="String" required>
  The column to fetch the unique values from.
</ParamField>

<ParamField path="timeRange" type="TimeRangeInput">
  The time range for calculating the top values.

  <Expandable title="TimeRangeInput">
    The fields required to specify the time range for a time series, counter, or leaderboard Metric query.

    If no relative or absolute time ranges are provided, Propel defaults to an absolute time range beginning with the earliest record in the Metric's Data Pool and ending with the latest record.

    If both relative and absolute time ranges are provided, the relative time range will take precedence.

    If a `LAST_N` relative time period is selected, an `n` ≥ 1 must be provided. If no `n` is provided or `n` \< 1, a `BAD_REQUEST` error will be returned.

    <ParamField path="timestamp" type="String">
      The timestamp field to use when querying. Defaults to the timestamp configured on the Data Pool or Metric, if any.
      Set this to filter on an alternative timestamp field.
    </ParamField>

    <ParamField path="relative" type="RelativeTimeRange">
      The relative time period.

      <Expandable title="RelativeTimeRange">
        The Relative time ranges are based on the current date and time.

        `THIS` - The current unit of time. For example, if today is June 8, 2022, and
        `THIS_MONTH` is selected, then data for June 2022 would be returned.

        `PREVIOUS` - The previous unit of time. For example, if today is June 8, 2022, and
        `PREVIOUS_MONTH` is selected, then data for May 2022 would be returned. It excludes
        the current unit of time.

        `NEXT` - The next unit of time. For example, if today is June 8, 2022, and
        `NEXT_MONTH` is selected, then data for July 2022 would be returned. It excludes
        the current unit of time.

        `LAST_N` - The last `n` units of time, including the current one. For example, if today
        is June 8, 2022 and `LAST_N_YEARS` with `n` = 3 is selected, then data for 2020, 2021, and
        2022 will be returned. It will include the current time period.

        <ParamField path=" ">
          * `THIS_HOUR`: Starts at the zeroth minute of the current hour and continues for 60 minutes.
          * `TODAY`: Starts at 12:00:00 AM of the current day and continues for 24 hours.
          * `THIS_WEEK`: Starts on Monday, 12:00:00 AM of the current week and continues for seven days.
          * `THIS_MONTH`: Starts at 12:00:00 AM on the first day of the current month and continues for the duration of the month.
          * `THIS_QUARTER`: Starts at 12:00:00 AM on the first day of the current calendar quarter and continues for the duration of the quarter.
          * `THIS_YEAR`: Starts on January 1st, 12:00:00 AM of the current year and continues for the duration of the year.
          * `PREVIOUS_HOUR`: Starts at the zeroth minute of the previous hour and continues for 60 minutes.
          * `YESTERDAY`: Starts at 12:00:00 AM on the day before the today and continues for 24 hours.
          * `PREVIOUS_WEEK`: Starts on Monday, 12:00:00 AM, a week before the current week, and continues for seven days.
          * `PREVIOUS_MONTH`: Starts at 12:00:00 AM on the first day of the month before the current month and continues for the duration of the month.
          * `PREVIOUS_QUARTER`: Starts at 12:00:00 AM on the first day of the calendar quarter before the current quarter and continues for the duration of the quarter.
          * `PREVIOUS_YEAR`: Starts on January 1st, 12:00:00 AM, the year before the current year, and continues for the duration of the year.
          * `NEXT_HOUR`:  Starts at the zeroth minute of the next hour and continues for 60 minutes.
          * `TOMORROW`: " Starts at 12:00:00 AM, the day after the current day, and continues for 24 hours.
          * `NEXT_WEEK`: Starts on Monday, 12:00:00 AM, the week after the current week, and continues for the duration of the week.
          * `NEXT_MONTH`: Starts at 12:00:00 AM on the first day of the next month and continues for the duration of the month.
          * `NEXT_QUARTER`: Starts at 12:00:00 AM on the first day of the next calendar quarter and continues for the duration of the quarter.
          * `NEXT_YEAR`: Starts on January 1st, 12:00:00 AM of the next year and continues for the duration of the year.
          * `LAST_N_MINUTES`: Starts at the zeroth second `n` - 1 minute(s) before the current minute and continues through the current minute. It includes this minute.
          * `LAST_N_HOURS`: Starts at the zeroth minute of the `n` - 1 hour(s) before the current hour, and continues through the current hour. It includes this hour.
          * `LAST_N_DAYS`: Starts at 12:00:00 AM, `n` - 1 day(s) before the current day, and continues through the current day. It includes today.
          * `LAST_N_WEEKS`: Starts on Monday, 12:00:00 AM, `n` - 1 week(s) before the current week, and continues through the current week. It includes this week.
          * `LAST_N_MONTHS`: Starts at 12:00:00 AM on the first day of the month, `n` - 1 month(s) before the current month, and continues through the current month. It includes this month.
          * `LAST_N_QUARTERS`: Starts at 12:00:00 AM on the first day of the calendar quarter `n` - 1 quarter(s) before the current quarter and continues through the current quarter. It includes this quarter.
          * `LAST_N_YEARS`: Starts on January 1st, 12:00:00 AM of the year `n` - 1 year(s) before the current year and continues through the current year. It includes this year.
          * `LAST_15_MINUTES`
          * `LAST_30_MINUTES`
          * `LAST_HOUR`
          * `LAST_4_HOURS`
          * `LAST_12_HOURS`
          * `LAST_24_HOURS`
          * `LAST_7_DAYS`
          * `LAST_30_DAYS`
          * `LAST_90_DAYS`
          * `LAST_3_MONTHS`
          * `LAST_6_MONTHS`
          * `LAST_YEAR`
          * `LAST_2_YEARS`
          * `LAST_5_YEARS`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="n" type="Int">
      The number of time units for the `LAST_N` relative periods.
    </ParamField>

    <ParamField path="start" type="DateTime">
      The optional start timestamp (inclusive). Defaults to the timestamp of the earliest record in the Data Pool.
    </ParamField>

    <ParamField path="stop" type="DateTime">
      The optional end timestamp (exclusive). Defaults to the timestamp of the latest record in the Data Pool.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="timeZone" type="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](https://en.wikipedia.org/wiki/Tz_database). Defaults to "UTC".
</ParamField>

<ParamField path="maxValues" type="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.
</ParamField>

## Response

<ParamField path="values" type="[String!]" required>
  An array with the list of values.
</ParamField>

## Embeddable UI components

<CardGroup cols={2}>
  <Card title="Simple Filter component" icon="React" href="/docs/embeddable-ui/components/simple-filter">
    A React component for rendering top values in a UI filter.
  </Card>

  <Card title="useTopValues" icon="code" href="/docs/embeddable-ui/components/use-top-values">
    A React Hook for fetching unique values from the Top Values API.
  </Card>
</CardGroup>