Skip to main content
Facets return document counts for values in keyword fields, including arrays and nested fields addressed by dotted paths. Use them to show filter choices such as category or brand counts alongside search results.

​
Request facets

Add facets to the query request. Each key is an indexed keyword field name. Set its size to the maximum number of buckets to return (default 10, range 1–100).
A response includes a facets object alongside the usual document results:
This facet-only request uses "size": 0 to return no documents. Set size to 1–100 to include document results. total still counts returned documents, so it is zero in that case. Omit query to count all documents in the selected read scope.

​
Counting rules

  • Counts cover all documents matching the query, independent of the number of returned documents or buckets. All query and partition filters apply, including filters on the facet’s own field.
  • A document with ["sale", "sale", "new"] contributes once to sale and once to new. Bucket counts can therefore sum to more than the number of matching documents.
  • Missing fields, null fields, empty arrays, and values excluded from indexing produce no bucket. Empty strings are indexed values. Existing keyword length limits still apply.
  • Buckets are ordered by count descending, then value ascending in Unicode code point order. Values are not analyzed or folded by locale or case.
  • Every requested field is present in the response; a field without matching indexed values has an empty buckets array. Without a facet request, the response omits facets.
  • Counts remain inline when document results are downloaded through docsUrl.

​
Supported queries and read scope

Use facets with queryString, bool combinations of supported queries, or no query. Vector, sparse vector, and hybrid queries are rejected when facets are requested. Numeric or date range facets, nested bucket aggregations, and excluding a facet’s own filter are not supported. Adding native reranking preserves these restrictions. For supported scoring lexical queries with positive size, counts still cover all matches and are unchanged by reranking or fallback; they are not counts of the reranked candidate pool. Facet-only size: 0 requests cannot rerank. The existing partitionFilter, ref, and consistentRead rules apply. Counts use the selected Branch, Tag, or Alias and the same pending-write visibility as document results. consistentRead: true requires a direct Branch read (or the default main Branch when ref is omitted); Tags and Aliases reject it. Facets do not introduce a stronger global snapshot guarantee.

​
Limits and cost

At most 5 keyword fields can be requested. Counts are exact across the selected partitions: all buckets are combined before selecting the returned top buckets. If the population exceeds 10,000 distinct (field, value) buckets or 262,144 UTF-8 bytes of distinct values across requested fields, the request fails with HTTP 400 instead of returning partial counts. The same value in two fields counts twice. Narrow the query or request fewer fields; reducing a facet’s return size does not reduce the number of values that must be counted. Separate memory admission limits protect aggregation work and distributed response merging. A request whose estimated memory exceeds its budget returns HTTP 400; request fewer fields or select fewer partitions. This estimate also depends on indexed values outside the matching population, so a narrower query alone may not resolve it. If concurrent facet requests have temporarily exhausted a budget, the request returns HTTP 429; retry with backoff. No partial counts are returned on either failure. Facets visit all matching documents, so broad queries may cost more than retrieving a small number of top documents. Queries without facets do not perform this additional aggregation.

​
Index requirements

Configure each facet field as a keyword index. Keyword fields accept single values or arrays. The top-level document id is always a single string; arrays are not allowed for id.

​
Client compatibility

The recommended SDK releases accept facets in query requests and preserve facet results when documents are downloaded through docsUrl: The CLI accepts facets in query JSON files, and the MCP server accepts them through lambdadb_query_collection.