facets

About this parameter

Retrieve facets and their facet values.

For each of the facets (for example, color and size) you created, the response will retrieve a list of facet values (for example, blue, red, small, large) for objects matching the current user query. Each value returns its associated count (number of matched objects containing that value).

The maximum number of facet values returned depends on the maxValuesPerFacet setting: 100 (default) to 1,000. All facet values are truncated to their first 1,000 characters.

By default, the returned values are sorted by frequency, but this can be changed to alphabetical with sortFacetValuesBy.

Usage notes

• Facets must have been declared beforehand in the attributesForFaceting index setting.
• Faceting doesn’t filter your results. If you want to filter results, use filters.
• Default or empty lists: if not specified or empty, no facets are retrieved. The value ['*'] retrieves all facets and forces the engine to avoid aggressive optimizations. Retrieving all facets can be useful when your query includes filters.
• Approximating facet counts: if the number of hits is high, facet counts may be approximate. The response field exhaustiveFacetsCount is true when the count is exact.

Use facets for attributes that have values in common with a significant number of records, for example, brand, color, size. Don’t use facets for attributes that probably have unique values, such as title and description. Using facets for attributes that are unique or uncommon may degrade search performance and relevance. See the facets usage notes for more information.

Examples

Only retrieve faceting data for some attributes

For this example, attributesForFaceting are set to ["category", "author", "nb_views", "nb_downloads"] but, for the current search, you want to retrieve facet values only for category and author.

1
2
3
$results = $index->search('query', [
  'facets' => ['category', 'author']
]);

1
2
3
results = index.search('query', {
  facets: ['category', 'author']
})

1
2
3
4
5
index.search('query', {
  facets: ['category', 'author']
}).then(({ hits }) => {
  console.log(hits);
});

1
2
3
results = index.search('query', {
    'facets': ['category', 'author']
})

1
2
3
4
5
6
7
8
let query = Query("query")
  .set(\.facets, to: ["category", "author"])

index.search(query: query) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
index.Search<Book>(new Query("query")
{
    Facets = new List<string>{ "category", "author" }
});

1
2
3
4
5
6
index.search(
  new Query("query").setFacets(Arrays.asList(
    "category",
    "author"
  ))
);

1
2
3
4
res, err := index.Search(
  "query",
  opt.Facets("category", "author"),
)

1
2
3
4
5
6
7
8
9
client.execute {
  search into "myIndex" query Query(
    query = Some("query"),
    facets = Some(Seq(
      "category",
      "author"
    ))
  )
}

1
2
3
4
5
6
7
8
val query = query("query") {
    facets {
        +"category"
        +"author"
    }
}

index.search(query)

When searching with the facets parameter, the method returns facets with the following “shape”:

1
2
3
4
5
6
7
8
9
10
{
  "facets": {
    "author": {
      "Jhon": 3,
    },
    "category": {
      "Classical": 1,
    }
  }
}