From 96d5b2da1456345f7cc1c5f68b6cd8ed8f2e6d39 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Dec 2024 11:37:03 -0500 Subject: [PATCH 1/3] DOCSP-45195: Project fields --- source/includes/read/project.rb | 43 +++++++++ source/read.txt | 3 +- source/read/project.txt | 160 ++++++++++++++++++++++++++++++++ 3 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 source/includes/read/project.rb create mode 100644 source/read/project.txt diff --git a/source/includes/read/project.rb b/source/includes/read/project.rb new file mode 100644 index 00000000..517bfcb4 --- /dev/null +++ b/source/includes/read/project.rb @@ -0,0 +1,43 @@ +require 'bundler/inline' + +gemfile do + source 'https://rubygems.org' + gem 'mongo' +end + +uri = '' + +Mongo::Client.new(uri) do |client| + # Access database and collection + # start-db-coll + database = client.database + collection = client[:restaurants] + # end-db-coll + + # Retrieves documents matching the "name" field query + # and projects their "name", "cuisine", and "borough" values + # start-project-include + opts = { projection: { name: 1, cuisine: 1, borough: 1 } } + collection.find({ name: 'Emerald Pub' }, opts).each do |doc| + puts doc + end + # end-project-include + + # Retrieves documents matching the "name" field query + # and projects their "name", "cuisine", and "borough" values while excluding the "_id" values + # start-project-include-without-id + opts = { projection: { name: 1, cuisine: 1, borough: 1, _id: 0 } } + collection.find({ name: 'Emerald Pub' }, opts).each do |doc| + puts doc + end + # end-project-include-without-id + + # Retrieves documents matching the "name" field query + # and excludes their "grades" and "address" values when printing + # start-project-exclude + opts = { projection: { grades: 0, address: 0 } } + collection.find({ name: 'Emerald Pub' }, opts).each do |doc| + puts doc + end + # end-project-exclude + end \ No newline at end of file diff --git a/source/read.txt b/source/read.txt index e9822bf6..b9f5ba1a 100644 --- a/source/read.txt +++ b/source/read.txt @@ -22,4 +22,5 @@ Read Data from MongoDB :titlesonly: :maxdepth: 1 - Retrieve Data \ No newline at end of file + Retrieve Data + Specify Fields to Return \ No newline at end of file diff --git a/source/read/project.txt b/source/read/project.txt new file mode 100644 index 00000000..8291bd53 --- /dev/null +++ b/source/read/project.txt @@ -0,0 +1,160 @@ +.. _ruby-project: + +======================== +Specify Fields To Return +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: read, filter, project, select, code example + +Overview +-------- + +In this guide, you can learn how to use the {+driver-short+} to specify which fields +to return from a read operation by using a **projection**. A projection is a document +that specifies which fields MongoDB returns from a query. + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` +database from the :atlas:`Atlas sample datasets `. To access this collection +from your {+language+} application, create a ``Mongo::Client`` object that connects to +an Atlas cluster and assign the following values to your ``database`` and ``collection`` +variables: + +.. literalinclude:: /includes/read/project.rb + :language: ruby + :dedent: + :start-after: start-db-coll + :end-before: end-db-coll + +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. + +Projection Types +---------------- + +You can use a projection to specify which fields to include in a return +document, or to specify which fields to exclude. You cannot combine inclusion and +exclusion statements in a single projection, unless you are excluding the +``_id`` field. + +Specify Fields to Include +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the fields to include in the result, specify the ``projection`` +option in a parameter to the ``find`` method. To set this option, use the following syntax: + +.. code-block:: ruby + + { projection: { : 1 } } + +The following example uses the ``find`` method to find all restaurants in which the ``name`` +field value is ``'Emerald Pub'``. Then, the code specifies the ``projection`` option +to instruct the find operation to return only the ``name``, ``cuisine``, and ``borough`` fields +of matching documents: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/project.rb + :start-after: start-project-include + :end-before: end-project-include + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id": {"$oid": "..."}, "borough": "Manhattan", "cuisine": "American", "name": "Emerald Pub"} + {"_id": {"$oid": "..."}, "borough": "Queens", "cuisine": "American", "name": "Emerald Pub"} + +When you use a projection to specify fields to include in the return +document, the ``_id`` field is also included by default. All other fields are +implicitly excluded. To remove the ``_id`` field from the return +document, you must :ref:`explicitly exclude it `. + +.. _ruby-project-remove-id: + +Exclude the ``_id`` Field +~~~~~~~~~~~~~~~~~~~~~~~~~ + +When specifying fields to include, you can also exclude the ``_id`` field from +the returned document. + +The following example performs the same query as the preceding example but +excludes the ``_id`` field from the projection: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/project.rb + :start-after: start-project-include-without-id + :end-before: end-project-include-without-id + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"borough": "Manhattan", "cuisine": "American", "name": "Emerald Pub"} + {"borough": "Queens", "cuisine": "American", "name": "Emerald Pub"} + +Specify Fields to Exclude +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify the fields to exclude from the result, specify the ``projection`` +option in a parameter to the ``find`` method. To set this option, use the +following syntax: + +.. code-block:: ruby + + { projection: { : 0 } } + +The following example uses the ``find`` method to find all restaurants in which the ``name`` +field value is ``'Emerald Pub'``. Then, the code uses the ``projection`` option +to instruct the find operation to omit the ``name`` and ``address`` fields +in the result: + +.. io-code-block:: + :copyable: + + .. input:: /includes/read/project.rb + :start-after: start-project-exclude + :end-before: end-project-exclude + :language: ruby + :dedent: + + .. output:: + :visible: false + + {"_id": {"$oid": "..."}, "borough": "Manhattan", "cuisine": "American", + "grades": [...], "restaurant_id": "40367329"} + {"_id": {"$oid": "..."}, "borough": "Queens", "cuisine": "American", + "grades": [...], "restaurant_id": "40668598"} + +When you use a projection to specify which fields to exclude, +any unspecified fields are implicitly included in the return document. + +Additional Information +---------------------- + +To learn more about projections, see the :manual:`Project Fields +` guide in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the ``find`` method, see the `API documentation. +<{+api-root+}/Mongo/Collection.html#find-instance_method>`__ From d9536cd08c2fb38fc6bb07adb6edd9e9653aa5d1 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Dec 2024 12:05:14 -0500 Subject: [PATCH 2/3] edits --- source/includes/read/project.rb | 4 ++-- source/read/project.txt | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/source/includes/read/project.rb b/source/includes/read/project.rb index 517bfcb4..c08ab842 100644 --- a/source/includes/read/project.rb +++ b/source/includes/read/project.rb @@ -10,8 +10,8 @@ Mongo::Client.new(uri) do |client| # Access database and collection # start-db-coll - database = client.database - collection = client[:restaurants] + database = client.use('sample_restaurants') + collection = database[:restaurants] # end-db-coll # Retrieves documents matching the "name" field query diff --git a/source/read/project.txt b/source/read/project.txt index 8291bd53..185c5172 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -77,8 +77,8 @@ of matching documents: .. output:: :visible: false - {"_id": {"$oid": "..."}, "borough": "Manhattan", "cuisine": "American", "name": "Emerald Pub"} - {"_id": {"$oid": "..."}, "borough": "Queens", "cuisine": "American", "name": "Emerald Pub"} + {"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"} + {"_id"=>BSON::ObjectId('...'), "borough"=>"Queens", "cuisine"=>"American", "name"=>"Emerald Pub"} When you use a projection to specify fields to include in the return document, the ``_id`` field is also included by default. All other fields are @@ -108,8 +108,8 @@ excludes the ``_id`` field from the projection: .. output:: :visible: false - {"borough": "Manhattan", "cuisine": "American", "name": "Emerald Pub"} - {"borough": "Queens", "cuisine": "American", "name": "Emerald Pub"} + {"borough"=>"Manhattan", "cuisine"=>"American", "name"=>"Emerald Pub"} + {"borough"=>"Queens", "cuisine"=>"American", "name"=>"Emerald Pub"} Specify Fields to Exclude ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -139,10 +139,10 @@ in the result: .. output:: :visible: false - {"_id": {"$oid": "..."}, "borough": "Manhattan", "cuisine": "American", - "grades": [...], "restaurant_id": "40367329"} - {"_id": {"$oid": "..."}, "borough": "Queens", "cuisine": "American", - "grades": [...], "restaurant_id": "40668598"} + {"_id"=>BSON::ObjectId('...'), "borough"=>"Manhattan", "cuisine"=>"American", + "name"=>"Emerald Pub", "restaurant_id"=>"40367329"} + {"_id"=>BSON::ObjectId('...'), "borough"=>"Queens", "cuisine"=>"American", + "name"=>"Emerald Pub", "restaurant_id"=>"40668598"} When you use a projection to specify which fields to exclude, any unspecified fields are implicitly included in the return document. From f325f4b86358677b5e3790b097abc04fcb7477db Mon Sep 17 00:00:00 2001 From: norareidy Date: Wed, 18 Dec 2024 10:40:12 -0500 Subject: [PATCH 3/3] SA feedback --- source/read/project.txt | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/source/read/project.txt b/source/read/project.txt index 185c5172..b9bd4896 100644 --- a/source/read/project.txt +++ b/source/read/project.txt @@ -45,15 +45,14 @@ To learn how to create a free MongoDB Atlas cluster and load the sample datasets Projection Types ---------------- -You can use a projection to specify which fields to include in a return -document, or to specify which fields to exclude. You cannot combine inclusion and -exclusion statements in a single projection, unless you are excluding the -``_id`` field. +You can use a projection to specify which fields to include or exclude in +a return Document. You cannot combine inclusion and exclusion statements in +a single projection, unless you are excluding the ``_id`` field. Specify Fields to Include ~~~~~~~~~~~~~~~~~~~~~~~~~ -To specify the fields to include in the result, specify the ``projection`` +To include specific fields in a read operation result, specify the ``projection`` option in a parameter to the ``find`` method. To set this option, use the following syntax: .. code-block:: ruby @@ -114,7 +113,7 @@ excludes the ``_id`` field from the projection: Specify Fields to Exclude ~~~~~~~~~~~~~~~~~~~~~~~~~ -To specify the fields to exclude from the result, specify the ``projection`` +To exclude specific fields from a read operation result, specify the ``projection`` option in a parameter to the ``find`` method. To set this option, use the following syntax: @@ -124,7 +123,7 @@ following syntax: The following example uses the ``find`` method to find all restaurants in which the ``name`` field value is ``'Emerald Pub'``. Then, the code uses the ``projection`` option -to instruct the find operation to omit the ``name`` and ``address`` fields +to instruct the find operation to omit the ``grades`` and ``address`` fields in the result: .. io-code-block::