include( )

Includes referenced items for the specified properties in a query's results.

Description

The include() function refines a query so that the items returned in the query's results include the full referenced items for the specified properties.

For example, suppose you have a books collection with an author field that references an authors collection. Querying the books collection with an include("author") returns the relevant book items and each item will include the full referenced author item in the book's author property.

When querying a collection that contains a reference field without using the include() function:

Single reference field: returned items contain only the ID of the referenced item, and not the full referenced items.
Multiple reference field: returned items do not contain the multiple reference field at all.

When including a property with multiple references, the following limitations apply:

Only one property with multiple references can be included.
The query will return an error if more than 50 items are returned, regardless of any query limit set using the limit() function.
Each returned item can include up to 50 referenced items. If there are more than 50 referenced items, only 50 are returned when the query is run and the partialIncludes property of the returned WixDataQueryResult is true. To retrieve more than 50 referenced items, use the queryReferenced() function.

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

Notes:
Calling the include() function does not trigger any hooks.
The include() function is not supported for Single Item Collections.

Authorization

Request

This endpoint does not take any parameters

Response Object

A WixDataQuery object representing the query.

Returns an empty object.

Status/Error Codes

Was this helpful?

Add an include to a query

Copy Code

1let newQuery = query.include("referenceField");

Create a query, include a reference field, and run it

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.query("myCollection")
6  .include("referenceField")
7  .find()
8  .then((results) => {
9    if(results.items.length > 0) {
10      let items = results.items;
11      let firstItem = items[0];
12      let firstRefProp = firstItem.referenceField.propertyName;
13
14      let totalCount = results.totalCount;
15      let pageSize = results.pageSize;
16      let currentPage = results.currentPage;
17      let totalPages = results.totalPages;
18      let hasNext = results.hasNext();
19      let hasPrev = results.hasPrev();
20      let length = results.length;
21      let query = results.query;
22    } else {
23      // handle case where no matching items found
24    }
25  })
26  .catch((error) => {
27    let errorMsg = error.message;
28    let code = error.code;
29  });

Create a query, include a reference field, and run it

In this example there is a books collection which has two reference fields that reference an authors collection and a publishers collection.

The query includes the author and publisher properties so that each returned book will also include the full items of its referenced author and publisher.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.query("books")
6  .include("author", "publisher")
7  .find()
8  .then((results) => {
9    if(results.items.length > 0) {
10      let books = results.items;
11      let firstBook = books[0];
12      let firstAuthor = firstBook.author;
13      let firstAuthorBio = firstAuthor.bio;
14      let firstPublisher = firstBook.publisher.name;
15    } else {
16      // handle case where no matching items found
17    }
18  })
19  .catch((error) => {
20    let errorMsg = error.message;
21    let code = error.code;
22  });
23

Create a query, include a reference field, and run it

In this example there is a books collection which has two reference fields that reference an authors collection and a publishers collection.

The query is refined to only include books from a specific publisher using the eq() function and the publisher's ID.

The query also includes the author property so that each returned book will include the full item of its referenced author.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5wixData.query("books")
6  .eq("publisher", "00001")
7  .include("author")
8  .find()
9  .then((results) => {
10    if(results.items.length > 0) {
11      let books = results.items;
12      let firstBook = books[0];
13      let firstAuthor = firstBook.author;
14      let firstAuthorBio = firstAuthor.bio;
15    } else {
16      // handle case where no matching items found
17    }
18  })
19  .catch((error) => {
20    let errorMsg = error.message;
21    let code = error.code;
22  });
23

Create a query, include a reference field, and populate a table with the results

In this example there is a books collection which has one reference field, author, that references an authors collection.

The columns of a table are set to show information from both the books collection and the referenced authors collection.

The query includes the author property so that each returned book will include the full item of its referenced author.

Copy Code

1import wixData from 'wix-data';
2
3// ...
4
5$w("#myTable").columns = [
6  {
7    "id": "col1",
8    // 'dataPath' is 'title' field from 'Books' collection
9    "dataPath": "title", 
10    "label": "Book",
11    "type": "string"
12  }, {
13    "id": "col2",
14    // 'datapath' is 'name' field from the collection referenced
15    // in the 'author' field 
16    "dataPath": "author.name",
17    "label": "Author",
18    "type": "string"
19  }
20];
21
22wixData.query("books")
23  .include("author")
24  .find()
25  .then((myResults) => {
26    if(myResults.items.length > 0) {
27      $w("#myTable").rows = myResults.items;
28    }
29    else {
30      console.log("No results found.");
31    }
32  });
33