From 8a178ada12a39d3754d5a917b5e371be1d860da0 Mon Sep 17 00:00:00 2001
From: Valeri Karpov <val@karpov.io>
Date: Fri, 14 Sep 2018 10:24:03 -0400
Subject: [PATCH] docs: add selectPopulatedPaths option

Re: #6546
---
 docs/guide.jade | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/docs/guide.jade b/docs/guide.jade
index fc5e1ec7388..cbd73e676f5 100644
--- a/docs/guide.jade
+++ b/docs/guide.jade
@@ -358,6 +358,7 @@ block content
     - [collation](#collation)
     - [skipVersioning](#skipVersioning)
     - [timestamps](#timestamps)
+    - [selectPopulatedPaths](#selectPopulatedPaths)
 
     <h3 id="autoIndex"><a href="#autoIndex">option: autoIndex</a></h3>
 
@@ -867,6 +868,44 @@ block content
     });
     ```
 
+    <h3 id="selectPopulatedPaths">
+      <a href="#selectPopulatedPaths">
+        option: selectPopulatedPaths
+      </a>
+    </h3>
+
+    By default, Mongoose will automatically `select()` any populated paths for
+    you, unless you explicitly exclude them.
+
+    ```javascript
+    const bookSchema = new Schema({
+      title: 'String',
+      author: { type: 'ObjectId', ref: 'Person' }
+    });
+    const Book = mongoose.model('Book', bookSchema);
+
+    // By default, Mongoose will add `author` to the below `select()`.
+    await Book.find().select('title').populate('author');
+
+    // In other words, the below query is equivalent to the above
+    await Book.find().select('title author').populate('author');
+    ```
+
+    To opt out of selecting populated fields by default, set `selectPopulatedPaths`
+    to `false` in your schema.
+
+    ```javascript
+    const bookSchema = new Schema({
+      title: 'String',
+      author: { type: 'ObjectId', ref: 'Person' }
+    }, { selectPopulatedPaths: false });
+    const Book = mongoose.model('Book', bookSchema);
+
+    // Because `selectPopulatedPaths` is false, the below doc will **not**
+    // contain an `author` property.
+    const doc = await Book.findOne().select('title').populate('author');
+    ```
+
     <h3 id="plugins"><a href="#plugins">Pluggable</a></h3>
 
     Schemas are also [pluggable](./plugins.html) which allows us to package up reusable features into