> 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: externalDatabases # Namespace: ExternalDatabaseService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/cms/external-databases/external-database-service-plugin/query-referenced-data-items.md ## Introduction 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 referenced 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](https://dev.wix.com/docs/rest/assets/data/external-database-spi/query-data-items.md) endpoint for the **Awards** collection. > - This endpoint might also be called when a user calls the [isReferenced](https://dev.wix.com/docs/rest/api-reference/wix-data/data-items/is-referenced-data-item.md) endpoint of the Wix Data API. --- ## REST API ### Schema ``` Method: queryReferencedDataItems Description: 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 referenced items of any **Movie** item, the response contains the referenced **Actor** items, but only the GUIDs 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](https://dev.wix.com/docs/rest/assets/data/external-database-spi/query-data-items.md) endpoint for the **Awards** collection. > - This endpoint might also be called when a user calls the [isReferenced](https://dev.wix.com/docs/rest/api-reference/wix-data/data-items/is-referenced-data-item.md) endpoint of the Wix Data API. URL: null Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: collectionId, referringFieldKey, consistentRead, returnTotalCount, includeReferencedItems Method parameters: param name: collectionId | type: collectionId | description: GUID of the collection to query. | required: true 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. Applicable if the external database is eventually consistent. | required: true param name: fieldsToReturn | type: array | description: Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned. param name: includeReferencedItems | type: includeReferencedItems | description: When `true`, the response includes the full referenced items. When `false`, only the GUIDs of referenced items be returned. | required: true param name: order | type: SortOrder - enum: ASC - DESC - - ONE-OF: - name: paging | type: Paging | description: Offset-based paging - 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-based paging - 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: referencedItemIds | type: array | description: IDs of the referenced items. If the array is empty, return all referenced items for the referring items. param name: referringFieldKey | type: referringFieldKey | description: Field GUID to query in the referring collection. | required: true param name: referringItemIds | type: array | description: IDs of the referring items. If the array is empty, return results for all referring items. param name: returnTotalCount | type: returnTotalCount | description: When `true`, the response includes the total number of the items that match the query. | required: true Return type: QueryReferencedDataItemsResponse - name: items | type: array | description: Retrieved references. - name: referringItemId | type: string | description: GUID of the item in the referring collection. - name: referencedItemId | type: string | description: GUID of the item in the referenced collection. - name: referencedItem | type: object | description: Item in the referenced collection. If the external database does not support returning referenced items, this field can remain empty. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - 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 for and return any referenced items For a single data item, query and return all referenced items. ```curl curl -X POST https://external-db.example.com/v3/items/query-referenced \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ -d '{ "collectionId": "cities", "referringItemIds": ["c285e77c-a86b-4361-a55f-c6b934d70187"], "referencedItemIds": [], "order": "ASC", "referringFieldKey": "pointsOfInterest", "paging": { "limit": 50, "offset": 0 }, "consistentRead": false, "fieldsToReturn": [], "returnTotalCount": false, "includeReferencedItems": true }' ``` ### Query for referenced items For a single data item, query and return a specified referenced item. ```curl curl -X POST https://external-db.example.com/v3/items/query-referenced \ -H 'Content-Type: application/json;charset=UTF-8' \ -H 'Authorization: ' \ -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 }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.externalDatabases.ExternalDatabaseService.queryReferencedDataItems(request, metadata) Description: 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 referenced items of any **Movie** item, the response contains the referenced **Actor** items, but only the GUIDs 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](https://dev.wix.com/docs/rest/assets/data/external-database-spi/query-data-items.md) endpoint for the **Awards** collection. > - This endpoint might also be called when a user calls the [isReferenced](https://dev.wix.com/docs/rest/api-reference/wix-data/data-items/is-referenced-data-item.md) endpoint of the Wix Data API. Method parameters: param name: metadata | type: Context | description: this message is not directly used by any service, it exists to describe the expected parameters that SHOULD be provided to invoked Velo methods as part of open-platform. e.g. SPIs, event-handlers, etc.. NOTE: this context object MUST be provided as the last argument in each Velo method signature. Example: ```typescript export function wixStores_onOrderCanceled({ event, metadata }: OrderCanceledEvent) { ... } ``` - name: requestId | type: string | description: A unique identifier of the request. You may print this GUID to your logs to help with future debugging and easier correlation with Wix's logs. - name: currency | type: string | description: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) 3-letter currency code. - name: identity | type: IdentificationData | description: An object that describes the identity that triggered this request. - ONE-OF: - name: anonymousVisitorId | type: string | description: GUID of a site visitor that has not logged in to the site. - name: memberId | type: string | description: GUID of a site visitor that has logged in to the site. - name: wixUserId | type: string | description: GUID of a Wix user (site owner, contributor, etc.). - name: appId | type: string | description: GUID of an app. - name: languages | type: array | description: A string representing a language and region in the format of `"xx-XX"`. First 2 letters represent the language code according to ISO 639-1. This is followed by a dash "-", and then a by 2 capital letters representing the region according to ISO 3166-2. For example, `"en-US"`. - name: instanceId | type: string | description: The service provider app's instance GUID. param name: request | type: QueryReferencedDataItemsRequest - ONE-OF: - name: paging | type: Paging | description: Offset-based paging - 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-based paging - 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. - name: collectionId | type: string | description: GUID of the collection to query. - name: referringItemIds | type: array | description: IDs of the referring items. If the array is empty, return results for all referring items. - name: referencedItemIds | type: array | description: IDs of the referenced items. If the array is empty, return all referenced items for the referring items. - name: order | type: SortOrder | description: Order to by which to sort the results. Valid values are `ASC` and `DESC`. - enum: ASC, DESC - name: referringFieldKey | type: string | description: Field GUID to query in the referring collection. - 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. Applicable if the external database is eventually consistent. - name: fieldsToReturn | type: array | description: Fields to return in the referenced item. If the array is empty or not provided, all fields in the referenced item are returned. - name: returnTotalCount | type: boolean | description: When `true`, the response includes the total number of the items that match the query. - name: includeReferencedItems | type: boolean | description: When `true`, the response includes the full referenced items. When `false`, only the GUIDs of referenced items be returned. Return type: PROMISE - name: items | type: array | description: Retrieved references. - name: referringItemId | type: string | description: GUID of the item in the referring collection. - name: referencedItemId | type: string | description: GUID of the item in the referenced collection. - name: referencedItem | type: object | description: Item in the referenced collection. If the external database does not support returning referenced items, this field can remain empty. - name: pagingMetadata | type: PagingMetadataV2 | description: Paging information. - name: total | type: integer | description: Total number of items that match the query. Returned if offset paging is used and the `tooManyToCount` flag is not set. - 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 ### Example of `items` and `pagingMetadata` return values ```javascript import { externalDatabase } from '@wix/data/service-plugins'; externalDatabase.provideHandlers({ queryReferencedDataItems: async ( payload ) => { const {request, metadata} = payload; // Use the `request` and `metadata` received from Wix and // apply custom logic. return { // Return your response exactly as documented to integrate with Wix. // Return value example: items: [ { referringItemId: "c285e77c-a86b-4361-a55f-c6b934d70187", referencedItemId: "faa17edb-2d88-488d-8e95-24b9364c3284" } ], pagingMetadata: {} } } }); ``` ### queryReferencedDataItems (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 { externalDatabase } from '@wix/data/service-plugins'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { externalDatabase }, // Include the auth strategy and host as relevant }); async function queryReferencedDataItems(request,metadata) { const response = await myWixClient.externalDatabase.queryReferencedDataItems(request,metadata); }; ``` ---