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 returnedWixDataQueryResult
istrue
. To retrieve more than 50 referenced items, use thequeryReferenced()
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.
Syntax
function include(propertyName: ...string): WixDataQuery
include Parameters
NAME
TYPE
DESCRIPTION
The properties for which to include referenced items.
Was this helpful?
1let newQuery = query.include("referenceField");
1import wixData from 'wix-data';23// ...45wixData.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;1314 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 found24 }25 })26 .catch((error) => {27 let errorMsg = error.message;28 let code = error.code;29 });
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.
1import wixData from 'wix-data';23// ...45wixData.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 found17 }18 })19 .catch((error) => {20 let errorMsg = error.message;21 let code = error.code;22 });23
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.
1import wixData from 'wix-data';23// ...45wixData.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 found17 }18 })19 .catch((error) => {20 let errorMsg = error.message;21 let code = error.code;22 });23
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.
1import wixData from 'wix-data';23// ...45$w("#myTable").columns = [6 {7 "id": "col1",8 // 'dataPath' is 'title' field from 'Books' collection9 "dataPath": "title",10 "label": "Book",11 "type": "string"12 }, {13 "id": "col2",14 // 'datapath' is 'name' field from the collection referenced15 // in the 'author' field16 "dataPath": "author.name",17 "label": "Author",18 "type": "string"19 }20];2122wixData.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