> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QueryReferencedDataItems # Package: cms # Namespace: DataItemService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/query-referenced-data-items.md ## Permission Scopes: Read Data Items: SCOPE.DC-DATA.READ ## Introduction 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 method 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 method 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. --- ## REST API ### Schema ``` Method: queryReferencedDataItems Description: 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 method 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 method 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. URL: https://www.wixapis.com/wix-data/v2/items/query-referenced Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId Method parameters: param name: appOptions | type: appOptions | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying: When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), 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`. param name: consistentRead | type: consistentRead | description: 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](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency). Default: `false` param name: dataCollectionId | type: dataCollectionId | description: GUID of the collection containing the referring item. | required: true param name: fields | type: array | description: 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. param name: language | type: language | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_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](https://www.wix.com/app-market/wix-multilingual). If not provided, result text is not translated. param name: order | type: SortOrder - enum: ASC - DESC - - ONE-OF: - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. - name: offset | type: integer | description: Number of items to skip in the current sort order. - name: cursorPaging | type: CursorPaging | description: 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`. - name: limit | type: integer | description: Number of items to load. - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. param name: publishPluginOptions | type: PublishPluginOptions - name: includeDraftItems | type: boolean | description: Whether to include draft items. When `true`, both published and draft items are affected. Default: `false`. param name: referringItemFieldName | type: referringItemFieldName | description: Field containing references in the referring item. param name: referringItemId | type: referringItemId | description: GUID of the referring item. param name: returnTotalCount | type: returnTotalCount | description: Whether to return the total count in the response. When `true`, the `pagingMetadata` object in the response contains a `total` field. Default: `false` Return type: QueryReferencedDataItemsResponse - name: results | type: array | description: Referenced items and/or GUIDs. For successfully resolved references, the referenced data item is returned. For references that can't be resolved, the GUID is returned. - ONE-OF: - name: dataItem | type: DataItem | description: Data item referenced. - name: id | type: string | description: Data item GUID. - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to - name: data | type: object | description: Data item contents. Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields: + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. - name: unresolvedReference | type: UnresolvedReference | description: Unresolved reference. Appears instead of the data item when the reference doesn't resolve, for example, when an GUID isn't found or if an item is in draft state. - name: referencedItemId | type: string | description: GUID of unresolved referenced item - name: unauthorized | type: boolean | description: Flag is set if item exists, but user is not authorized to read it - name: referringItemId | type: string | description: GUID of the referring item. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### Query referenced items, order by reference creation date and return only the first one ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/query-referenced' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "albums", "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105", "order": "ASC", "paging": { "limit": 1 } }' ``` ### Query referenced items ```curl curl -X POST \ 'https://www.wixapis.com/wix-data/v2/items/query-referenced' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "dataCollectionId": "albums", "referringItemFieldName": "songs", "referringItemId": "37de298e-026d-4b2e-b87f-fbec11d53105" }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.cms.DataItemService.queryReferencedDataItems(dataCollectionId, referringItem, field, options) Description: 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 method 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 method 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. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: dataCollectionId, referringItem, field Method parameters: param name: dataCollectionId | type: string | description: GUID of the collection containing the referring item. | required: true param name: field | type: string | description: Field containing references in the referring item. | required: true param name: options | type: WixDataQueryReferencedOptions none - name: order | type: SortOrder | description: Order of the returned referenced items. Sorted by the date each item was referenced. - enum: ASC, DESC - name: returnTotalCount | type: boolean | description: Whether to return the total count in the response. When `true`, the `pagingMetadata` object in the response contains a `total` field. Default: `false` - name: consistentRead | type: boolean | description: 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](https://dev.wix.com/api/rest/wix-data/wix-data/eventual-consistency). Default: `false` - name: language | type: string | description: Language to translate result text into, in [IETF BCP 47 language tag](https://en.wikipedia.org/wiki/IETF_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](https://www.wix.com/app-market/wix-multilingual). If not provided, result text is not translated. - name: fields | type: array | description: 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. - name: appOptions | type: object | description: Additional parameters specific to the [Wix app collection](https://support.wix.com/en/article/cms-formerly-content-manager-working-with-wix-app-collections) you are querying: When querying the Wix Stores [Products collection](https://dev.wix.com/docs/develop-websites/articles/wix-apps/wix-e-commerce-stores/wix-stores-products-collection-fields.md), 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`. - name: showDrafts | type: boolean | description: When `true`, operations include draft items. Read operations include draft items in their response, and write operations modify draft items. - name: suppressHooks | type: boolean | description: Prevents hooks from running for the operation. Can only be used in the [backend code of a Wix site](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/backend-code/about-the-site-backend.md). - name: skip | type: integer | description: Number of items to skip in the current sort order. Default: `0` - name: limit | type: integer | description: Number of items to load. Default: `50` param name: referringItem | type: string | description: GUID of the referring item. | required: true Return type: PROMISE - name: results | type: array | description: Referenced items and/or GUIDs. For successfully resolved references, the referenced data item is returned. For references that can't be resolved, the GUID is returned. - ONE-OF: - name: dataItem | type: DataItem | description: Data item referenced. - name: _id | type: string | description: Data item GUID. - name: dataCollectionId | type: string | description: GUID of the collection this item belongs to - name: data | type: object | description: Data item contents. Property-value pairs representing the data item's payload. When retrieving a data item, it also includes the following read-only fields: + `_id`: Item GUID. + `_createdDate`: Date and time the item was added to the collection. + `_updatedDate`: Date and time the item was last modified. When the item is first inserted, `_createdDate` and `_updatedDate` have the same value. + `_ownerId`: GUID of the user who created the item. Can be modified with site owner permissions. - name: unresolvedReference | type: UnresolvedReference | description: Unresolved reference. Appears instead of the data item when the reference doesn't resolve, for example, when an GUID isn't found or if an item is in draft state. - name: referencedItemId | type: string | description: GUID of unresolved referenced item - name: unauthorized | type: boolean | description: Flag is set if item exists, but user is not authorized to read it - name: referringItemId | type: string | description: GUID of the referring item. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: count | type: integer | description: Number of items returned in the response. - name: offset | type: integer | description: Offset that was requested. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used, `returnTotalCount` is `true` in the request, and `tooManyToCount` is false. - name: tooManyToCount | type: boolean | description: Whether the server failed to calculate the `total` field. - name: cursors | type: Cursors | description: Cursors to navigate through the result pages using `next` and `prev`. Returned if cursor paging is used. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: prev | type: string | description: Cursor pointing to previous page in the list of results. ``` ### Examples ### queryReferenced ```javascript import { items } from '@wix/data'; async function queryReferenced(dataCollectionId,referringItem,field,options) { const response = await items.queryReferenced(dataCollectionId,referringItem,field,options); }; ``` ### queryReferenced (with elevated permissions) ```javascript import { items } from '@wix/data'; import { auth } from '@wix/essentials'; async function myQueryReferencedMethod(dataCollectionId,referringItem,field,options) { const elevatedQueryReferenced = auth.elevate(items.queryReferenced); const response = await elevatedQueryReferenced(dataCollectionId,referringItem,field,options); } ``` ### queryReferenced (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { items } from '@wix/data'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { items }, // Include the auth strategy and host as relevant }); async function queryReferenced(dataCollectionId,referringItem,field,options) { const response = await myWixClient.items.queryReferenced(dataCollectionId,referringItem,field,options); }; ``` ---