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

# maxValuesPerFacet

> The maximum number of values to return for each facet

export const Setting = ({type, default: defaultValue, defaultNote, scope, min, max, formerly}) => {
  const renderedDefault = defaultValue === '' ? '""' : defaultValue;
  const renderedNote = defaultNote ? `(${defaultNote})` : '';
  return <ul>
      <li><strong>Type:</strong> <code>{type}</code></li>
      <li><strong>Default:</strong> <code>{renderedDefault}</code>{renderedNote}</li>
      {min && <li><strong>Min:</strong> <code>{min}</code></li>}
      {max && <li><strong>Max:</strong> <code>{max}</code></li>}
      <li><strong>Scope:</strong> <a href="/doc/api-reference/api-parameters"><code>{scope}</code></a></li>
      {formerly && <li>
          <strong>Deprecated name:</strong> <code>{formerly}</code>
        </li>}
    </ul>;
};

<Setting type="integer" default="100" scope="settings,search" max="1,000" />

The `maxValuesPerFacet` parameter limits how many facet values are returned per facet in the search response.
This helps you focus the user experience on the most relevant facet values,
especially in cases where a facet (like `brand`, `author`, or `genre`) has many possible values.

<Info>
  Don't confuse `maxValuesPerFacet` with [`maxFacetHits`](/doc/api-reference/api-parameters/maxFacetHits).
  `maxFacetHits` sets the maximum number of returned results when [searching for facet values](/doc/rest-api/search/search-for-facet-values).
</Info>

## Usage

The maximum value for `maxValuesPerFacet` is 1,000.
You can set it higher but the engine will interpret it as 1,000.

## Examples

### Set the default number of facet values to retrieve

<AccordionGroup>
  <Accordion title="Current API clients" defaultOpen="true">
    <CodeGroup>
      ```cs C# theme={"system"}
      var response = await client.SetSettingsAsync(
        "INDEX_NAME",
        new IndexSettings { MaxValuesPerFacet = 100 }
      );
      ```

      ```dart Dart theme={"system"}
      final response = await client.setSettings(
        indexName: "INDEX_NAME",
        indexSettings: IndexSettings(
          maxValuesPerFacet: 100,
        ),
      );
      ```

      ```go Go theme={"system"}
      response, err := client.SetSettings(client.NewApiSetSettingsRequest(
        "INDEX_NAME",
        search.NewEmptyIndexSettings().SetMaxValuesPerFacet(100)))
      if err != nil {
        // handle the eventual error
        panic(err)
      }
      ```

      ```java Java theme={"system"}
      UpdatedAtResponse response = client.setSettings("INDEX_NAME", new IndexSettings().setMaxValuesPerFacet(100));
      ```

      ```js JavaScript theme={"system"}
      const response = await client.setSettings({ indexName: 'theIndexName', indexSettings: { maxValuesPerFacet: 100 } });
      ```

      ```kotlin Kotlin theme={"system"}
      var response =
        client.setSettings(
          indexName = "INDEX_NAME",
          indexSettings = IndexSettings(maxValuesPerFacet = 100),
        )
      ```

      ```php PHP theme={"system"}
      $response = $client->setSettings(
          'INDEX_NAME',
          ['maxValuesPerFacet' => 100,
          ],
      );
      ```

      ```python Python theme={"system"}
      response = client.set_settings(
          index_name="INDEX_NAME",
          index_settings={
              "maxValuesPerFacet": 100,
          },
      )
      ```

      ```ruby Ruby theme={"system"}
      response = client.set_settings("INDEX_NAME", Algolia::Search::IndexSettings.new(max_values_per_facet: 100))
      ```

      ```scala Scala theme={"system"}
      val response = Await.result(
        client.setSettings(
          indexName = "INDEX_NAME",
          indexSettings = IndexSettings(
            maxValuesPerFacet = Some(100)
          )
        ),
        Duration(100, "sec")
      )
      ```

      ```swift Swift theme={"system"}
      let response = try await client.setSettings(
          indexName: "INDEX_NAME",
          indexSettings: IndexSettings(maxValuesPerFacet: 100)
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Legacy API clients">
    <CodeGroup>
      ```cs C# theme={"system"}
      IndexSettings settings = new IndexSettings();
      settings.MaxValuesPerFacet = 100;

      index.SetSettings(settings);
      ```

      ```go Go theme={"system"}
      res, err := index.SetSettings(search.Settings{
      	opt.MaxValuesPerFacet(100),
      })
      ```

      ```java Java theme={"system"}
      index.setSettings(
        new IndexSettings().setMaxValuesPerFacet(100)
      );
      ```

      ```js JavaScript theme={"system"}
      index
        .setSettings({
          maxValuesPerFacet: 100,
        })
        .then(() => {
          // done
        });
      ```

      ```kotlin Kotlin theme={"system"}
      val settings = settings {
          maxValuesPerFacet = 100
      }

      index.setSettings(settings)
      ```

      ```php PHP theme={"system"}
      $index->setSettings([
        'maxValuesPerFacet' => 100
      ]);
      ```

      ```python Python theme={"system"}
      index.set_settings({"maxValuesPerFacet": 100})
      ```

      ```ruby Ruby theme={"system"}
      index.set_settings(
        {
          maxValuesPerFacet: 100
        }
      )
      ```

      ```scala Scala theme={"system"}
      client.execute {
        setSettings of "myIndex" `with` IndexSettings(
          maxValuesPerFacet = Some(100)
        )
      }
      ```

      ```swift Swift theme={"system"}
      let settings = Settings()
        .set(\.maxValuesPerFacet, to: 100)

      index.setSettings(settings) { result in
        if case .success(let response) = result {
          print("Response: \(response)")
        }
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

### Set the maximum number of facet values for the current query

<AccordionGroup>
  <Accordion title="Current API clients" defaultOpen>
    This search setting will override the default `maxValuesPerFacet` setting for the current search.

    <CodeGroup>
      ```cs C# theme={"system"}
      var response = await client.SearchSingleIndexAsync<Hit>(
        "INDEX_NAME",
        new SearchParams(new SearchParamsObject { Query = "query", MaxValuesPerFacet = 20 })
      );
      ```

      ```dart Dart theme={"system"}
      final response = await client.searchSingleIndex(
        indexName: "INDEX_NAME",
        searchParams: SearchParamsObject(
          query: "query",
          maxValuesPerFacet: 20,
        ),
      );
      ```

      ```go Go theme={"system"}
      response, err := client.SearchSingleIndex(client.NewApiSearchSingleIndexRequest(
        "INDEX_NAME").WithSearchParams(search.SearchParamsObjectAsSearchParams(
        search.NewEmptySearchParamsObject().SetQuery("query").SetMaxValuesPerFacet(20))))
      if err != nil {
        // handle the eventual error
        panic(err)
      }
      ```

      ```java Java theme={"system"}
      SearchResponse response = client.searchSingleIndex(
        "INDEX_NAME",
        new SearchParamsObject().setQuery("query").setMaxValuesPerFacet(20),
        Hit.class
      );
      ```

      ```js JavaScript theme={"system"}
      const response = await client.searchSingleIndex({
        indexName: 'indexName',
        searchParams: { query: 'query', maxValuesPerFacet: 20 },
      });
      ```

      ```kotlin Kotlin theme={"system"}
      var response =
        client.searchSingleIndex(
          indexName = "INDEX_NAME",
          searchParams = SearchParamsObject(query = "query", maxValuesPerFacet = 20),
        )
      ```

      ```php PHP theme={"system"}
      $response = $client->searchSingleIndex(
          'INDEX_NAME',
          ['query' => 'query',
              'maxValuesPerFacet' => 20,
          ],
      );
      ```

      ```python Python theme={"system"}
      response = client.search_single_index(
          index_name="INDEX_NAME",
          search_params={
              "query": "query",
              "maxValuesPerFacet": 20,
          },
      )
      ```

      ```ruby Ruby theme={"system"}
      response = client.search_single_index(
        "INDEX_NAME",
        Algolia::Search::SearchParamsObject.new(query: "query", max_values_per_facet: 20)
      )
      ```

      ```scala Scala theme={"system"}
      val response = Await.result(
        client.searchSingleIndex(
          indexName = "INDEX_NAME",
          searchParams = Some(
            SearchParamsObject(
              query = Some("query"),
              maxValuesPerFacet = Some(20)
            )
          )
        ),
        Duration(100, "sec")
      )
      ```

      ```swift Swift theme={"system"}
      let response: SearchResponse<Hit> = try await client.searchSingleIndex(
          indexName: "INDEX_NAME",
          searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
              query: "query",
              maxValuesPerFacet: 20
          ))
      )
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Legacy API clients">
    This search setting will override the default `maxValuesPerFacet` setting for the current search.

    <CodeGroup>
      ```cs C# theme={"system"}
      var query = new Query("query")
      {
        MaxValuesPerFacet = 20
      };
      ```

      ```go Go theme={"system"}
      res, err := index.Search(
      	"query",
      	opt.MaxValuesPerFacet(20),
      )
      ```

      ```java Java theme={"system"}
      index.search(
        new Query("query").setMaxValuesPerFacet(20L)
      );
      ```

      ```js JavaScript theme={"system"}
      index
        .search("query", {
          maxValuesPerFacet: 20,
        })
        .then(({ hits }) => {
          console.log(hits);
        });
      ```

      ```kotlin Kotlin theme={"system"}
      val query = query("query") {
          maxValuesPerFacet = 20
      }

      index.search(query)
      ```

      ```php PHP theme={"system"}
      $results = $index->search('query', [
        'maxValuesPerFacet' => 20
      ]);
      ```

      ```python Python theme={"system"}
      results = index.search("query", {"maxValuesPerFacet": 20})
      ```

      ```ruby Ruby theme={"system"}
      results = index.search(
        "query",
        {
          maxValuesPerFacet: 20
        }
      )
      ```

      ```scala Scala theme={"system"}
      client.execute {
        search into "myIndex" query Query(
          query = Some("query"),
          maxValuesPerFacet = Some(20)
        )
      }
      ```

      ```swift Swift theme={"system"}
      let query = Query("query")
        .set(\.maxValuesPerFacet, to: 20)

      index.search(query: query) { result in
        if case .success(let response) = result {
          print("Response: \(response)")
        }
      }
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>