include( )
Includes referenced items for the specified properties in a query's results.
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.
The properties for which to include referenced items.