API Reference / API Methods / Search / Search for facet values
Feb. 26, 2019

Search for facet values

Required API Key: any key with the search ACL
Method signature
$index->searchForFacetValues(string facetName, string facetQuery)
$index->searchForFacetValues(string facetName, string facetQuery, [
  // any searchParameters
  // any 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 is often used in combination with a user’s current search (using the searchParameters). By combining facet and query searches, you can control the number of facet values a user sees, thereby focusing the user’s attention on what you consider to be the most relevant facet values.

Searching for facet values is a powerful tool that allows you to use as many facet values as you need, without overloading the user with too many values on the screen. Being able to search for values, users can more easily drill down into the results. See more here.

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 attributesForFaceting index setting with the searchable() modifier.

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:

  • match the facet query (thanks to the first parameter, facetQuery)
  • and are contained in the records matching the regular search query (thanks to this parameter).

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 page, hitsPerPage, offset, and length parameters do not impact the count, as the count value represents the whole set of results not just the current page.

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
boolean

Highlighted value.

count
integer

Number of times the value is present in the dataset.

Did you find this page helpful?