We are excited to announce the addition of the include() function to the wix-data API. The include() function is used when querying a collection that contains reference fields.

Previously, when you queried such a collection, you would only receive the IDs of referenced items in the query results. Now, using the include() function, you can retrieve the entire reference item in the query results.

How it works

Simply add the include() function to your query building chain before calling the find() function.

Example

Suppose you have a collection of books that contains a reference field that refers to the book’s author data, which is stored in another collection. You could write the following query to find all the books over 250 pages and receive the full author information in the results.

import wixData from 'wix-data';

// ...

wixData.query("books")
  .ge("pages", 250)
 .include("author")
  .find()
  .then( (results) => {
 let books = results.items;
 let firstBook = items[0];
 let firstAuthor = firstBook.author.name;
  } )
  .catch( (error) => {
 let errorMsg = error.message;
 let code = error.code;
  } );

Here, a single one of the resulting items will look something like this.

{
 "_id":"37d9a27a-6b13-4c8d-ac40-5ce8dac7a64f",
 "_owner":"f6c0f9c2-a02d-4e9f-a58d-99729af244d9",
 "_createdDate":"2018-02-07T13:40:40.765Z",
 "_updatedDate":"2018-02-07T13:46:47.132Z",
 "title":"Amazing Book",
 "publisher":"A Publishing House",
 "pages":"375",
 "author": {
 "_id":"c4cb45bc-bece-4ef7-bfee-e47c5b6f9d8e",
 "_owner":"f6c0f9c2-a02d-4e9f-a58d-99729af244d9",
 "_createdDate":"2018-02-07T13:40:05.542Z",
 "_updatedDate":"2018-02-07T13:40:05.542Z",
 "name":"John Doe",
 "dob":"1963-04-08T00:00:00.000Z",
 "bio":"John is a prolific author and lives in NYC with his six dogs."
 }
} 

Learn more

To learn more, see the include() function in the API Reference.