This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a list of distinct values for a given field for all items that match the query, without duplicates.
As with the Query Data Items endpoint, this endpoint retrieves items based on the filtering, sorting, and paging preferences provided.
However, the Query Distinct Values endpoint doesn't return the full items that match the query. Rather, for items that match the query, it returns all unique values in the field specified in fieldName
. If more than one item has the same value in that field, that value appears only once.
See API Query Language for more information about handling data queries.
ID of the collection to query.
Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.
Item field name for which to return all distinct values.
Order to by which to sort the results. Valid values are ASC
and DESC
.
Whether to retrieve data from the primary database instance. This decreases performance but ensures data retrieved is up-to-date even immediately after an update. Applicable if the external database is eventually consistent.
When true
, the query response must include the total number of items that match the query.
List of distinct values contained in the field specified in fieldName
. Values can be of any JSON type.
If the field is an array, values must be unwound, independent values. For example, if the field name contains ["a", "b", "c"]
, the result must contain "a"
, "b"
and "c"
as separate values.
Paging information.
curl POST https://external-db.example.com/v3/items/query-distinct-values \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"fieldName": "country",
"order": "ASC",
"paging": {
"limit": 50,
"offset": 0
},
"consistentRead": false,
"returnTotalCount": false
}'
{
"distinctValues": ["US", "CA"],
"pagingMetadata": {}
}