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

Aug. 16, 2022

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
])

index.search_for_facet_values(
  String facetName,
  String facetQuery
)

index.search_for_facet_values(
  String facetName,
  String facetQuery,
  Hash opts = {
      # any searchParameters
      # any requestOptions
  }
)

index.searchForFacetValues(string facetName, string facetQuery)

index.searchForFacetValues(string facetName, string facetQuery, {
  // any searchParameters
  // any requestOptions
})

index.search_for_facet_values(str facetName, str facetQuery)
index.search_for_facet_values(str facetName, str facetQuery, {
  # any searchParameters
  # any requestOptions
})

index.searchForFacetValues(
  of facetName: Attribute,
  matching facetQuery: String ,
  applicableFor searchQuery: Query? = nil,
  requestOptions: RequestOptions? = nil,
  completion: Result<FacetSearchResponse> -> Void
)
// searchParameters can be added in the Query object

suspend fun Index.searchForFacets(
    attribute: Attribute,
    facetQuery: String? = null,
    query: Query? = Query(),
    requestOptions: RequestOptions? = null
): ResponseSearchForFacetValues

index.SearchForFacetValues( new SearchForFacetRequest {
  FacetName = String,
  FacetQuery = String,

  // All the following parameters are optional
  SearchParameters = Query,
  RequestOptions = RequestOptions
})

index.searchForFacetValues(
  new SearchForFacetRequest()
  .setFacetName(String facetName)
  .setFacetQuery(String facetQuery)
)

index.searchForFacetValues(
  new SearchForFacetRequest()
  .setFacetName(String facetName)
  .setFacetQuery(String facetQuery)
  .setSearchParameters(Query new Query())
)

index.searchForFacetValues(
  new SearchForFacetRequest()
  .setFacetName(String facetName)
  .setFacetQuery(String facetQuery)
  .setSearchParameters(Query new Query()),
  RequestOptions requestOptions
)

// any searchParameters can be set to the Query object

index.SearchForFacetValues(
  string facetName,
  string facetQuery,
)
index.SearchForFacetValues(
  string facetName,
  string facetQuery,
  searchParameters
)
index.SearchForFacetValues(
  string facetName,
  string facetQuery,
  searchParameters,
  requestOptions,
)

search into "myIndex" facet facetName values facetQuery
search into "myIndex" facet facetName values facetQuery query Query()
search into "myIndex" facet facetName values facetQuery
  query Query() options requestOptions

// searchParameters can be added in the Query object

See code examples

About this method

We released a new version of the PHP API client in public beta. Read the beta documentation for more information.

We released a new version of the JavaScript API client in public beta. Read the beta documentation for more information.

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

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

You’re currently reading the Ruby API client v2 documentation. Check the 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.

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.

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

Read the Algolia CLI documentation for more information.

Copy

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

1
2
3
4
// Search the "category" facet for values matching "phone" in records
index.searchForFacetValues('category', 'phone').then(({ facetHits }) => {
  console.log(facetHits);
});

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

1
2
3
4
5
6
7
8
9
// 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

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'
]);

1
2
3
4
5
6
7
# Search the "category" facet for values matching "phone" in records
# having "Apple" in their "brand" facet.
index.search_for_facet_values('category', 'phone', {
  params: {
    filters: 'brand:Apple'
  }
})

1
2
3
4
5
6
7
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
index.searchForFacetValues('category', 'phone', {
  filters: 'brand:apple'
}).then(({ facetHits }) => {
  console.log(facetHits);
});

1
2
3
4
5
6
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)

1
2
3
4
5
6
7
8
9
10
11
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
var query = Query()
query.filters = "brand:Apple"
index.searchForFacetValues(of: "category",
                           matching: "phone",
                           applicableFor: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
// 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
});

1
2
3
4
5
6
7
8
9
10
11
12
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);

1
2
3
// 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

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

1
2
3
4
5
6
# Search the "category" facet for values matching "phone" in records
index.search_for_facet_values('category', 'phone', {
  headers: {
    'X-Algolia-User-ID': 'user123'
  }
})

1
2
3
4
5
6
7
8
9
10
11
12
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
// only for the user123

index.searchForFacetValues('category', 'phone', {
  filters: 'brand:apple',
  headers: {
    'X-Algolia-User-ID': 'user123'
  }
}).then(({ facetHits }) => {
  console.log(facetHits);
});

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// Search the "category" facet for values matching "phone" in records
// having "Apple" in their "brand" facet.
var query = Query()
query.filters = "brand:Apple"

var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-UserToken"] = "user123"

index.searchForFacetValues(of: "category",
                           matching: "phone",
                           applicableFor: query,
                           requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
val attribute = Attribute("category")
val requestOptions = requestOptions {
    header("X-Algolia-User-ID", "user123")
}

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
// 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);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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")
);

1
2
3
4
5
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")))
}

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

This section shows the JSON response returned by the API. Since each language encapsulates this response inside objects specific to that language and/or implementation, the actual type in your language might differ from what’s written here. You can view the response in the logs (using the getLogs method).

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,
    "exhaustive": {
      "facetsCount": 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?

Search for Facet Values

About this method

Examples