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:

• Up to 100 properties with multiple references can be included.
• By default, each returned item can include up to 50 referenced items. To change this limit, pass a numeric value as the final argument to include(). For example, .include("publishers", 200) returns a maximum of 200 publishers for every item. The limit applies to all multi-reference fields being included. For example, .include("publishers", "authors", 200) returns a maximum of 200 publishers and 200 authors for every item. The maximum value that can be set is 1000. If no limit is provided, it defaults to 50. To retrieve more referenced items, use queryReferenced().

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