Waterline projections

Summary

Waterline projections in Sails.js allow you to control which fields are returned in a query. There are two types of projections:

1. Select Projection: Specifies the fields to include in the query result.

   • Example: User.find().select(['name', 'age'])

   • The id field is always included by default.

   • Can also be specified inside the criteria object.

2. Omit Projection: Specifies the fields to exclude from the query result.

   • Example: User.find().omit(['socialSecurityNumber'])

   • Returns all fields except the specified ones.

Key Assumptions in Waterline Projections

• The id field is always included in query results.

• You cannot use select and omit together in the same query.

• If using shorthand for the where clause, you must expand it before applying select or omit.

Using projections helps optimize queries, making them faster and more efficient in a Sails application.

Transcript

What's up my friend, my name is Kelvin and welcome to this screencast. In this screencast, we're going to be looking at Waterline projections.

Now I'm going to open up the Sails console and execute a Waterline query to get all user records belonging to the User model. When I log that in, you’ll see that we have multiple users, each with attributes like updatedAt, id, name, socialSecurityNumber, gender, age, and birthday.

But what if I want to control what gets returned from that query? That’s where projections come in.

Select Projection

Select projections allow you to specify which fields you want in the query results.

• Using .select() method:

  User.find().select(['name', 'age'])

  This returns only name and age, but Waterline still includes id by default.

• Alternative syntax:

  User.find({ select: ['name', 'age'] })

  This achieves the same result using a criteria object.

Omit Projection

Omit projections let you exclude certain fields from the query results.

• Example:

  User.find().omit(['socialSecurityNumber'])

  This returns all fields except the social security number.

Waterline Assumptions & Limitations

• ID Always Included: Waterline always returns the id field, even if not explicitly selected.

• Cannot Use select and omit Together: You must choose either select or omit in a single query.

• Where Clause Shorthand Conflicts:
  If you use a shorthand where clause like:

  User.find({ gender: 'female' }).select(['name'])

  Waterline will throw an error. Instead, expand the query:

  User.find({ where: { gender: 'female' }, select: ['name'] })

That’s it for Waterline projections! They make queries faster and give you better control over your data in a Sails application. Hope this helps, and I’ll see you in the next screencast!