Skip to content

Commit a1238e5

Browse files
norareidynorareidy
authored
DOCSP-45195: Project fields (#105)
* DOCSP-45195: Project fields * edits * SA feedback
1 parent 38eb583 commit a1238e5

File tree

3 files changed

+204
-1
lines changed

3 files changed

+204
-1
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/read.txt

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

25-
Retrieve Data </read/retrieve>
25+
Retrieve Data </read/retrieve>
26+
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>`__

0 commit comments

Comments
 (0)