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.
You can only call this method when authenticated as a Wix app or Wix user identity.
ID of the collection containing the referring item.
ID of the referring item.
Field containing references in the referring item.
Order of the returned referenced items. Sorted by the date each item was referenced.
Whether to return the total count in the response.
When true
, the pagingMetadata
object in the response contains a total
field.
Default: false
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
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.
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.
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
.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.
Paging options to limit and skip the number of items.
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
.
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.
Paging information.
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"
}'
{
"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
}
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.