Skip to main content
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.
Don’t confuse maxValuesPerFacet with maxFacetHits. maxFacetHits sets the maximum number of returned results when searching for facet values.

​
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

Current API clients

var response = await client.SetSettingsAsync(
  "INDEX_NAME",
  new IndexSettings { MaxValuesPerFacet = 100 }
);

final response = await client.setSettings(
  indexName: "INDEX_NAME",
  indexSettings: IndexSettings(
    maxValuesPerFacet: 100,
  ),
);

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

UpdatedAtResponse response = client.setSettings("INDEX_NAME", new IndexSettings().setMaxValuesPerFacet(100));

const response = await client.setSettings({ indexName: 'theIndexName', indexSettings: { maxValuesPerFacet: 100 } });

var response =
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(maxValuesPerFacet = 100),
  )

$response = $client->setSettings(
    'INDEX_NAME',
    ['maxValuesPerFacet' => 100,
    ],
);

response = client.set_settings(
    index_name="INDEX_NAME",
    index_settings={
        "maxValuesPerFacet": 100,
    },
)

response = client.set_settings("INDEX_NAME", Algolia::Search::IndexSettings.new(max_values_per_facet: 100))

val response = Await.result(
  client.setSettings(
    indexName = "INDEX_NAME",
    indexSettings = IndexSettings(
      maxValuesPerFacet = Some(100)
    )
  ),
  Duration(100, "sec")
)

let response = try await client.setSettings(
    indexName: "INDEX_NAME",
    indexSettings: IndexSettings(maxValuesPerFacet: 100)
)

IndexSettings settings = new IndexSettings();
settings.MaxValuesPerFacet = 100;

index.SetSettings(settings);

res, err := index.SetSettings(search.Settings{
	opt.MaxValuesPerFacet(100),
})

index.setSettings(
  new IndexSettings().setMaxValuesPerFacet(100)
);

index
  .setSettings({
    maxValuesPerFacet: 100,
  })
  .then(() => {
    // done
  });

val settings = settings {
    maxValuesPerFacet = 100
}

index.setSettings(settings)

$index->setSettings([
  'maxValuesPerFacet' => 100
]);

index.set_settings({"maxValuesPerFacet": 100})

index.set_settings(
  {
    maxValuesPerFacet: 100
  }
)

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

let settings = Settings()
  .set(\.maxValuesPerFacet, to: 100)

index.setSettings(settings) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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

Current API clients

This search setting will override the default maxValuesPerFacet setting for the current search.
var response = await client.SearchSingleIndexAsync<Hit>(
  "INDEX_NAME",
  new SearchParams(new SearchParamsObject { Query = "query", MaxValuesPerFacet = 20 })
);

final response = await client.searchSingleIndex(
  indexName: "INDEX_NAME",
  searchParams: SearchParamsObject(
    query: "query",
    maxValuesPerFacet: 20,
  ),
);

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)
}

SearchResponse response = client.searchSingleIndex(
  "INDEX_NAME",
  new SearchParamsObject().setQuery("query").setMaxValuesPerFacet(20),
  Hit.class
);

const response = await client.searchSingleIndex({
  indexName: 'indexName',
  searchParams: { query: 'query', maxValuesPerFacet: 20 },
});

var response =
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = SearchParamsObject(query = "query", maxValuesPerFacet = 20),
  )

$response = $client->searchSingleIndex(
    'INDEX_NAME',
    ['query' => 'query',
        'maxValuesPerFacet' => 20,
    ],
);

response = client.search_single_index(
    index_name="INDEX_NAME",
    search_params={
        "query": "query",
        "maxValuesPerFacet": 20,
    },
)

response = client.search_single_index(
  "INDEX_NAME",
  Algolia::Search::SearchParamsObject.new(query: "query", max_values_per_facet: 20)
)

val response = Await.result(
  client.searchSingleIndex(
    indexName = "INDEX_NAME",
    searchParams = Some(
      SearchParamsObject(
        query = Some("query"),
        maxValuesPerFacet = Some(20)
      )
    )
  ),
  Duration(100, "sec")
)

let response: SearchResponse<Hit> = try await client.searchSingleIndex(
    indexName: "INDEX_NAME",
    searchParams: SearchSearchParams.searchSearchParamsObject(SearchSearchParamsObject(
        query: "query",
        maxValuesPerFacet: 20
    ))
)
This search setting will override the default maxValuesPerFacet setting for the current search.
var query = new Query("query")
{
  MaxValuesPerFacet = 20
};

res, err := index.Search(
	"query",
	opt.MaxValuesPerFacet(20),
)

index.search(
  new Query("query").setMaxValuesPerFacet(20L)
);

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

val query = query("query") {
    maxValuesPerFacet = 20
}

index.search(query)

$results = $index->search('query', [
  'maxValuesPerFacet' => 20
]);

results = index.search("query", {"maxValuesPerFacet": 20})

results = index.search(
  "query",
  {
    maxValuesPerFacet: 20
  }
)

client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    maxValuesPerFacet = Some(20)
  )
}

let query = Query("query")
  .set(\.maxValuesPerFacet, to: 20)

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}
Last modified on May 19, 2026