> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# Method name: include(propertyName: Array<string>)

# Method package: wixData

# Method menu location: wixData --> WixDataQuery --> include

# Method Link: https://dev.wix.com/docs/velo/apis/wix-data/wix-data-query/include.md

# Method Description:

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()`](https://dev.wix.com/docs/sdk/business-solutions/data/items/query-referenced.md).


 For a discussion of when to use the similar [`queryReferenced()`](wix-data.html#queryReferenced)
 function and when to use `include()`, see [Querying Items that Reference Other Items](https://support.wix.com/en/article/including-referenced-data-when-filtering).

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



# Method Code Examples:

*** Note: do not assume any prop names or enum values other than the ones in the example.

## Add an include to a query

```javascript
let newQuery = query.include("referenceField");
```

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

```javascript
import wixData from 'wix-data';

// ...

wixData.query("myCollection")
  .include("referenceField")
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      let items = results.items;
      let firstItem = items[0];
      let firstRefProp = firstItem.referenceField.propertyName;

      let totalCount = results.totalCount;
      let pageSize = results.pageSize;
      let currentPage = results.currentPage;
      let totalPages = results.totalPages;
      let hasNext = results.hasNext();
      let hasPrev = results.hasPrev();
      let length = results.length;
      let query = results.query;
    } else {
      // handle case where no matching items found
    }
  })
  .catch((error) => {
    let errorMsg = error.message;
    let code = error.code;
  });
```

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

```javascript
import wixData from 'wix-data';

// ...

wixData.query("books")
  .include("author", "publisher")
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      let books = results.items;
      let firstBook = books[0];
      let firstAuthor = firstBook.author;
      let firstAuthorBio = firstAuthor.bio;
      let firstPublisher = firstBook.publisher.name;
    } else {
      // handle case where no matching items found
    }
  })
  .catch((error) => {
    let errorMsg = error.message;
    let code = error.code;
  });

```

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

```javascript
import wixData from 'wix-data';

// ...

wixData.query("books")
  .eq("publisher", "00001")
  .include("author")
  .find()
  .then((results) => {
    if(results.items.length > 0) {
      let books = results.items;
      let firstBook = books[0];
      let firstAuthor = firstBook.author;
      let firstAuthorBio = firstAuthor.bio;
    } else {
      // handle case where no matching items found
    }
  })
  .catch((error) => {
    let errorMsg = error.message;
    let code = error.code;
  });

```

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

```javascript
import wixData from 'wix-data';

// ...

$w("#myTable").columns = [
  {
    "id": "col1",
    // 'dataPath' is 'title' field from 'Books' collection
    "dataPath": "title", 
    "label": "Book",
    "type": "string"
  }, {
    "id": "col2",
    // 'datapath' is 'name' field from the collection referenced
    // in the 'author' field 
    "dataPath": "author.name",
    "label": "Author",
    "type": "string"
  }
];

wixData.query("books")
  .include("author")
  .find()
  .then((myResults) => {
    if(myResults.items.length > 0) {
      $w("#myTable").rows = myResults.items;
    }
    else {
      console.log("No results found.");
    }
  });

```

---