Search for Facet Values | Ruby API Client V1 (Deprecated)
search
ACL
index.search_for_facet_values( String facetName, String facetQuery ) index.search_for_facet_values( String facetName, String facetQuery, Hash searchParameters ) index.search_for_facet_values( String facetName, String facetQuery, Hash searchParameters, Hash requestOptions )
About this method
Search for a set of values within a given facet attribute. Can be combined with a query.
This method enables you to search through the values of a facet attribute, selecting only a subset of those values that meet a given criteria.
Note: For a facet attribute to be searchable, it must have been declared in the
attributesForFaceting
index setting with the searchable()
modifier.
Facet-searching only affects facet values. It does not impact the underlying index search.
The results are sorted by decreasing count.
This can be adjusted via sortFacetValuesBy
.
By default, maximum 10 results are returned.
This can be adjusted via maxFacetHits
.
This method is often used in combination with a user’s current search (using the search parameters). By combining facet and query searches, you control the number of facet values a user sees.
When you have 1000s of different values for a given facet attribute, it is impossible to display them all on the user’s interface. With Search for facet values, you allow your users to search within a specific faceted attribute (for example, brands, authors, or categories) without needing to create a separate index. This means that you can still display the most common occurrences for each facet at the top, but also enable the end user to search for a specific value to use for filtering.
By default, facet values are returned sorted by their count.
Due to technical limitations, search for facet value does not work if you have more than 65 searchable attributes defined. A search for facet values will result in an empty list of facet values.
Examples
Search for facet values
1
2
# Search the values of the "category" facet matching "phone".
$index->searchForFacetValues("category", "phone");
Search for facet values with an additional searchParameters:
1
2
3
4
5
// Search the "category" facet for values matching "phone"
// in records having "Apple" in their "brand" facet.
$index->searchForFacetValues("category", "phone", [
'filters' => 'brand:Apple'
]);
Search for facet values and send extra HTTP headers
1
2
3
4
# Search the "category" facet for values matching "phone" in records
$index->searchForFacetValues("category", "phone", [
'X-Algolia-User-ID' => 'user123'
]);
Parameters
facetName
|
type: string
Required
Attribute name. Note that for this to work, attribute must be declared in the
|
facetQuery
|
type: string
Required
The search query used to search the facet attribute. Follows the same rules for an index query: a single character, a partial word, a word, or a phrase. |
searchParameters
|
type: key/value mapping
default: No search parameters
Optional
The mapping of search parameters, to be used to search the underlying index. If set, the method will return facet values that both:
Using this parameter, therefore, aligns the count of each facet value
with the current search results. Without it, the count will be based on the whole index.
Note that the Settings that affect the returned facet values (maxFacetHits and sortFacetValuesBy) can be set as well. |
requestOptions
|
type: key/value mapping
default: No request options
Optional
A mapping of request options to send along with the query. |
Response
In this section we document the JSON response returned by the API. Each language will encapsulate this response inside objects specific to the language and/or the implementation. So the actual type in your language might differ from what is documented.
JSON format
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"facetHits": [
{
"value": "Mobile phones",
"highlighted": "Mobile <em>phone</em>s",
"count": 507
},
{
"value": "Phone cases",
"highlighted": "<em>Phone</em> cases",
"count": 63
}
],
"exhaustiveFacetsCount": true,
"processingTimeMS": 1
}
facetHits
|
list of facetHit
|
exhaustiveFacetsCount
|
boolean
Whether the count returned for each facetHit is exhaustive. |
processingTimeMS
|
integer
Processing time. |
facetHit
value
|
string
Facet value. |
highlighted
|
string
Highlighted value. |
count
|
integer
Number of times the value is present in the dataset. |