facets

About this parameter

Retrieve facets, their facet values, and the number of matching facet values.

For each facet you added to your index, for example, color and size, retrieve a list of facet values, for example, blue, red, small, or large for records matching the current search query. For each facet value, the response also contains the number of matching records with that facet value.

Usage notes

• You need to add all attributes you want to use for faceting to the attributesForFaceting index setting.

• Faceting doesn’t filter the search results. It’s a setting for the search engine to allow you to filter the results at search time with the filters parameter.

• By default, no facets are retrieved. The same is true if you set facets to an empty list: facets: [].

• You can retrieve all facets with the wildcard * character: facets: ['*'].

• By default, facet values are sorted by frequency. You can change this with the sortFacetValuesBy parameter.

Approximate facet counts and facet values

The response can have two additional parameters in the exhaustive object:

• facetsCount: if the number of hits for a query is high, the facet count may be approximate. The field facetsCount is true if the facet count is exact (exhaustive).

• facetValues: by default, up to 100 facet values are retrieved per facet. The exhaustive object contains facetValues: false if not all facet values are retrieved.

  You can increase this number by increasing the maxValuesPerFacet setting to a maximum of 1,000.

• Facet values are truncated to 1,000 characters.

Examples

Retrieve only some facets

The following example searches for “query” and retrieves the facets and facet values for the “author” and “category” attributes. Both attributes must be added to the attributesForFaceting index setting before searching.

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((results) => {
  console.log(results);
});

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
5
6
7
8
val query = query("query") {
    facets {
        +"category"
        +"author"
    }
}

index.search(query)

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"
    ))
  )
}

The example response shows three matches for “Jhon” in the “author” facet and one match in the “category” facet for “Classical”.

The facet count is exact (exhaustive).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "facets": {
    "author": {
      "Jhon": 3,
    },
    "category": {
      "Classical": 1,
    }
  },
  "exhaustiveFacetsCount": true,
  "exhaustive": {
    "facetsCount": true
  },
  "hits": {...},
}