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

# Leaderboard

> Get aggregated values grouped by common dimensions.

<div />

## Use cases

<CardGroup cols={2}>
  <Card title="Leaderboard visualization">
    Visualize leaderboard data in your apps.

    <br />

    <Frame>
      <img src="https://mintcdn.com/propeldocs/9FdNDTkhOu7EgAUd/images/docs/leaderboard_use_case_1.png?fit=max&auto=format&n=9FdNDTkhOu7EgAUd&q=85&s=0380b362796590ae138d079ef53c77ff" width="400" height="300" data-path="images/docs/leaderboard_use_case_1.png" />
    </Frame>
  </Card>

  <Card title="Aggregated tables">
    Display aggregated data in tables.

    <br />

    <Frame>
      <img src="https://mintcdn.com/propeldocs/9FdNDTkhOu7EgAUd/images/docs/leaderboard_use_case_2.png?fit=max&auto=format&n=9FdNDTkhOu7EgAUd&q=85&s=925a72dc9e066030ce481bcd6729eb24" width="400" height="300" data-path="images/docs/leaderboard_use_case_2.png" />
    </Frame>
  </Card>
</CardGroup>

## Features

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

<AccordionGroup>
  <Accordion title="Group by dimensions" icon="table-columns">
    Group the results by one or more dimensions.

    * Use `dimensions` in the query to specify the dimensions to group by

    ```graphql theme={"system"}
    query LeaderboardExample {
      leaderboard(input: {
        ...
        dimensions: [
          {
            columnName: "restaurant_name"
          }
        ]
        ...
      }) {
        headers
        rows
      }
    }
    ```
  </Accordion>

  <Accordion title="Ordering" icon="sort">
    Order the results based on a sort direction.

    * Use `sort` to specify the sort direction (ASC or DESC)

    ```graphql theme={"system"}
    query LeaderboardExample {
      leaderboard(input: {
        ...
        sort: DESC
        ...
      }) {
        rows
      }
    }
    ```
  </Accordion>

  <Accordion title="Row limit" icon="list">
    Limit the number of rows returned.

    * Use `rowLimit` to specify the maximum number of rows to return

    ```graphql theme={"system"}
    query LeaderboardExample {
      leaderboard(input: {
        ...
        rowLimit: 10
        ...
      }) {
        rows
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Example

### Example 1: Simple leaderboard query

Get top 3 restaurants by total taco sales for the current year.

<CodeGroup>
  ```graphql Query theme={"system"}
  query LeaderboardExample1 {
    leaderboard(input: {
      metric: {
        sum: {
          dataPool: {
            name: "TacoSoft Demo Data"
          },
          measure: {
            columnName: "taco_total_price"
          }
        }
      },
      sort: DESC,
      timeRange: {
        relative: THIS_YEAR,
        n: null
      },
      rowLimit: 3,
      dimensions: [
        {
          columnName: "restaurant_name"
        }
      ],
    }) {
      headers
      rows
    }
  }
  ```

  ```json Response theme={"system"}
  {
    "leaderboard": {
      "headers": [
        "restaurant_name",
        "value"
      ],
      "rows": [
        [
          "Taqueria Vallarta",
          "290208.75"
        ],
        [
          "Taqueria Cancun",
          "280639"
        ],
        [
          "La Taqueria",
          "276774.75"
        ]
      ]
    }
  }
  ```
</CodeGroup>

## Usage

## Arguments

The fields for querying a Metric in leaderboard format.

A Metric's leaderboard query returns an ordered table of Dimension and Metric values over a given time range.

<ParamField path="metric" type="MetricInput">
  The Metric to query. You can query a pre-configured Metric by ID or name, or you can query an ad hoc Metric that you define inline.

  <Expandable title="MetricInput">
    <ParamField path="id" type="ID">
      The ID of a pre-configured Metric.
    </ParamField>

    <ParamField path="name" type="String">
      The name of a pre-configured Metric.
    </ParamField>

    <ParamField path="custom" type="CustomMetricQueryInput">
      An ad hoc Custom Metric.

      <Expandable title="CustomMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="expression" type="String" required>
          Custom expression for defining the Metric.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="count" type="CountMetricQueryInput">
      An ad hoc Count Metric.

      <Expandable title="CountMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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>
      </Expandable>
    </ParamField>

    <ParamField path="sum" type="SumMetricQueryInput">
      An ad hoc Sum Metric.

      <Expandable title="SumMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="measure" type="DimensionInput" required>
          The column to be summed.

          <Expandable title="DimensionInput">
            The fields for creating or modifying a Dimension.

            <ParamField path="columnName" type="String" required>
              The name of the column to create the Dimension from.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="average" type="AverageMetricQueryInput">
      An ad hoc Average Metric.

      <Expandable title="AverageMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="measure" type="DimensionInput" required>
          The column to be averaged.

          <Expandable title="DimensionInput">
            The fields for creating or modifying a Dimension.

            <ParamField path="columnName" type="String" required>
              The name of the column to create the Dimension from.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="min" type="MinMetricQueryInput">
      An ad hoc Min Metric.

      <Expandable title="MinMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="measure" type="DimensionInput" required>
          The column to calculate the minimum from.

          <Expandable title="DimensionInput">
            The fields for creating or modifying a Dimension.

            <ParamField path="columnName" type="String" required>
              The name of the column to create the Dimension from.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="max" type="MaxMetricQueryInput">
      An ad hoc Max Metric.

      <Expandable title="MaxMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="measure" type="DimensionInput" required>
          The column to calculate the maximum from.

          <Expandable title="DimensionInput">
            The fields for creating or modifying a Dimension.

            <ParamField path="columnName" type="String" required>
              The name of the column to create the Dimension from.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="countDistinct" type="CountDistinctMetricQueryInput">
      An ad hoc Count Distinct Metric.

      <Expandable title="CountDistinctMetricQueryInput">
        <ParamField path="dataPool" type="DataPoolInput" required>
          The Data Pool to which this Metric belongs.

          <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="dimension" type="DimensionInput" required>
          The column to count distinct values from.

          <Expandable title="DimensionInput">
            The fields for creating or modifying a Dimension.

            <ParamField path="columnName" type="String" required>
              The name of the column to create the Dimension from.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

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

  <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="dimensions" type="[DimensionInput!]" required>
  One or many Dimensions to group the Metric values by. Typically, Dimensions in a leaderboard are what you want to compare and rank.

  <Expandable title="DimensionInput">
    The fields for creating or modifying a Dimension.

    <ParamField path="columnName" type="String" required>
      The name of the column to create the Dimension from.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="sort" type="Sort">
  The sort order of the rows. It can be ascending (`ASC`) or descending (`DESC`) order. Defaults to descending (`DESC`) order when not provided.

  <Expandable title="Sort">
    The available sort orders.

    <ParamField path=" ">
      * `ASC`: Sort in ascending order.
      * `DESC`: Sort in descending order.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="rowLimit" type="Int" required>
  The number of rows to be returned. It can be a number between 1 and 1,000.
</ParamField>

<ParamField path="filterSql" type="String">
  The Query Filters to apply before retrieving the leaderboard data, in the form of SQL. If no Query Filters are provided, all data is included.
</ParamField>

<Expandable title="Deprecated Fields">
  <ParamField path="metricId" type="ID" deprecated>
    The ID of the Metric to query.

    Required if `metricName` is not specified.

    <span style={{ fontStyle: 'italic' }}>deprecated: Use `metric`</span>
  </ParamField>

  <ParamField path="metricName" type="String" deprecated>
    The name of the Metric to query.

    Required if `metricId` is not specified.

    <span style={{ fontStyle: 'italic' }}>deprecated: Use `metric`</span>
  </ParamField>

  <ParamField path="filters" type="[FilterInput!]" deprecated>
    The Query Filters to apply before retrieving the leaderboard data. If no Query Filters are provided, all data is included.

    <span style={{ fontStyle: 'italic' }}>deprecated: Use `filterSql` instead</span>

    <Expandable title="FilterInput">
      The fields of a filter.

      You can construct more complex filters using `and` and `or`. For example, to construct a filter equivalent to

      ```
      (value > 0 AND value <= 100) OR status = "confirmed"
      ```

      you could write

      ```
      {
        "column": "value",
        "operator": "GREATER_THAN",
        "value": "0",
        "and": [{
          "column": "value",
          "operator": "LESS_THAN_OR_EQUAL_TO",
          "value": "0"
        }],
        "or": [{
          "column": "status",
          "operator": "EQUALS",
          "value": "confirmed"
        }]
      }
      ```

      Note that `and` takes precedence over `or`.

      <ParamField path="column" type="String" required>
        The name of the column to filter on.
      </ParamField>

      <ParamField path="operator" type="FilterOperator" required>
        The operation to perform when comparing the column and filter values.

        <Expandable title="FilterOperator">
          The available Filter operators.

          <ParamField path=" ">
            * `EQUALS`:  Selects values that are equal to the specified value.
            * `NOT_EQUALS`:  Selects values that are not equal to the specified value.
            * `GREATER_THAN`:  Selects values that are greater than the specified value.
            * `GREATER_THAN_OR_EQUAL_TO`:  Selects values that are greater or equal to the specified value.
            * `LESS_THAN`:  Selects values that are less than the specified value.
            * `LESS_THAN_OR_EQUAL_TO`:  Selects values that are less or equal to the specified value.
            * `IS_NULL`:  Selects values that are null. This operator does not accept a value.
            * `IS_NOT_NULL`:  Selects values that are not null. This operator does not accept a value.
            * `LIKE`:  Selects values that match the specified pattern.
            * `NOT_LIKE`:  "Selects values that do not match the specified pattern.
          </ParamField>
        </Expandable>
      </ParamField>

      <ParamField path="value" type="String">
        The value to compare the column to.
      </ParamField>

      <ParamField path="and" type="[FilterInput!]">
        Additional filters to AND with this one. AND takes precedence over OR.
      </ParamField>

      <ParamField path="or" type="[FilterInput!]">
        Additional filters to OR with this one. AND takes precedence over OR.
      </ParamField>
    </Expandable>
  </ParamField>
</Expandable>

## Response

The leaderboard response object. It contains an array of headers and a table (array of rows) with the selected Dimensions and corresponding Metric values for the given time range and Query Filters.

<ParamField path="headers" type="[String!]" required>
  The table headers. It contains the Dimension and Metric names.
</ParamField>

<ParamField path="rows" type="[[String]!]" required>
  An ordered array of rows. Each row contains the Dimension values and the corresponding Metric value. A Dimension value can be empty. A Metric value will never be empty.
</ParamField>

<ParamField path="query" type="QueryInfo" required>
  The Query statistics and metadata.

  <Expandable title="QueryInfo">
    The Query Info object. It contains metadata and statistics about a Query performed.

    <ParamField path="id" type="ID" required>
      The Query's unique identifier.
    </ParamField>

    <ParamField path="createdAt" type="DateTime" required>
      The date and time in UTC when the Query was created.
    </ParamField>

    <ParamField path="createdBy" type="String" required>
      The unique identifier of the actor that performed the Query.
    </ParamField>

    <ParamField path="modifiedAt" type="DateTime" required>
      The date and time in UTC when the Query was last modified.
    </ParamField>

    <ParamField path="modifiedBy" type="String" required>
      The unique identifier of the actor that modified the Query.
    </ParamField>

    <ParamField path="bytesProcessed" type="String" required>
      The bytes processed by the Query.
    </ParamField>

    <ParamField path="durationInMilliseconds" type="Int" required>
      The duration of the Query in milliseconds.
    </ParamField>

    <ParamField path="recordsProcessed" type="String" required>
      The number of records processed by the Query.
    </ParamField>

    <ParamField path="resultingBytes" type="Int" required>
      The bytes returned by the Query.
    </ParamField>

    <ParamField path="resultingRecords" type="Int" required>
      The number of records returned by the Query.
    </ParamField>

    <ParamField path="propeller" type="Propeller">
      The Propeller used for this query.

      <Expandable title="Propeller">
        A Propeller determines your Application's query processing power. The larger the Propeller, the faster the queries and the higher the cost. Every Propel Application (and therefore every set of API credentials) has a Propeller that determines the speed and cost of queries.

        <ParamField path=" ">
          * `P1_X_SMALL`: Max records per second: 5,000,000 records per second
          * `P1_SMALL`: Max records per second: 25,000,000 records per second
          * `P1_MEDIUM`: Max records per second: 100,000,000 records per second
          * `P1_LARGE`: Max records per second: 250,000,000 records per second
          * `P1_X_LARGE`: Max records per second: 500,000,000 records per second
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="status" type="QueryStatus" required>
      The Query status.

      <Expandable title="QueryStatus">
        The Query status.

        <ParamField path=" ">
          * `COMPLETED`: The Query was completed succesfully.
          * `ERROR`: The Query experienced an error.
          * `TIMED_OUT`: The Query timed out.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="type" type="QueryType" required>
      The Query type.

      <Expandable title="QueryType">
        The Query type.

        <ParamField path=" ">
          * `METRIC`: Indicates a Metric Query.
          * `STATS`: Indicates a Dimension Stats Query.
          * `REPORT`: Indicates a Report Query.
          * `RECORDS`: Indicates a Record Table Query.
          * `RECORDS_BY_UNIQUE_ID`: Indicates records queried by unique ID.
          * `SQL`: Indicates a SQL Query.
          * `TOP_VALUES`: Indicates a Top Values Query.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="subtype" type="QuerySubtype">
      The Query subtype.

      <Expandable title="QuerySubtype">
        The Query subtype.

        <ParamField path=" ">
          * `COUNTER`: Indicates a Metric counter Query.
          * `TIME_SERIES`: Indicates a Metric time series Query.
          * `LEADERBOARD`: Indicates a Metric leaderboard Query.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="sql" type="String" required>
      The SQL the query executed.
    </ParamField>
  </Expandable>
</ParamField>

## Embeddable UI components

<CardGroup cols={2}>
  <Card title="Leaderboard component" icon="React" href="/docs/embeddable-ui/components/leaderboard">
    A React component for rendering leaderboard data.
  </Card>

  <Card title="useLeaderboard" icon="code" href="/docs/embeddable-ui/components/use-leaderboard">
    A React Hook for fetching ranked data from the Leaderboard API.
  </Card>
</CardGroup>