POST

Query Distinct Values


Developer Preview

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.

Endpoint
POST
{DEPLOYMENT-URI}/v3/items/query-distinct-values
Body Params
collectionIdstringRequired

ID of the collection to query.


filterstruct

Filter to apply to the collection's data before aggregation. See API Query Language for more information about handling data queries.


fieldNamestringRequired

Item field name for which to return all distinct values.


orderstring

Order to by which to sort the results. Valid values are ASC and DESC.


consistentReadbooleanRequired

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.


returnTotalCountbooleanRequired

When true, the query response must include the total number of items that match the query.


ONE OF:

pagingPaging

cursorPagingCursorPaging
Response Object
distinctValuesArray <Value>

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.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
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 }'
Response
JSON
{ "distinctValues": ["US", "CA"], "pagingMetadata": {} }
Did this help?