facets
'facets' => [ 'attribute', ... ]
Can be used in these methods:
search,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
search,
search_for_facet_values,
generate_secured_api_key,
add_api_key,
update_api_key
search,
searchForFacetValues,
generateSecuredApiKey,
addAPIKey,
updateAPIKey
search,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
SearchForFacetValues,
GenerateSecuredApiKeys,
AddApiKey,
UpdateApiKey
Search,
searchForFacetValues,
generateSecuredApiKey,
addApiKey,
updateApiKey
Search,
SearchForFacetValues,
GenerateSecuredAPIKey,
AddAPIKey,
UpdateAPIKey
search,
search into facet values,
generateSecuredApiKey,
add key,
update key
About this parameter
Retrieve facets, their facet values, and the number of matching facet values.
For each specified facet (for example, color
, and size
) in your index:
- Retrieve a list of facet values (for example,
blue
,red
,small
, andlarge
) for records matching the current query - To retrieve all facets, use the wildcard character (
*
) - For each facet value, the response also contains the number of matching records for that facet value
Retrieve all facets from your index with the wildcard *
character. For example, facets: ['*']
.
Usage notes
- Faceting itself doesn’t filter the search results: you filter results at search time with the
filters
parameter. - By default, or if you set
facets
to an empty list (facets: []
), no facets are retrieved. - Add all attributes you want to use for faceting with
attributesForFaceting
.
There’s no limit to the number of attributes in the list, but having many attributes slows down calls to getSettings
. This can make the Algolia dashboard slower and less responsive.
Approximate facet counts and facet values
- By default, facet values are sorted by frequency: change this with the
sortFacetValuesBy
parameter. - Facet values are truncated to 1,000 characters.
-
The response can have two additional parameters (in the
exhaustive
object):facetsCount
: the fieldfacetsCount
istrue
if the facet count is exact. For queries with many hits, the facet count may be approximate.facetValues
: by default, up to 100 facet values are retrieved per facet. Theexhaustive
object containsfacetValues: false
if not all facet values are retrieved. Increase this limit withmaxValuesPerFacet
(to a maximum of 1,000).
Examples
Retrieve only some facets
The following example searches for “query” and retrieves the facets and facet values for the author
and category
attributes. Both must have previously been declared as attributes for faceting with the API or dashboard.
1
2
3
$results = $index->search('query', [
'facets' => ['category', 'author']
]);
The example response shows three matches for “Jhon” in the author
facet and one in the category
facet for “Classical”.
The facet count is exact.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"facets": {
"author": {
"Jhon": 3,
},
"category": {
"Classical": 1,
}
},
"exhaustiveFacetsCount": true,
"exhaustive": {
"facetsCount": true
},
"hits": {...},
}
Retrieve all facets
1
2
3
$results = $index->search('query', [
'facets' => ['*']
]);