include( )

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

The include() method 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() method:

• 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() method.
• 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() method.

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