Skip to main content
This page documents an earlier version of the API client. For the latest version, see Search for facet values.
Required ACL: search 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 with 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. 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 users to search for a specific value for filtering.
Search for facet values doesn’t work if you have more than 65 searchable facets and searchable attributes combined: any such search results in an empty list of facet values.

​
Examples

​
Search for facet values

// Search the values of the "category" facet matching "phone".
index.SearchForFacetValue(new SearchForFacetRequest
{
    FacetName = "phone",
    FacetQuery = "category"
});

​
Search for facet values with additional search parameters

// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
var queryParams = new Query
{
  Filters = "brand:Apple"
};

index.SearchForFacetValue(new SearchForFacetRequest
{
    FacetName = "phone",
    FacetQuery = "category",
    SearchParameters = queryParams
});

​
Search for facet values and send extra HTTP headers

// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.

var queryParams = new Query
{
  Filters = "brand:Apple"
};

var requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-User-ID", "user123" } }
};

index.SearchForFacetValue(new SearchForFacetRequest
{
    FacetName = "phone",
    FacetQuery = "category",
    SearchParameters = queryParams
}, requestOptions);

​
Parameters

​
facetName
string
required
Attribute name.For this to work, you must declare the attribute with attributesForFaceting using the searchable() modifier.
​
facetQuery
string
required
The search query used to search the facet attribute.
Facet queries only match prefixes, typos, and exact.
​
requestOptions
object
A mapping of request options with this method.
​
searchParameters
object
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.

​
Response

​
count
integer
The number of times the value is present in the dataset.
​
exhaustiveFacetsCount
boolean
Whether the count returned for each facetHit is exhaustive.
​
facetHits
object[]
​
highlighted
string
Highlighted value.
​
processingTimeMS
integer
Processing time.
​
value
string
Facet value.

​
Response as JSON

This section shows the JSON response returned by the API. Each API client wraps this response in language-specific objects, so the structure may vary. To view the response, use the getLogs method. Don’t rely on the order of properties—JSON objects don’t preserve key order.
JSON
{
    "facetHits": [
        {
            "value": "Mobile phones",
            "highlighted": "Mobile <em>phone</em>s",
            "count": 507
        },
        {
            "value": "Phone cases",
            "highlighted": "<em>Phone</em> cases",
            "count": 63
        }
    ],
    "exhaustiveFacetsCount": true,
    "exhaustive": {
      "facetsCount": true
    },
    "processingTimeMS": 1
}
⌘I