queryReferenced( )

Gets the full items referenced in the specified property.

Description

The queryReferenced() function returns a Promise that resolves to the full items that are referenced in the specified property of the item from the specified collection. The Promise is rejected if the current user does not have read permissions for the specified collection or the collection containing the referenced items.

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 queryReferenced() returns the relevant People items referenced in the Actors field of the specified Movies item. Meaning, it returns the full actor information for all actors in the specified movie.

The queryReferenced() function can be used instead of a standard query() with an include() to overcome the limitations of the include() function.

You can optionally control the order of the returned referenced items by passing a WixDataQueryReferencedOptions object.

Notes:
Calling the queryReferenced() function does not trigger any hooks.
You can only use the queryReferenced() function with multiple-item reference fields, and not with single-item (regular) reference fields.
The queryReferenced() function is not supported for Single Item Collections.

For a discussion of when to use the similar include() function and when to use queryReferenced(), see Querying Items that Reference Other Items.

Syntax

function queryReferenced(collectionId: string, item: Object | string, propertyName: string, [options: WixDataQueryReferencedOptions]): Promise<WixDataQueryReferencedResult>

queryReferenced Parameters

NAME

TYPE

DESCRIPTION

collectionId

string

The ID of the collection that contains the referring item.

To find your collectionId, select the Databases tab in the Velo Sidebar. Hover over your collection, click the three dots, and select Edit Settings.

item

Object | string

The referring item or referring item's ID.

propertyName

string

The property that contains the references to the referenced items.

options

Optional

WixDataQueryReferencedOptions

An object for controlling the order of the returned referenced items.

Returns

Fulfilled - The referenced items. Rejected - The error that caused the rejection.

Return Type:

Promise<WixDataQueryReferencedResult>

Was this helpful?

Get referenced items

This example finds the item in the Movies collection with the ID 00001. It gets all of the items referenced in the Actors field of that item and then stores the first actor in a variable.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.queryReferenced("movies", "00001", "actors")
6  .then((results) => {
7    if(results.items.length > 0) {
8      console.log(results.items[0]); //see item below
9    } else {
10      // handle case where no matching items found
11    }
12  })
13  .catch((err) => {
14    console.log(err);
15  });
16
17/*  firstItem is:
18 *
19 *  {
20 *    "_id":          "12345",
21 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
22 *    "_createdDate": "2017-05-24T12:33:18.938Z",
23 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
24 *    "first_name":   "John",
25 *    "last_name":    "Doe"
26 *  }
27 */
28

Get referenced items using options

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5let options = {
6  "order": "asc"
7};
8
9wixData.queryReferenced("movies", "00001", "actors", options)
10  .then((results) => {
11    if(results.items.length > 0) {
12      console.log(results.items[0]); //see item below
13    } else {
14      // handle case where no matching items found
15    }
16  })
17  .catch((err) => {
18    console.log(err);
19  });
20
21/*  firstItem is:
22 *
23 *  {
24 *    "_id":          "12345",
25 *    "_owner":       "ffdkj9c2-df8g-f9ke-lk98-4kjhfr89keedb",
26 *    "_createdDate": "2017-05-24T12:33:18.938Z",
27 *    "_updatedDate": "2017-05-24T12:33:18.938Z",
28 *    "first_name":   "John",
29 *    "last_name":    "Doe"
30 *  }
31 */