POST

Query Data Items


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 items based on the provided filtering, sorting, and paging preferences.

See API Query Language for more information about handling data queries.

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

ID of the collection to query.


queryQueryRequired

Query preferences. See API Query Language for information about handling data queries.


includeReferencedItemsArray <ReferencedItemToInclude>

Fields for which to include the full referenced items in the query's results, rather than just their IDs. Returned items are sorted in ascending order by the creation date of the reference. If the field being querried is a multi-reference field and the array is empty, the response does not return any items.


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.

Response Object
itemsArray <object>

Retrieved items.


pagingMetadataPagingMetadata

Pagination information.

Request
cURL
curl POST https://external-db.example.com/v3/items/query \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: <AUTH>' \ --d '{ "collectionId": "cities", "query": { "filter": { }, "sort": [], "paging": { "limit": 50, "offset": 0 }, "fields": [] }, "includeReferencedItems": [], "consistentRead": false, "returnTotalCount": true }'
Response
JSON
{ "items": [ { "name": "New York", "_id": "c285e77c-a86b-4361-a55f-c6b934d70187", "population": 8300000.0, "country": "US", "isCapital": false } ], "pagingMetadata": { "total": 1 } }
Errors
ItemAlreadyExistsobjectstatus code: 409
ItemNotFoundobjectstatus code: 404
CollectionAlreadyExistsobjectstatus code: 409
CollectionNotFoundobjectstatus code: 404
ReferenceAlreadyExistsobjectstatus code: 409
ReferenceNotFoundobjectstatus code: 404
ValidationErrorobjectstatus code: 400
CollectionChangeNotSupportedobjectstatus code: 400
BadRequestobjectstatus code: 400
Did this help?