---
title: Facet queries
slug: data-platform/docs/facet-queries
docTags: 
createdAt: 2026-08-10T12:05:18.000Z
---

You can use GraphQL to return aggregated results for dimension columns. For example, if you want to check the most frequently used name in your `customers` dimension, execute the following GraphQL query:

```graphql
query {
  customers {
    facets {
      name {
        name
        count
      }
    }
  }
}
```

The response returns the aggregated results:

```graphql
{
  "data": {
    "customers": {
      "facets": {
          "name": [
            {
              "name": "Chandler",
              "count": 176
            },
            {
              "name": "Ross",
              "count": 156
            },
            {
              "name": "Phoebe",
              "count": 151
            },
            {
              "name": "Monica",
              "count": 145
            },
            {
              "name": "Joey",
              "count": 134
            },
            {
              "name": "Rachel",
              "count": 127
            },
            {
              "name": "Ursula",
              "count": 120
            },
            {
              "name": "Amy",
              "count": 113
            },
            {
              "name": "Paolo",
              "count": 104
            },
            {
              "name": "Paul",
              "count": 100
            }
          ]
      }
    }
  }
}
```

The facet query returns up to 10 aggregated results sorted in descending order based on popularity (number of occurrences) in the data set.

You can use the`istarts_with` filter to return aggregations on a more narrow data set. The `istarts_with` filter is not case sensitive. Therefore, if you set `istarts_with` to `a`, both "Ashley" and "andrew" will match the filter.

A filtered example is shown below:

```graphql
query {
  customers {
    facets {
      name(istarts_with: "J") {
        name
        count
      }
    }
  }
}
```

Which returns the following response:

```graphql
{
  "data": {
    "customers": {
      "facets": {
          "name": [
            {
              "name": "Joey",
              "count": 134
            },
            {
              "name": "Joshua",
              "count": 96
            },
            {
              "name": "Janice",
              "count": 25
            },
            {
              "name": "Jack",
              "count": 25
            },
            {
              "name": "Janine",
              "count": 21
            },
            {
              "name": "Julie",
              "count": 19
            },
            {
              "name": "Jade",
              "count": 15
            },
            {
              "name": "Judy",
              "count": 5
            }
          ]
      }
    }
  }
}
```

:::hint{type="info"}
**Note**
Facet queries only work for `text` columns.
:::