Facets

Count facets

Exact document counts for projected metadata fields across authorized Corpora. Uses content:read and validates every requested Corpus before resolving mappings, including Corpora excluded for missing facet or predicate fields. Exclusions use the same excluded_corpora shape and rules as search and metadata-filtered listing. All fields are aggregated in one read snapshot from current baseline-ready, non-quarantined Versions; withdrawn Records and Tombstones are excluded immediately. Each distinct array value counts a document once. Missing field values contribute no bucket. Common metadata.* fields and custom fields declared with the filter role are supported. Incompatible types across Corpora return 422 invalid_query. Existing projections without metadata require rebuilding (422 metadata_filter_unavailable). Each field returns at most its limit, selected by descending count then JSON value text in byte order for ties. UTC date buckets are then returned chronologically; empty date buckets are omitted. Histograms require day, month or year on datetime fields; interval on another type is invalid_query. Counts are independent of search and listing reads and can change with ingestion. No text query or ranking is applied. Each API process admits at most 8 active facet requests; excess work returns retryable 503 content_unavailable with Retry-After: 1. Requests have a 25-second execution deadline. With accuracy fast, counts may instead come from each Corpus's stored snapshot, exact as of the response's as_of and refreshed in the background while it is read, when the request has no predicate or only whole UTC days of the single date field it counts; otherwise from an exact count that ends within about a second, or else estimates scaled from a uniform sample of the Corpora's Records, marked approximate with their sample_fraction. Exact responses carry neither as_of nor approximate.

post/v0/facets

Request

  • Base URL
    https://docs.quivr.thevibecompany.co (the document declares no server; this is the origin it was published from)
  • Auth
    HTTP bearer

Request body

corpus_idsstring[] required
accepted_afterstring date-time

Inclusive current-Version acceptance-time lower bound, as in listing.

accepted_beforestring date-time

Exclusive current-Version acceptance-time upper bound, as in listing.

accuracy'exact' | 'fast'

Absent or exact counts every current document now. fast is best effort: Quivr may answer sooner, usually within a few seconds, from stored snapshots (as_of), a uniform sample (approximate), or an exact count that ended within about a second (neither marker). The 25-second request deadline still applies.

Response

Bounded document counts and excluded Corpus explanations.

as_ofstring date-time

Fast requests only. Counts come from stored per-Corpus snapshots, each exact when it was taken; this is the oldest snapshot's time. Changes since a Corpus's snapshot are missing from its counts, and newer snapshots of other Corpora include their later changes.

approximateboolean

Fast requests only; present and true when counts are estimates scaled from a uniform sample of Records.

sample_fractionnumber double

Share of the Corpora's Records counted when approximate.

Changes

No recorded changes to this operation across all 1 revision of this API.