# Faceting
URL: /docs/faceting

Count matching documents per field value, over the whole result set.



The `facet` search parameter takes a comma-separated list of fields declared
`facet: true`, and returns a value → count breakdown for each, computed over
**every** matching document — not just the current page:

<Tabs items="['cURL', 'TypeScript', 'Python', 'C#']">
  <Tab value="cURL">
    ```bash
    curl 'localhost:8108/collections/products/search?q=keyboard&facet=brand'
    ```
  </Tab>

  <Tab value="TypeScript">
    ```ts
    import { Tachyon } from 'tachyon-sdk';

    const client = new Tachyon({ url: 'http://localhost:8108' });

    const results = await client.collection('products').search({ q: 'keyboard', facet: ['brand'] });
    console.log(results.facets?.brand);
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from tachyon_sdk import Tachyon

    client = Tachyon(url="http://localhost:8108")

    results = client.collection("products").search(q="keyboard", facet=["brand"])
    print(results["facets"]["brand"])
    ```
  </Tab>

  <Tab value="C#">
    ```csharp
    using Tachyon.Sdk;

    var client = new TachyonClient(new TachyonClientOptions { Url = "http://localhost:8108" });

    var results = await client.Collection("products").SearchAsync(new SearchParams { Q = "keyboard", Facet = ["brand"] });
    Console.WriteLine(results.Facets?["brand"]);
    ```
  </Tab>
</Tabs>

```json
{
  "found": 42,
  "hits": [ "..." ],
  "facets": {
    "brand": { "Logitech": 12, "Razer": 8, "Corsair": 5 }
  }
}
```

## Notes [#notes]

* Counts are ordered most-common first.
* Each field is capped at its 100 most common values.
* Numeric and boolean values are rendered as string keys (`"2024": 3`,
  booleans as `"1"`/`"0"`).
* A multi-valued field counts a document once per distinct value it holds,
  so per-value counts across a facet can sum to more than `found`.
* A field not declared `facet: true` in the schema returns a
  `400 invalid_query` error if passed to `facet`.