API Reference / API Methods / Search / Search for facet values

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

You are currently reading the JavaScript API client v4 documentation. Check our migration guide to learn how to upgrade from v3 to v4. You can still access the v3 documentation.

You are currently reading the Ruby API client v2 documentation. Check our migration guide to learn how to upgrade from v1 to v2. You can still access the v1 documentation.

Search for a set of values within a given facet attribute. Can be combined with a query.

This method lets you search through the values of a facet attribute and select a subset of those values that meet a given criteria.

Facet-searching only affects facet values, not the index search.

For a facet attribute to be searchable, it must have been declared in the attributesForFaceting index setting using the searchable() modifier.

By default:

  • Results are sorted by decreasing count. You can adjust with sortFacetValuesBy.
  • A maximum of 10 results are returned. You can adjust with maxFacetHits.

This method is often used in combination with a user’s current search with search parameters. By combining facet and query searches, you control the number of facet values a user sees.

Api method search for facet values

When you have thousands of different values for a given facet attribute, it’s impossible to display them all on a user 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. You can still display the most common occurrences for each facet at the top, but also enable the user to search for a specific value for filtering.

By default, facet values are sorted by their count.

Due to technical limitations, search for facet values doesn’t work if you have more than 65 searchable attributes defined: any such search results 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 additional search parameters

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.

For this to work, you must declare the attribute with attributesForFaceting using the searchable() modifier.

facetQuery
type: string
Required

The search query used to search the facet attribute.

Facet queries only match prefixes, typos, and exact.

searchParameters
type: key-value mapping
default: No search parameters
Optional

The mapping of search parameters used to search the underlying index.

If set, the method will return facet values that both:

  • Match the facet query
  • Are contained in the records matching the regular search query

Using this parameter aligns the count of each facet value to current search results. Without it, the count is based on the whole index.

page, hitsPerPage, offset, and length parameters don’t affect the count, as the count value represents the whole set of results, not just the current page. maxFacetHits and sortFacetValuesBy do affect the returned facet values.

requestOptions
type: key/value mapping
default: No request options
Optional

A mapping of requestOptions to send along with the query. In addition to sending extra HTTP headers or setting timeouts, you can use requestOptions to specify search parameters with this method.

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

The number of times the value is present in the dataset.

Did you find this page helpful?