Api clients / JavaScript / V3 / Methods

Jan. 22, 2021

Search for Facet Values | JavaScript API Client V3 (Deprecated)

This version of the JavaScript API client has been deprecated in favor of the latest version of the JavaScript API client.

Required API Key: any key with the search ACL

Method signature

index.searchForFacetValues(
  {
    facetName: string,
    facetQuery: string,
    object ...searchParameters
  },
  callback
)

See code examples

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

Copy

Copy
# Search the values of the "category" facet matching "phone".
$index->searchForFacetValues("category", "phone");

Copy
// Search the "category" facet for values matching "phone" in records
index.searchForFacetValues({
  facetName: 'category',
  facetQuery: 'phone'
}, (err, { facetHits } = {}) => {
  if (err) throw err;

  console.log(facetHits);
});

Copy
# Search the values of the "category" facet matching "phone".
index.searchForFacetValues("category", "phone", new CompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
        // [...]
    }
});

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

Copy
// Search the values of the "category" facet matching "phone".

// Sync version
SearchForFacetResponse result = index.searchForFacetValues(
    new SearchForFacetRequest().setFacetName("phone").setFacetQuery("category"));

// Async version
CompletableFuture<SearchForFacetResponse> result = index.searchForFacetValuesAsync(
    new SearchForFacetRequest().setFacetName("phone").setFacetQuery("category"));

Copy

Copy
// Search the "category" facet for values matching "phone"
// in records having "Apple" in their "brand" facet.
$index->searchForFacetValues("category", "phone", [
  'filters' => 'brand:Apple'
]);

Copy
search_parameters = {
  filters: 'brand:Apple'
}

# Search the "category" facet for values matching "phone" in records
# having "Apple" in their "brand" facet.
index.search_for_facet_values('category', 'phone', search_parameters)

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
index.searchForFacetValues({
  facetName: 'category',
  facetQuery: 'phone',
  filters: 'brand:apple'
}, (err, { facetHits } = {}) => {
  if (err) throw err;

  console.log(facetHits);
});

Copy
query = {
    'filters': 'brand:Apple'
}
# Search the values of the "category" facet matching "phone" for the records
# having "Apple" in their "brand" facet.
index.search_for_facet_values('category', 'phone', query)

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
let query = Query()
query.filters = "brand:Apple"
index.searchForFacetValues(
  of: "category",
  matching: "phone",
  query: query
) { (content, error) in
    // Handle results
}

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
Query query = new Query().setFilters("brand:Apple");
index.searchForFacetValues("category", "phone", query, new CompletionHandler() {
  @Override
  public void requestCompleted(JSONObject content, AlgoliaException error) {
    // [...]
  }
});

Copy
// 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
});

Copy
Query query = new Query().setFilters("brand:Apple");

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

//Sync version
SearchFacetResult result =
  index.searchForFacetValues("category", "phone", query);

//Async version
CompletableFuture<SearchFacetResult> result =
  index.searchForFacetValues("category", "phone", query);

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
index.SearchForFacetValues("category", "phone", opt.Filters("brand:Apple"))

Copy

Copy
# Search the "category" facet for values matching "phone" in records
$index->searchForFacetValues("category", "phone", [
  'X-Algolia-User-ID' => 'user123'
]);

Copy
search_parameters = {}

extra_headers = {
  'X-Algolia-User-ID': 'user123'
}

# Search the "category" facet for values matching "phone" in records
index.search_for_facet_values('category', 'phone', search_parameters, extra_headers)

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

client.setExtraHeader('X-Algolia-User-ID', 'user123');

index.searchForFacetValues({
  facetName: 'category',
  facetQuery: 'phone',
  filters: 'brand:apple'
}, (err, { facetHits } = {}) => {
  if (err) throw err;

  console.log(facetHits);
});

Copy
# Search the values of the 'category' facet matching 'phone' for the records
index.search_for_facet_values('category', 'phone', {
    'X-Algolia-User-ID': 'user123'
})

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
let query = Query()
query.filters = "brand:Apple"
let requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-User-ID"] = "user123"
index.searchForFacetValues(
  of: "category",
  matching: "phone",
  query: query,
  requestOptions: requestOptions
) { (content, error) in
    // Handle results
}

Copy
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
Query query = new Query().setFilters("brand:Apple");
index.searchForFacetValues(
  "category",
  "phone",
  query,
  new RequestOptions()
    .setHeader("X-Algolia-User-ID", "94.228.178.246"),
  new AssertCompletionHandler() {
    @Override
    public void requestCompleted(JSONObject content, AlgoliaException error) {
      // [...]
    }
  }
);

Copy
// 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);

Copy
Query query = new Query().setFilters("brand:Apple");

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

//Sync version
SearchFacetResult result = index.searchForFacetValues(
  "category",
  "phone",
  query,
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

//Async version
CompletableFuture<SearchFacetResult> result = index.searchForFacetValues(
  "category",
  "phone",
  query,
  new RequestOptions().addExtraHeader("X-Algolia-User-ID", "user123")
);

Copy
client.execute {
  search into "myIndex" facet "category" values "phone" query Query(
      filters = Some(Seq("brand:Apple"))
  ) options RequestOptions(extraHeaders = Some(Map("X-Algolia-User-ID" => "user123")))
}

Copy
val attribute = Attribute("category")
val requestOptions = requestOptions {
    header("X-Algolia-User-ID", "user123")
}

index.searchForFacets(attribute, "phone", Query(filters = "brand:Apple"), requestOptions)

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 [`requestOptions`](/doc/api-client/getting-started/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

Copy

          {
    "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.

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Search for Facet Values | JavaScript API Client V3 (Deprecated)

About this method

Examples