facets

About this parameter

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

For each specified facet (for example, color, and size) in your index:

• Retrieve a list of facet values (for example, blue, red, small, and large) for records matching the current query
• To retrieve all facets, use the wildcard character (*)
• For each facet value, the response also contains the number of matching records for that facet value

Retrieve all facets from your index with the wildcard * character. For example, facets: ['*'].

Usage notes

• Faceting itself doesn’t filter the search results: you filter results at search time with the filters parameter.
• By default, or if you set facets to an empty list (facets: []), no facets are retrieved.
• Add all attributes you want to use for faceting with attributesForFaceting.

While there’s no limit to the number of attributes, adding too many attributes can slow down calls to getSettings and reduce the responsiveness of Algolia’s dashboard.

Approximate facet counts and facet values

• By default, facet values are sorted by frequency: change this with the sortFacetValuesBy parameter.
• Facet values are truncated to 1,000 characters.

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

  • facetsCount: the field facetsCount is true if the facet count is exact. For queries with many hits, the facet count may be approximate.
  • 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. Increase this limit with maxValuesPerFacet (to a maximum of 1,000).

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 must have previously been declared as attributes for faceting with the API or dashboard.

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 in the category facet for “Classical”.

The facet count is exact.

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": {...},
}

Retrieve all facets

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

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

1
2
3
index.search('query', {
  facets: ['*']
});

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

1
2
3
4
5
6
let query = Query(query: "query")
query.facets = ["*"]

index.search(query, completionHandler: { (res, error) in
  print(res)
})

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

index.search(query)

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

1
2
3
4
5
index.search(
  new Query("query").setFacets(Arrays.asList(
    "*"
  ))
);

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

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