Page Contents

See also: Querying related models.

An include filter enables you to include results from related models in a query, for example models that have belongsTo or hasMany relations, to optimize the number of requests. See Creating model relations for more information.

The value of the include filter can be a string, an array, or an object.

REST API

filter[include][relatedModel]=propertyName You can also use stringified JSON format in a REST query.

Node API

{include: 'relatedModel'}
{include: ['relatedModel1', 'relatedModel2', ...]}
{include: {relatedModel1: [{relatedModel2: 'relationName'} , 'relatedModel']}}

Where:

  • relatedModel, relatedModel1, and relatedModel2 are the names (pluralized) of related models.
  • relationName is the name of a relation in the related model.

Examples

Include relations without filtering:

User.find({include: 'posts'}, function() { /* ... */ });

Return all user posts and orders with two additional requests:

User.find({include: ['posts', 'orders']}, function() { /* ... */ });

Return all post owners (users), and all orders of each owner:

Post.find({include: {owner: 'orders'}}, function() { /* ... */ });

Return all post owners (users), and all friends and orders of each owner:

Post.find({include: {owner: ['friends', 'orders']}}, function() { /* ... */ });

Return all post owners (users), and all posts and orders of each owner. The posts also include images.

Post.find({include: {owner: [{posts: 'images'} , 'orders']}}, function() { /* ... */ });

Combined use of fields and include for a belongsTo relation

If you want to use both include and fields to display only specific fields of a model and a specific belongsTo relation, you need to add the relation foreign key in the fields :

Return all posts only with field title and the relation category:

Post.find({include: 'category', fields: ['title', 'categoryId']}, function() { /* ... */ });

Include with filters

In some cases, you may want to apply filters to related models to be included.

LoopBack supports that with the following syntax (for example):

Post.find({
  include: {
    relation: 'owner', // include the owner object
    scope: { // further filter the owner object
      fields: ['username', 'email'], // only show two fields
      include: { // include orders for the owner
        relation: 'orders', 
        scope: {
          where: {orderId: 5} // only select order with id 5
        }
      }
    }
  }
}, function() { /* ... */ });

For real-world scenarios where only users in $authenticated or $owner roles should have access, use findById(). For example, the following example uses filters to perform pagination:

Post.findById('123', {
  include: {
    relation: 'orders',
    scope: { // fetch 1st "page" with 5 entries in it
      skip:0,
      limit:5
    }
  }
}, function() { /* ... */ });

Access included objects

In the Node.js API, call toJSON() to convert the returned model instance with related items into a plain JSON object. For example:

Post.find({include: {owner: [{posts: 'images'} , 'orders']}}, function(err, posts) {
 posts.forEach(function(post) {
   // post.owner points to the relation method instead of the owner instance
   var p = post.toJSON();
   console.log(p.owner.posts, p.owner.orders);
 });
 //... 
});

Note the relation properties such as post.owner reference a JavaScript function for the relation method.

REST examples

These examples assume a customer model with a hasMany relationship to a reviews model. 

Return all customers including their reviews:

/customers?filter[include]=reviews

Return all customers including their reviews which also includes the author:

/customers?filter[include][reviews]=author

Return all customers whose age is 21, including their reviews which also includes the author:

/customers?filter[include][reviews]=author&filter[where][age]=21

Return first two customers including their reviews which also includes the author

/customers?filter[include][reviews]=author&filter[limit]=2

Return all customers including their reviews and orders

/customers?filter[include]=reviews&filter[include]=orders