This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves the items referenced in the specified field of a referring item. Reference fields refer to items that exist in different collections. Implement this endpoint so callers can retrieve the full details of the referenced items.
This service plugin supports item multi-references, which means that data collections can have many-to-many relationships with other collections. For example, consider a scenario where a Movies collection includes a multi-reference Actors field, which might refer to several Actor items in an Actors collection. Users can therefore query the Movies collection to retrieve the Actor items referenced in each Movie item.
Notes:
ID of the collection to query.
IDs of the referring items. If the array is empty, return results for all referring items.
IDs of the referenced items. If the array is empty, return all referenced items for the referring items.
Order to by which to sort the results. Valid values are ASC
and DESC
.
Field ID to query in the referring collection.
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.
Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned.
When true
, the response includes the total number of the items that match the query.
When true
, the response includes the full referenced items. When false
, only the IDs of referenced items be returned.
Offset-based paging
Cursor-based paging
Retrieved references.
Paging information.
For a single data item, query and return a specified referenced item.
curl POST https://external-db.example.com/v3/items/query-referenced \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: <AUTH>' \
--d '{
"collectionId": "cities",
"referringItemIds": ["c285e77c-a86b-4361-a55f-c6b934d70187"],
"referencedItemIds": ["faa17edb-2d88-488d-8e95-24b9364c3284"],
"order": "ASC",
"referringFieldKey": "pointsOfInterest",
"paging": {
"limit": 1,
"offset": 0
},
"consistentRead": false,
"fieldsToReturn": [],
"returnTotalCount": false,
"includeReferencedItems": false
}'
{
"items": [
{
"referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187",
"referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284"
}
],
"pagingMetadata": {}
}