diff --git a/docs/source/api/collections.md b/docs/source/api/collections.md index a90c3e24ae..355686e820 100644 --- a/docs/source/api/collections.md +++ b/docs/source/api/collections.md @@ -201,10 +201,10 @@ changes the documents in a cursor will trigger a recomputation. To disable this behavior, pass `{reactive: false}` as an option to `find`. -Note that when `fields` are specified, only changes to the included +Note that when `projection` are specified, only changes to the included fields will trigger callbacks in `observe`, `observeChanges` and invalidations in reactive computations using this cursor. Careful use -of `fields` allows for more fine-grained reactivity for computations +of `projection` allows for more fine-grained reactivity for computations that don't depend on an entire document. On the client, there will be a period of time between when the page loads and @@ -216,6 +216,8 @@ collections will be empty. Equivalent to [`find`](#find)`(selector, options).`[`fetch`](#fetch)`()[0]` with `options.limit = 1`. +> **Note**: The `fields` option is deprecated in favor of `projection`, which aligns with MongoDB's official terminology and driver. Using `projection` ensures consistency and clarity in specifying which fields to include or exclude in query results. + {% apibox "Mongo.Collection#findOneAsync" %} Async version of [`findOne`](#findOne) that return a `Promise`. @@ -950,30 +952,30 @@ document objects, and returns -1 if the first document comes first in order, 1 if the second document comes first, or 0 if neither document comes before the other. This is a Minimongo extension to MongoDB. -

Field Specifiers

+

Projection Specifiers

Queries can specify a particular set of fields to include or exclude from the -result object. +result object using the `projection` option. -To exclude specific fields from the result objects, the field specifier is a +To exclude specific fields from the result objects, the projection specifier is a dictionary whose keys are field names and whose values are `0`. All unspecified fields are included. ```js -Users.find({}, { fields: { password: 0, hash: 0 } }); +Users.find({}, { projection: { password: 0, hash: 0 } }); ``` To include only specific fields in the result documents, use `1` as the value. The `_id` field is still included in the result. ```js -Users.find({}, { fields: { firstname: 1, lastname: 1 } }); +Users.find({}, { projection: { firstname: 1, lastname: 1 } }); ``` With one exception, it is not possible to mix inclusion and exclusion styles: the keys must either be all 1 or all 0. The exception is that you may specify `_id: 0` in an inclusion specifier, which will leave `_id` out of the result -object as well. However, such field specifiers can not be used with +object as well. However, such projection specifiers can not be used with [`observeChanges`](#observe_changes), [`observe`](#observe), cursors returned from a [publish function](#meteor_publish), or cursors used in `{% raw %}{{#each}}{% endraw %}` in a template. They may be used with [`fetch`](#fetch), @@ -994,10 +996,12 @@ Users.insert({ name: 'Yagami Light', }); -Users.findOne({}, { fields: { 'alterEgos.name': 1, _id: 0 } }); +Users.findOne({}, { projection: { 'alterEgos.name': 1, _id: 0 } }); // Returns { alterEgos: [{ name: 'Kira' }, { name: 'L' }] } ``` +> Note: The `fields` option is deprecated in favor of `projection`, which is the standard term used by MongoDB. Using `projection` ensures compatibility with MongoDB's documentation and drivers. + See the MongoDB docs for details of the nested field rules and array behavior.