Skip to content

Commit 31ef665

Browse files
norareidynorareidy
committed
Merge remote-tracking branch 'upstream/standardization' into DOCSP-45196-return-docs
2 parents 6e2f6f2 + a1238e5 commit 31ef665

File tree

5 files changed

+277
-6
lines changed

5 files changed

+277
-6
lines changed

‎source/includes/read/project.rb

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# Access database and collection
12+
# start-db-coll
13+
database = client.use('sample_restaurants')
14+
collection = database[:restaurants]
15+
# end-db-coll
16+
17+
# Retrieves documents matching the "name" field query
18+
# and projects their "name", "cuisine", and "borough" values
19+
# start-project-include
20+
opts = { projection: { name: 1, cuisine: 1, borough: 1 } }
21+
collection.find({ name: 'Emerald Pub' }, opts).each do |doc|
22+
puts doc
23+
end
24+
# end-project-include
25+
26+
# Retrieves documents matching the "name" field query
27+
# and projects their "name", "cuisine", and "borough" values while excluding the "_id" values
28+
# start-project-include-without-id
29+
opts = { projection: { name: 1, cuisine: 1, borough: 1, _id: 0 } }
30+
collection.find({ name: 'Emerald Pub' }, opts).each do |doc|
31+
puts doc
32+
end
33+
# end-project-include-without-id
34+
35+
# Retrieves documents matching the "name" field query
36+
# and excludes their "grades" and "address" values when printing
37+
# start-project-exclude
38+
opts = { projection: { grades: 0, address: 0 } }
39+
collection.find({ name: 'Emerald Pub' }, opts).each do |doc|
40+
puts doc
41+
end
42+
# end-project-exclude
43+
end

‎source/index.txt

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
Indexes </indexes>
2020
View the Source <https://github.com/mongodb/mongo-ruby-driver>
2121
API Documentation <{+api-root+}>
22+
What's New </whats-new>
2223
Compatibility </compatibility>
2324

2425
.. TODO:
@@ -29,7 +30,6 @@
2930
Data Aggregation </aggregation>
3031
Security </security>
3132
Issues & Help </issues-and-help>
32-
What's New </whats-new>
3333
Upgrade </upgrade>
3434

3535
Introduction
@@ -90,11 +90,11 @@ working with data in the :ref:`ruby-get-started` tutorial.
9090
.. Learn how to authenticate your application and encrypt your data in the
9191
.. :ref:`ruby-security` section.
9292

93-
.. What's New
94-
.. ----------
93+
What's New
94+
----------
9595

96-
.. For a list of new features and changes in each version, see the :ref:`What's New <ruby-whats-new>`
97-
.. section.
96+
For a list of new features and changes in each version, see the :ref:`What's New <ruby-whats-new>`
97+
section.
9898

9999
.. Upgrade Driver Versions
100100
.. -----------------------

‎source/read.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,4 +23,5 @@ Read Data from MongoDB
2323
:maxdepth: 1
2424

2525
Retrieve Data </read/retrieve>
26-
Specify Documents to Return </read/specify-documents-to-return>
26+
Specify Documents to Return </read/specify-documents-to-return>
27+
Specify Fields to Return </read/project>

‎source/read/project.txt

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
.. _ruby-project:
2+
3+
========================
4+
Specify Fields To Return
5+
========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: read, filter, project, select, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the {+driver-short+} to specify which fields
24+
to return from a read operation by using a **projection**. A projection is a document
25+
that specifies which fields MongoDB returns from a query.
26+
27+
Sample Data
28+
~~~~~~~~~~~
29+
30+
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
31+
database from the :atlas:`Atlas sample datasets </sample-data>`. To access this collection
32+
from your {+language+} application, create a ``Mongo::Client`` object that connects to
33+
an Atlas cluster and assign the following values to your ``database`` and ``collection``
34+
variables:
35+
36+
.. literalinclude:: /includes/read/project.rb
37+
:language: ruby
38+
:dedent:
39+
:start-after: start-db-coll
40+
:end-before: end-db-coll
41+
42+
To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the
43+
:atlas:`Get Started with Atlas </getting-started>` guide.
44+
45+
Projection Types
46+
----------------
47+
48+
You can use a projection to specify which fields to include or exclude in
49+
a return Document. You cannot combine inclusion and exclusion statements in
50+
a single projection, unless you are excluding the ``_id`` field.
51+
52+
Specify Fields to Include
53+
~~~~~~~~~~~~~~~~~~~~~~~~~
54+
55+
To include specific fields in a read operation result, specify the ``projection``
56+
option in a parameter to the ``find`` method. To set this option, use the following syntax:
57+
58+
.. code-block:: ruby
59+
60+
{ projection: { <field_name>: 1 } }
61+
62+
The following example uses the ``find`` method to find all restaurants in which the ``name``
63+
field value is ``'Emerald Pub'``. Then, the code specifies the ``projection`` option
64+
to instruct the find operation to return only the ``name``, ``cuisine``, and ``borough`` fields
65+
of matching documents:
66+
67+
.. io-code-block::
68+
:copyable:
69+
70+
.. input:: /includes/read/project.rb
71+
:start-after: start-project-include
72+
:end-before: end-project-include
73+
:language: ruby
74+
:dedent:
75+
76+
.. output::
77+
:visible: false
78+
79+
{"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"}
80+
{"_id"=>BSON::ObjectId('...'), "borough"=>"Queens", "cuisine"=>"American", "name"=>"Emerald Pub"}
81+
82+
When you use a projection to specify fields to include in the return
83+
document, the ``_id`` field is also included by default. All other fields are
84+
implicitly excluded. To remove the ``_id`` field from the return
85+
document, you must :ref:`explicitly exclude it <ruby-project-remove-id>`.
86+
87+
.. _ruby-project-remove-id:
88+
89+
Exclude the ``_id`` Field
90+
~~~~~~~~~~~~~~~~~~~~~~~~~
91+
92+
When specifying fields to include, you can also exclude the ``_id`` field from
93+
the returned document.
94+
95+
The following example performs the same query as the preceding example but
96+
excludes the ``_id`` field from the projection:
97+
98+
.. io-code-block::
99+
:copyable:
100+
101+
.. input:: /includes/read/project.rb
102+
:start-after: start-project-include-without-id
103+
:end-before: end-project-include-without-id
104+
:language: ruby
105+
:dedent:
106+
107+
.. output::
108+
:visible: false
109+
110+
{"borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"}
111+
{"borough"=>"Queens", "cuisine"=>"American", "name"=>"Emerald Pub"}
112+
113+
Specify Fields to Exclude
114+
~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+
To exclude specific fields from a read operation result, specify the ``projection``
117+
option in a parameter to the ``find`` method. To set this option, use the
118+
following syntax:
119+
120+
.. code-block:: ruby
121+
122+
{ projection: { <field_name>: 0 } }
123+
124+
The following example uses the ``find`` method to find all restaurants in which the ``name``
125+
field value is ``'Emerald Pub'``. Then, the code uses the ``projection`` option
126+
to instruct the find operation to omit the ``grades`` and ``address`` fields
127+
in the result:
128+
129+
.. io-code-block::
130+
:copyable:
131+
132+
.. input:: /includes/read/project.rb
133+
:start-after: start-project-exclude
134+
:end-before: end-project-exclude
135+
:language: ruby
136+
:dedent:
137+
138+
.. output::
139+
:visible: false
140+
141+
{"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American",
142+
"name"=>"Emerald Pub", "restaurant_id"=>"40367329"}
143+
{"_id"=>BSON::ObjectId('...'), "borough"=>"Queens", "cuisine"=>"American",
144+
"name"=>"Emerald Pub", "restaurant_id"=>"40668598"}
145+
146+
When you use a projection to specify which fields to exclude,
147+
any unspecified fields are implicitly included in the return document.
148+
149+
Additional Information
150+
----------------------
151+
152+
To learn more about projections, see the :manual:`Project Fields
153+
</tutorial/project-fields-from-query-results/>` guide in the {+mdb-server+} manual.
154+
155+
API Documentation
156+
~~~~~~~~~~~~~~~~~
157+
158+
To learn more about the ``find`` method, see the `API documentation.
159+
<{+api-root+}/Mongo/Collection.html#find-instance_method>`__

‎source/whats-new.txt

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. _ruby-whats-new:
2+
3+
==========
4+
What's New
5+
==========
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: update, new feature, deprecation, upgrade
19+
20+
Learn what's new in:
21+
22+
* :ref:`2.21 <version-2.21>`
23+
* :ref:`2.20 <version-2.20>`
24+
25+
.. _upcoming-breaking-changes:
26+
27+
.. _version-2.21:
28+
29+
What's New in 2.21
30+
------------------
31+
32+
The {+driver-short+} 2.21 release includes the following new features:
33+
34+
- Supports the Client-Side Operations Timeout (CSOT) feature, which unifies
35+
most timeout-related options under a single ``timeout_ms`` option.
36+
- Supports {+mdb-server+} version 8.0.
37+
- Support for range v2 queries with Queryable Encryption, including a new ``trim_factor``
38+
parameter. For more information about Queryable Encryption, see :manual:`Queryable Encryption </core/queryable-encryption>`
39+
in the {+mdb-server+} manual.
40+
41+
To learn more about this release, see the
42+
:github:`v2.21 Release Notes <mongodb/mongo-ruby-driver/releases/tag/v2.21.0>` on
43+
GitHub.
44+
45+
.. _version-2.20:
46+
47+
What's New in 2.20
48+
------------------
49+
50+
The {+driver-short+} 2.20 release includes the following new features:
51+
52+
- Discontinues support for Ruby 2.5 and 2.6. Deprecates support for Ruby 2.7 and
53+
JRuby 9.2, which will be discontinued in the next minor driver version. Adds
54+
support for JRuby 9.4.
55+
- Supports the newly-released Ruby-BSON version 5.0.
56+
- Allows connection strings without a slash between the hosts and the options.
57+
For example, ``mongodb://example.com?w=1`` and ``mongodb://example.com/?w=1`` are
58+
both valid connection strings now.
59+
- Sends container runtime and orchestration metadata for the client environment
60+
to the server for analytics purposes.
61+
- Writes a warning message to the log when detecting the host as a CosmosDB
62+
(Azure) or DocumentDB (Amazon) instance.
63+
- Attempts retries of read or write operations on a different ``mongos``
64+
instance in a sharded topology, if possible.
65+
66+
To learn more about this release, see the
67+
:github:`v2.20 Release Notes <mongodb/mongo-ruby-driver/releases/tag/v2.20.0>` on
68+
GitHub.

0 commit comments

Comments
 (0)