From 5d80ac5780b492b919a2e46eb7f823c95c54b5cf Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Fri, 5 Jun 2020 11:08:28 -0400 Subject: [PATCH 01/11] fix typo --- .../tutorials/ruby-driver-crud-operations.txt | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index eb8d617975..1a27fec58f 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -521,7 +521,7 @@ In driver versions 2.9 and below, client, collection and GridFS objects took write concern options in the ``:write`` option with session and transaction objects employing the ``:write_concern`` option. -Below are some examples of passing write concerns to client and colection +Below are some examples of passing write concerns to client and collection objects. The ``:write_concern`` option can be provided when constructing new client and collection objects, or to the ``#with`` methods. @@ -532,10 +532,10 @@ GridFS examples are provided on the :ref:`GridFS ` page. client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) alt_client = client.with(write_concern: {w: :majority}) - + collection = client[:artists, write_concern: {w: 3}] alt_collection = collection.with(write_concern: {w: :majority}) - + # Uses w: 3 collection.insert_one({name: 'SUN Project'}) # Uses w: :majority @@ -550,7 +550,7 @@ backwards compatibility, but is deprecated: client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write: {w: 2}) alt_client = client.with(write: {w: :majority}) - + collection = client[:artists, write: {w: 3}] alt_collection = collection.with(write: {w: :majority}) @@ -562,7 +562,7 @@ values must be identical or an exception will be raised: # OK client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 3}, write: {w: 3}) - + # Error client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 3}, write: {w: :majority}) @@ -575,10 +575,10 @@ the last provided option wins in case of naming differences: client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) alt_client = client.with(write: {w: 3}) - + alt_client.options[:write] # => {"w"=>3} - + alt_client.options[:write_concern] # => nil @@ -596,34 +596,34 @@ transaction option, the ``:write`` option is not recognized by any driver version. .. code-block:: ruby - + client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) collection = client[:artists, write_concern: {w: :majority}] - - + + session = client.start_session session.with_transaction do collection.insert_one({test: 1}, session: session) - + # Uses w: 2 when committing end - - + + session = client.start_session(default_transaction_options: {write_concern: {w: 3}) ) session.with_transaction do collection.insert_one({test: 1}, session: session) - + # Uses w: 3 when committing end - - + + session = client.start_session session.with_transaction(write_concern: {w: 3}) do collection.insert_one({test: 1}, session: session) - + # Uses w: 3 when committing end @@ -632,36 +632,36 @@ write concern hash rather than individual elements. For example, ``j: true`` is not inherited in the following case: .. code-block:: ruby - + client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 1, j: true}) collection = client[:artists, write_concern: {w: 2}] - + collection.write_concern.options # => #2}> Although CRUD operations accept an options hash, they currently do not recognize the ``:write_concern`` option: - + .. code-block:: ruby client = Mongo::Client.new([ '127.0.0.1:27017' ], database: 'music', write_concern: {w: 2}) collection = client[:artists, write_concern: {w: :majority}] - + # Still uses w: :majority collection.insert_one({name: 'SUN Project'}, write_concern: {w: 1}) The easiest workaround for this is to use ``#with`` to obtain a new collection instance with the desired write concern: - + .. code-block:: ruby # Uses w: 1 collection.with(write_concern: {w: 1}).insert_one(name: 'SUN Project') Write concern can also be manually specified in ``Database#command``: - + .. code-block:: ruby client.database.command(create: 'foo-collection', writeConcern: {w: :majority}) @@ -673,7 +673,7 @@ underscore one that Ruby driver uses. A Note about the BSON Symbol type ================================= -Because the BSON specification deprecated the BSON symbol type, the `bson` gem +Because the BSON specification deprecated the BSON symbol type, the `bson` gem will serialize Ruby symbols into BSON strings when used on its own. However, in order to maintain backwards compatibility with older datasets, the Ruby driver overrides this behavior to serialize Ruby symbols as BSON symbols. This is From 190451e284eb37a28c5fea408a8a66e50945a994 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 10:40:45 -0400 Subject: [PATCH 02/11] add hint option to API docs --- lib/mongo/collection/view/writable.rb | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/lib/mongo/collection/view/writable.rb b/lib/mongo/collection/view/writable.rb index 85c3fda3be..e55cd0e6b4 100644 --- a/lib/mongo/collection/view/writable.rb +++ b/lib/mongo/collection/view/writable.rb @@ -41,6 +41,8 @@ module Writable # will be sorted. # @option opts [ Hash ] :collation The collation to use. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document, nil ] The document, if found. # @@ -84,6 +86,8 @@ def find_one_and_delete(opts = {}) # @option opts [ true, false ] :bypass_document_validation Whether or # not to skip document level validation. # @option opts [ Hash ] :collation The collation to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document ] The document. # @@ -113,6 +117,8 @@ def find_one_and_replace(replacement, opts = {}) # @option opts [ Array ] :array_filters A set of filters specifying to which array elements # an update should apply. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document ] The document. # @@ -157,6 +163,8 @@ def find_one_and_update(document, opts = {}) # # @option opts [ Hash ] :collation The collation to use. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -189,6 +197,8 @@ def delete_many(opts = {}) # # @option opts [ Hash ] :collation The collation to use. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -227,6 +237,8 @@ def delete_one(opts = {}) # not to skip document level validation. # @option opts [ Hash ] :collation The collation to use. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -274,6 +286,8 @@ def replace_one(replacement, opts = {}) # @option opts [ Array ] :array_filters A set of filters specifying to # which array elements an update should apply. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -321,6 +335,8 @@ def update_many(spec, opts = {}) # @option opts [ Array ] :array_filters A set of filters specifying to # which array elements an update should apply. # @option opts [ Session ] :session The session to use. + # @option opts [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # From c051882a4163340ce49ff5f6f3bac9fef9d7e444 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 10:59:53 -0400 Subject: [PATCH 03/11] add a documentation section for delete options --- .../tutorials/ruby-driver-crud-operations.txt | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 1a27fec58f..8de0609c98 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -499,6 +499,42 @@ Deleting result = artists.delete_many(:label => 'Mute') result.deleted_count # Returns the number deleted. +Delete options +-------------- + +To add options to a delete command, specify them as key value pairs in the +options Hash. + +.. code-block:: ruby + + client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') + artists = client[:artists] + + # Use the _id index to perform this operation + result = artists.find(:name => 'Björk').delete_one(hint: { _id: 1 }) + result.deleted_count # Returns 1. + + result = artists.delete_one({ name: 'Björk' }, { hint: { _id: 1 } }) + result.deleted_count # Returns 1. + +The following is a full list of the available options that can be added +to ``delete_one`` and ``delete_many`` operations. + +.. list-table:: + :header-rows: 1 + :widths: 40 80 + + * - Option + - Description + * - ``collation`` + - Specifies a set of rules to use when comparing strings complying with the + conventions of a particular language. + * - ``session`` + - The session to use for this operation. + * - ``hint`` + - The index to use for this operation. May be specified as a Hash + (e.g. { _id: 1 }) or as a String (e.g. "_id_"). + .. _write-concern: Write Concern From 20fc7096d5c003960f57080dce021d88f0c28c77 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 11:53:59 -0400 Subject: [PATCH 04/11] added hint to API docs in collection methods --- lib/mongo/collection.rb | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/lib/mongo/collection.rb b/lib/mongo/collection.rb index bf2d29377c..abc415393e 100644 --- a/lib/mongo/collection.rb +++ b/lib/mongo/collection.rb @@ -605,6 +605,8 @@ def bulk_write(requests, options = {}) # # @option options [ Hash ] :collation The collation to use. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -623,6 +625,8 @@ def delete_one(filter = nil, options = {}) # # @option options [ Hash ] :collation The collation to use. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -669,6 +673,8 @@ def parallel_scan(cursor_count, options = {}) # not to skip document level validation. # @option options [ Hash ] :collation The collation to use. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -694,6 +700,8 @@ def replace_one(filter, replacement, options = {}) # @option options [ Array ] :array_filters A set of filters specifying to which array elements # an update should apply. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -719,6 +727,8 @@ def update_many(filter, update, options = {}) # @option options [ Array ] :array_filters A set of filters specifying to which array elements # an update should apply. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ Result ] The response from the database. # @@ -745,6 +755,8 @@ def update_one(filter, update, options = {}) # Defaults to the collection's write concern. # @option options [ Hash ] :collation The collation to use. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document, nil ] The document, if found. # @@ -781,6 +793,8 @@ def find_one_and_delete(filter, options = {}) # @option options [ Array ] :array_filters A set of filters specifying to which array elements # an update should apply. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document ] The document. # @@ -815,6 +829,8 @@ def find_one_and_update(filter, update, options = {}) # Defaults to the collection's write concern. # @option options [ Hash ] :collation The collation to use. # @option options [ Session ] :session The session to use. + # @option options [ Hash | String ] :hint The index to use for this operation. + # May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_"). # # @return [ BSON::Document ] The document. # From e07bb67669079dbad6bc236e470456dd8ba82f23 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 12:07:29 -0400 Subject: [PATCH 05/11] write hint documentation --- .../tutorials/ruby-driver-crud-operations.txt | 78 ++++++++++++++++++- 1 file changed, 74 insertions(+), 4 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 8de0609c98..eb9f1cdb1c 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -473,6 +473,73 @@ the modification occurs. ) doc # Return the document after the update. +Update Options +-------------- + +To add options to an update command, specify them as key value pairs in the options +Hash argument. + +.. code-block:: ruby + + client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') + artists = client[:artists] + + # Use the _id index to perform this operation + result = artists.find(:name => 'Goldie').update_one( + { "$inc" => { :plays => 1 } }, + { hint: { _id: 1 } } + ) + result.n # Returns 1. + + result = artists.update_one( + { :name => 'Goldie' }, + { "$inc" => { :plays => 1 } }, + { hint: { _id: 1 } } + ) + result.n # Returns 1. + +The following is a list of the options that can be added to update operations, +including ``update_one``, ``update_many``, ``replace_one``, +``find_one_and_delete``, ``find_one_and_update``, and ``find_one_and_replace``. + +.. list-table:: + :header-rows: 1 + :widths: 40 80 + + * - Option + - Description + * - ``array_filters`` + - An Array of filter documents that determine which array elements to modify + for an update operation on an array field. + * - ``bypass_document_validation`` + - Whether to skip document-level validation before writing the document. + * - ``collation`` + - Specifies a set of rules to use when comparing strings complying with the + conventions of a particular language. + * - ``hint`` + - The index to use for this operation. May be specified as a Hash + (e.g. { _id: 1 }) or as a String (e.g. "_id_"). + * - ``projection`` + - The fields to exclude or include in the operation result (only available + on ``find_one_and_delete``, ``find_one_and_replace``, and + ``find_one_and_update`` commands). + * - ``sort`` + - How to sort the results of a findAndModify command. Specified as a Hash + key value pair, where the key is the name of the field to sort by, and + the value is either 1 or -1, specifying a sort in ascending or descending + order (only available on ``find_one_and_delete``, ``find_one_and_replace``, + and ``find_one_and_update`` commands). + * - ``session`` + - The session to use for this operation. + * - ``upsert`` + - Whether to upsert if the document doesn't exist. Cannot be used on + ``find_one_and_delete`` operation. + +For more information about update options, see the MongoDB server documentation +on the following commands: +- :manual:`update ` +- :manual:`findAndModify ` + Deleting ======== @@ -499,11 +566,11 @@ Deleting result = artists.delete_many(:label => 'Mute') result.deleted_count # Returns the number deleted. -Delete options +Delete Options -------------- To add options to a delete command, specify them as key value pairs in the -options Hash. +options Hash argument. .. code-block:: ruby @@ -529,11 +596,14 @@ to ``delete_one`` and ``delete_many`` operations. * - ``collation`` - Specifies a set of rules to use when comparing strings complying with the conventions of a particular language. - * - ``session`` - - The session to use for this operation. * - ``hint`` - The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or as a String (e.g. "_id_"). + * - ``session`` + - The session to use for this operation. + +For more information about update options, see the MongoDB server documentation +on the :manual:`delete command. ` .. _write-concern: From dedcdff397d201609110e698019314afcbb0c9f3 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 12:14:52 -0400 Subject: [PATCH 06/11] fix update section --- .../tutorials/ruby-driver-crud-operations.txt | 24 ++----------------- 1 file changed, 2 insertions(+), 22 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index eb9f1cdb1c..63f8a76f3d 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -458,23 +458,8 @@ the modification occurs. doc = artists.find_one_and_update( { :name => 'José James' }, { '$set' => { :name => 'José' } } ) doc # Return the document before the update. -``find_one_and_replace`` - -.. code-block:: ruby - - doc = artists.find(:name => 'José James'). - find_one_and_replace( { '$set' => { :name => 'José' } }, :return_document => :after ) - doc # Return the document after the update. - - doc = artists.find_one_and_replace( - { :name => 'José James' }, - { '$set' => { :name => 'José' } }, - :return_document => :after - ) - doc # Return the document after the update. - Update Options --------------- +`````````````` To add options to an update command, specify them as key value pairs in the options Hash argument. @@ -485,12 +470,6 @@ Hash argument. artists = client[:artists] # Use the _id index to perform this operation - result = artists.find(:name => 'Goldie').update_one( - { "$inc" => { :plays => 1 } }, - { hint: { _id: 1 } } - ) - result.n # Returns 1. - result = artists.update_one( { :name => 'Goldie' }, { "$inc" => { :plays => 1 } }, @@ -537,6 +516,7 @@ including ``update_one``, ``update_many``, ``replace_one``, For more information about update options, see the MongoDB server documentation on the following commands: + - :manual:`update ` - :manual:`findAndModify ` From a3358ce8699419202d5b8d76bfe58053937cd035 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 12:23:43 -0400 Subject: [PATCH 07/11] try to fix headings --- docs/tutorials/ruby-driver-crud-operations.txt | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 63f8a76f3d..2b9258c427 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -166,7 +166,7 @@ notation. .. _ruby-driver-query-options: Query Options -~~~~~~~~~~~~~ +------------- To add options to a query, chain the appropriate methods after the ``find`` method. Note that the underlying object, the ``Mongo::Collection::View``, @@ -459,7 +459,7 @@ the modification occurs. doc # Return the document before the update. Update Options -`````````````` +-------------- To add options to an update command, specify them as key value pairs in the options Hash argument. @@ -561,9 +561,6 @@ options Hash argument. result = artists.find(:name => 'Björk').delete_one(hint: { _id: 1 }) result.deleted_count # Returns 1. - result = artists.delete_one({ name: 'Björk' }, { hint: { _id: 1 } }) - result.deleted_count # Returns 1. - The following is a full list of the available options that can be added to ``delete_one`` and ``delete_many`` operations. From 323ca15dbdb07717e217847cd922597252fcaa84 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 12:25:16 -0400 Subject: [PATCH 08/11] actually fix headings --- docs/tutorials/ruby-driver-crud-operations.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 2b9258c427..154f0e7dc7 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -166,7 +166,7 @@ notation. .. _ruby-driver-query-options: Query Options -------------- +~~~~~~~~~~~~~ To add options to a query, chain the appropriate methods after the ``find`` method. Note that the underlying object, the ``Mongo::Collection::View``, @@ -459,7 +459,7 @@ the modification occurs. doc # Return the document before the update. Update Options --------------- +~~~~~~~~~~~~~~ To add options to an update command, specify them as key value pairs in the options Hash argument. @@ -547,7 +547,7 @@ Deleting result.deleted_count # Returns the number deleted. Delete Options --------------- +~~~~~~~~~~~~~~ To add options to a delete command, specify them as key value pairs in the options Hash argument. From 9e6a5e50bf94ba749d41f194b558bd5be00dd51b Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 12:32:18 -0400 Subject: [PATCH 09/11] add information about which server versions support hints --- docs/tutorials/ruby-driver-crud-operations.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 154f0e7dc7..ca96a9a15f 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -497,7 +497,10 @@ including ``update_one``, ``update_many``, ``replace_one``, conventions of a particular language. * - ``hint`` - The index to use for this operation. May be specified as a Hash - (e.g. { _id: 1 }) or as a String (e.g. "_id_"). + (e.g. { _id: 1 }) or as a String (e.g. "_id_"). Supported on MongoDB + server versions 4.2 and newer for ``update_one``, ``update_many``, and + ``replace_one`` commands, and on server versions 4.4 and newer for all + findAndModify commands. * - ``projection`` - The fields to exclude or include in the operation result (only available on ``find_one_and_delete``, ``find_one_and_replace``, and @@ -575,7 +578,8 @@ to ``delete_one`` and ``delete_many`` operations. conventions of a particular language. * - ``hint`` - The index to use for this operation. May be specified as a Hash - (e.g. { _id: 1 }) or as a String (e.g. "_id_"). + (e.g. { _id: 1 }) or as a String (e.g. "_id_"). Supported on MongoDB + server versions 4.4 and newer. * - ``session`` - The session to use for this operation. From 7fdeac85169496fd0a3339778165f4f548f143db Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 14:30:21 -0400 Subject: [PATCH 10/11] add return_document info and key value --> key-value --- docs/tutorials/ruby-driver-crud-operations.txt | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index ca96a9a15f..7367cec24a 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -461,7 +461,7 @@ the modification occurs. Update Options ~~~~~~~~~~~~~~ -To add options to an update command, specify them as key value pairs in the options +To add options to an update command, specify them as key-value pairs in the options Hash argument. .. code-block:: ruby @@ -505,9 +505,13 @@ including ``update_one``, ``update_many``, ``replace_one``, - The fields to exclude or include in the operation result (only available on ``find_one_and_delete``, ``find_one_and_replace``, and ``find_one_and_update`` commands). + * - ``return_document`` + - A symbol specifying whether to return the updated document as it was before or + after the update. Potential values are ``:before`` or ``:after``. + (Only available on ``find_one_and_update`` and ``find_one_and_replace`` commands). * - ``sort`` - How to sort the results of a findAndModify command. Specified as a Hash - key value pair, where the key is the name of the field to sort by, and + key-value pair, where the key is the name of the field to sort by, and the value is either 1 or -1, specifying a sort in ascending or descending order (only available on ``find_one_and_delete``, ``find_one_and_replace``, and ``find_one_and_update`` commands). @@ -552,7 +556,7 @@ Deleting Delete Options ~~~~~~~~~~~~~~ -To add options to a delete command, specify them as key value pairs in the +To add options to a delete command, specify them as key-value pairs in the options Hash argument. .. code-block:: ruby From 6632d8dd59c13a9e60b181d7f8824322f8e1ef08 Mon Sep 17 00:00:00 2001 From: Emily Giurleo Date: Mon, 8 Jun 2020 16:49:10 -0400 Subject: [PATCH 11/11] make hint examples clearer --- .../tutorials/ruby-driver-crud-operations.txt | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 7367cec24a..77f6615224 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -469,11 +469,13 @@ Hash argument. client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] - # Use the _id index to perform this operation + artists.indexes.create_one(name: 1) + + # Force the server to use the name index to perform this operation result = artists.update_one( { :name => 'Goldie' }, { "$inc" => { :plays => 1 } }, - { hint: { _id: 1 } } + { hint: { name: 1 } } ) result.n # Returns 1. @@ -499,8 +501,9 @@ including ``update_one``, ``update_many``, ``replace_one``, - The index to use for this operation. May be specified as a Hash (e.g. { _id: 1 }) or as a String (e.g. "_id_"). Supported on MongoDB server versions 4.2 and newer for ``update_one``, ``update_many``, and - ``replace_one`` commands, and on server versions 4.4 and newer for all - findAndModify commands. + ``replace_one`` commands, and on server versions 4.4 and newer for + ``find_one_and_delete``, ``find_one_and_update``, and ``find_one_and_replace`` + commands. * - ``projection`` - The fields to exclude or include in the operation result (only available on ``find_one_and_delete``, ``find_one_and_replace``, and @@ -510,7 +513,7 @@ including ``update_one``, ``update_many``, ``replace_one``, after the update. Potential values are ``:before`` or ``:after``. (Only available on ``find_one_and_update`` and ``find_one_and_replace`` commands). * - ``sort`` - - How to sort the results of a findAndModify command. Specified as a Hash + - How to sort the results of a find and modify command. Specified as a Hash key-value pair, where the key is the name of the field to sort by, and the value is either 1 or -1, specifying a sort in ascending or descending order (only available on ``find_one_and_delete``, ``find_one_and_replace``, @@ -564,8 +567,10 @@ options Hash argument. client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'music') artists = client[:artists] - # Use the _id index to perform this operation - result = artists.find(:name => 'Björk').delete_one(hint: { _id: 1 }) + artists.indexes.create_one(name: 1) + + # Force the server to use the name index to perform this operation + result = artists.find(:name => 'Björk').delete_one(hint: { name: 1 }) result.deleted_count # Returns 1. The following is a full list of the available options that can be added