POST

Query Referenced 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 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:

  • This endpoint does not retrieve the full referenced items of referenced items. For example, the referenced Actors collection might itself contain a multi-reference field with references to Award items in an Awards collection. When calling this endpoint to retrieve the refernced items of any Movie item, the response contains the referenced Actor items, but only the IDs of the Award items. To retrieve the full Award items, the user must either call this endpoint for the Actors collection, or the Query Data Items endpoint for the Awards collection.
  • This endpoint might also be called when a user calls the isReferenced endpoint of the Wix Data API.
Endpoint
POST
{DEPLOYMENT-URI}/v3/items/query-referenced
Body Params
collectionIdstringRequired

ID of the collection to query.


referringItemIdsArray <string>maxItems 1000

IDs of the referring items. If the array is empty, return results for all referring items.


referencedItemIdsArray <string>maxItems 1000

IDs of the referenced items. If the array is empty, return all referenced items for the referring items.


orderstring

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


referringFieldKeystringRequired

Field ID to query in the referring collection.


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.


fieldsToReturnArray <string>

Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned.


returnTotalCountbooleanRequired

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


includeReferencedItemsbooleanRequired

When true, the response includes the full referenced items. When false, only the IDs of referenced items be returned.


ONE OF:

pagingPaging

Offset-based paging


cursorPagingCursorPaging

Cursor-based paging

Response Object
itemsArray <ReferencedItem>

Retrieved references.


pagingMetadataPagingMetadata

Paging information.

For a single data item, query and return a specified referenced item.

Request
cURL
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 }'
Response
JSON
{ "items": [ { "referringItemId": "c285e77c-a86b-4361-a55f-c6b934d70187", "referencedItemId": "faa17edb-2d88-488d-8e95-24b9364c3284" } ], "pagingMetadata": {} }
Did this help?