POST

Query Referenced Data Items


Retrieves the full items referenced in the specified field of an item.

Reference and multi-reference fields refer to items in different collections. Use this endpoint to retrieve the full details of the referenced items themselves.

For example, suppose you have a Movies collection with an Actors field that contains references to items in a People collection. Querying the Movies collection using the Query Referenced Data Items endpoint returns the relevant People items referenced in the Actors field of the specified Movie item. This gives you information from the People collection about each of the actors in the specified movie.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Read Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/wix-data/v2/items/query-referenced

Body Params
dataCollectionIdstringRequired

ID of the collection containing the referring item.


referringItemIdstring

ID of the referring item.


referringItemFieldNamestring

Field containing references in the referring item.


orderstring

Order of the returned referenced items. Sorted by the date each item was referenced.


returnTotalCountboolean

Whether to return the total count in the response. When true, the pagingMetadata object in the response contains a total field.

Default: false


consistentReadboolean

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. Learn more about Wix Data and eventual consistency.

Default: false


languagestringformat LANGUAGE_TAG

Language to translate result text into, in IETF BCP 47 language tag format. If provided, the result text is returned in the specified language. Note: Translation for the specified language must be enabled for the collection in Wix Multilingual.

If not provided, result text is not translated.


fieldsArray <string>maxItems 10000maxLength 1000

Fields to return for each referenced item. Only fields specified in the array are included in the response. If the array is empty, all fields are returned. Note: The _id system field is always returned.


appOptionsstruct

Additional parameters specific to the Wix app collection you are querying:

When querying the Wix Stores Products collection, pass the following optional parameters:

  • includeHiddenProducts: Whether to include hidden products in the response. Default: false.
  • includeVariants: Whether to include product variants in the query. Default: false.

publishPluginOptionsPublishPluginOptions

Options for the Publish plugin. This plugin allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not.


ONE OF:

pagingPaging

Paging options to limit and skip the number of items.


cursorPagingCursorPaging

Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not filter or sort.

Response Object
resultsArray <ReferencedResult>

Referenced items and/or IDs. For successfully resolved references, the referenced data item is returned. For references that can't be resolved, the ID is returned.


pagingMetadataPagingMetadata

Paging information.

Request
cURL
curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/query-referenced' \ -H 'Content-Type: application/json' \ -H 'Authorization: <AUTH>' \ -d '{ "dataCollectionId": "albums", "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105" }'
Response
JSON
{ "results": [ { "dataItem": { "id": "99cb26d5-dd42-4384-af30-3bb6e4026bd0", "dataCollectionId": "songs", "data": { "_id": "99cb26d5-dd42-4384-af30-3bb6e4026bd0", "_createdDate": { "$date": "2023-03-28T12:20:43.745Z" }, "_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" }, "_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360", "title": "I Should Have Known Better" } } }, { "dataItem": { "id": "b10170b2-2e0d-4093-b472-cf8f2982a247", "dataCollectionId": "songs", "data": { "_id": "b10170b2-2e0d-4093-b472-cf8f2982a247", "_createdDate": { "$date": "2023-03-28T12:20:43.745Z" }, "_updatedDate": { "$date": "2023-03-28T12:20:43.745Z" }, "_owner": "690264f5-29a0-4aa8-a9b5-0842fc5ab360", "title": "If I Fell" } } } ], "pagingMetadata": { "count": 2 } }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?