MImixpeek
Collection Documents

Return distinct values for a single field.

Changed on

Return the set of unique values for one document field across a collection, together with a per-value document count sorted desc. Thin wrapper over /aggregate for the common SELECT DISTINCT <field> case — use this when a UI needs a facet list (e.g. brand_slug) without loading every document. Null/missing values are excluded. A value comes back as a JSON number or boolean when the namespace declares a payload index of type integer, float or bool on the field. Any other field, including an undeclared numeric one, facets as strings, so check the namespace's payload_indexes to know which you will get. When a storage shard times out or returns only part of its documents, the list can be short: query_info.truncated is then true and query_info.warning says what to do.

post/v1/collections/{collection_identifier}/documents/distinct

Request

Path parameters

collection_identifierstring required

The unique identifier of the collection.

Request body

fieldstring required

Document field whose distinct values should be returned. Dotted paths are supported (e.g. metadata.brand_slug). Null/missing values are excluded.

filtersobject nullable

Optional pre-aggregation filters, same syntax as the standard aggregation endpoint. Applied before distinct values are computed.

limitinteger nullable

Maximum number of distinct values to return (sorted by count desc). Defaults to no limit on the server side; for high-cardinality fields always set a limit to keep the response bounded.

Example request

{
  "field": "brand_slug"
}

Response

Successful Response

fieldstring required

The field that was queried.

total_distinctinteger required

Number of distinct values in the response (== len(values)). When limit is set this can be less than the true cardinality.

query_infoobject

Empty when the answer is complete. When a storage shard timed out or returned only part of its documents, this holds truncated: true, a reason, any shard_warnings, and a warning; the list may then be missing values and every count is a lower bound. Retrying usually gives the full answer.

Changes

  • d4b5fad18960Revision changes
    • info

      added the optional property to the response with the status

  • 61a175e8eb9aRevision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status