RUBY-3520 Sort option for updateOne and replaceOne (#2938)

comandeo-mongo · web-flow · commit 9ce8f9049a06 · 2025-09-08T16:47:03.000+02:00
diff --git a/lib/mongo/bulk_write/transformable.rb b/lib/mongo/bulk_write/transformable.rb
@@ -99,6 +99,7 @@ module Transformable
           d['upsert'] = true if doc[:upsert]
           d[Operation::COLLATION] = doc[:collation] if doc[:collation]
           d['hint'] = doc[:hint] if doc[:hint]
+          d['sort'] = doc[:sort] if doc[:sort]
         end
       }
 
@@ -130,6 +131,7 @@ module Transformable
           d[Operation::COLLATION] = doc[:collation] if doc[:collation]
           d[Operation::ARRAY_FILTERS] = doc[:array_filters] if doc[:array_filters]
           d['hint'] = doc[:hint] if doc[:hint]
+          d['sort'] = doc[:sort] if doc[:sort]
         end
       }
 
diff --git a/lib/mongo/collection.rb b/lib/mongo/collection.rb
@@ -1049,6 +1049,11 @@ def parallel_scan(cursor_count, options = {})
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
     # @option options [ Hash ] :let Mapping of variables to use in the command.
     #   See the server documentation for details.
+    # @option options [ Hash ] :sort Specifies which document the operation
+    #   replaces if the query matches multiple documents. The first document
+    #   matched by the sort order will be replaced.
+    #   This option is only supported by servers >= 8.0. Older servers will
+    #   report an error for using this option.
     #
     # @return [ Result ] The response from the database.
     #
@@ -1115,6 +1120,11 @@ def update_many(filter, update, options = {})
     #   May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").
     # @option options [ Hash ] :let Mapping of variables to use in the command.
     #   See the server documentation for details.
+    # @option options [ Hash ] :sort Specifies which document the operation
+    #   updates if the query matches multiple documents. The first document
+    #   matched by the sort order will be updated.
+    #   This option is only supported by servers >= 8.0. Older servers will
+    #   report an error for using this option.
     #
     # @return [ Result ] The response from the database.
     #
diff --git a/lib/mongo/collection/view/writable.rb b/lib/mongo/collection/view/writable.rb
@@ -389,6 +389,11 @@ def delete_one(opts = {})
         # @option opts [ true, false ] :upsert Whether to upsert if the
         #   document doesn't exist.
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
+        # @option opts [ Hash ] :sort Specifies which document the operation
+        #   replaces if the query matches multiple documents. The first document
+        #   matched by the sort order will be replaced.
+        #   This option is only supported by servers >= 8.0. Older servers will
+        #   report an error for using this option.
         #
         # @return [ Result ] The response from the database.
         #
@@ -410,6 +415,7 @@ def replace_one(replacement, opts = {})
               Operation::U => replacement,
               hint: opts[:hint],
               collation: opts[:collation] || opts['collation'] || collation,
+              sort: opts[:sort] || opts['sort'],
             }.compact
             if opts[:upsert]
               update_doc['upsert'] = true
@@ -549,6 +555,11 @@ def update_many(spec, opts = {})
         #   document doesn't exist.
         # @option opts [ Hash ] :write_concern The write concern options.
         #   Can be :w => Integer, :fsync => Boolean, :j => Boolean.
+        # @option opts [ Hash ] :sort Specifies which document the operation
+        #   updates if the query matches multiple documents. The first document
+        #   matched by the sort order will be updated.
+        #   This option is only supported by servers >= 8.0. Older servers will
+        #   report an error for using this option.
         #
         # @return [ Result ] The response from the database.
         #
@@ -570,6 +581,7 @@ def update_one(spec, opts = {})
               Operation::U => spec,
               hint: opts[:hint],
               collation: opts[:collation] || opts['collation'] || collation,
+              sort: opts[:sort] || opts['sort'],
             }.compact
             if opts[:upsert]
               update_doc['upsert'] = true
diff --git a/spec/runners/unified/crud_operations.rb b/spec/runners/unified/crud_operations.rb
@@ -194,7 +194,8 @@ def update_one(op)
           hint: args.use('hint'),
           upsert: args.use('upsert'),
           timeout_ms: args.use('timeoutMS'),
-          max_time_ms: args.use('maxTimeMS')
+          max_time_ms: args.use('maxTimeMS'),
+          sort: args.use('sort')
         }
         if session = args.use('session')
           opts[:session] = entities.get(:session, session)
@@ -228,7 +229,8 @@ def replace_one(op)
           let: args.use('let'),
           hint: args.use('hint'),
           timeout_ms: args.use('timeoutMS'),
-          max_time_ms: args.use('maxTimeMS')
+          max_time_ms: args.use('maxTimeMS'),
+          sort: args.use('sort'),
         )
       end
     end
@@ -358,6 +360,9 @@ def convert_bulk_write_spec(spec)
       else
         raise NotImplementedError, "Unknown operation #{op}"
       end
+      if %w[ updateOne replaceOne ].include?(op)
+        out[:sort] = spec.use('sort') if spec.key?('sort')
+      end
       unless spec.empty?
         raise NotImplementedError, "Unhandled keys: #{spec}"
       end
diff --git a/spec/spec_tests/data/crud_unified/bulkWrite-replaceOne-sort.yml b/spec/spec_tests/data/crud_unified/bulkWrite-replaceOne-sort.yml
@@ -0,0 +1,94 @@
+description: BulkWrite replaceOne-sort
+
+schemaVersion: "1.0"
+
+createEntities:
+  - client:
+      id: &client0 client0
+      observeEvents: [ commandStartedEvent, commandSucceededEvent ]
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: &database0Name crud-tests
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collection0Name coll0
+
+initialData:
+  - collectionName: *collection0Name
+    databaseName: *database0Name
+    documents:
+      - { _id: 1, x: 11 }
+      - { _id: 2, x: 22 }
+      - { _id: 3, x: 33 }
+
+tests:
+  - description: BulkWrite replaceOne with sort option
+    runOnRequirements:
+      - minServerVersion: "8.0"
+    operations:
+      - object: *collection0
+        name: bulkWrite
+        arguments:
+          requests:
+            - replaceOne:
+                filter: { _id: { $gt: 1 } }
+                sort: { _id: -1 }
+                replacement: { x: 1 }
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: { x: 1 }
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+          - commandSucceededEvent:
+              reply: { ok: 1, n: 1 }
+              commandName: update
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 1 }
+
+  - description: BulkWrite replaceOne with sort option unsupported (server-side error)
+    runOnRequirements:
+      - maxServerVersion: "7.99"
+    operations:
+      - object: *collection0
+        name: bulkWrite
+        arguments:
+          requests:
+            - replaceOne:
+                filter: { _id: { $gt: 1 } }
+                sort: { _id: -1 }
+                replacement: { x: 1 }
+        expectError:
+          isClientError: false
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: { x: 1 }
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 33 }
diff --git a/spec/spec_tests/data/crud_unified/bulkWrite-updateOne-sort.yml b/spec/spec_tests/data/crud_unified/bulkWrite-updateOne-sort.yml
@@ -0,0 +1,94 @@
+description: BulkWrite updateOne-sort
+
+schemaVersion: "1.0"
+
+createEntities:
+  - client:
+      id: &client0 client0
+      observeEvents: [ commandStartedEvent, commandSucceededEvent ]
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: &database0Name crud-tests
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collection0Name coll0
+
+initialData:
+  - collectionName: *collection0Name
+    databaseName: *database0Name
+    documents:
+      - { _id: 1, x: 11 }
+      - { _id: 2, x: 22 }
+      - { _id: 3, x: 33 }
+
+tests:
+  - description: BulkWrite updateOne with sort option
+    runOnRequirements:
+      - minServerVersion: "8.0"
+    operations:
+      - object: *collection0
+        name: bulkWrite
+        arguments:
+          requests:
+            - updateOne:
+                filter: { _id: { $gt: 1 } }
+                sort: { _id: -1 }
+                update: [ $set: { x: 1 } ]
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: [ $set: { x: 1 } ]
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+          - commandSucceededEvent:
+              reply: { ok: 1, n: 1 }
+              commandName: update
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 1 }
+
+  - description: BulkWrite updateOne with sort option unsupported (server-side error)
+    runOnRequirements:
+      - maxServerVersion: "7.99"
+    operations:
+      - object: *collection0
+        name: bulkWrite
+        arguments:
+          requests:
+            - updateOne:
+                filter: { _id: { $gt: 1 } }
+                sort: { _id: -1 }
+                update: [ $set: { x: 1 } ]
+        expectError:
+          isClientError: false
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: [ $set: { x: 1 } ]
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 33 }
diff --git a/spec/spec_tests/data/crud_unified/replaceOne-sort.yml b/spec/spec_tests/data/crud_unified/replaceOne-sort.yml
@@ -0,0 +1,94 @@
+description: replaceOne-sort
+
+schemaVersion: "1.0"
+
+createEntities:
+  - client:
+      id: &client0 client0
+      observeEvents: [ commandStartedEvent, commandSucceededEvent ]
+  - database:
+      id: &database0 database0
+      client: *client0
+      databaseName: &database0Name crud-tests
+  - collection:
+      id: &collection0 collection0
+      database: *database0
+      collectionName: &collection0Name coll0
+
+initialData:
+  - collectionName: *collection0Name
+    databaseName: *database0Name
+    documents:
+      - { _id: 1, x: 11 }
+      - { _id: 2, x: 22 }
+      - { _id: 3, x: 33 }
+
+tests:
+  - description: ReplaceOne with sort option
+    runOnRequirements:
+      - minServerVersion: "8.0"
+    operations:
+      - name: replaceOne
+        object: *collection0
+        arguments:
+          filter: { _id: { $gt: 1 } }
+          sort: { _id: -1 }
+          replacement: { x: 1 }
+        expectResult:
+          matchedCount: 1
+          modifiedCount: 1
+          upsertedCount: 0
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: { x: 1 }
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+          - commandSucceededEvent:
+              reply: { ok: 1, n: 1 }
+              commandName: update
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 1 }
+
+  - description: replaceOne with sort option unsupported (server-side error)
+    runOnRequirements:
+      - maxServerVersion: "7.99"
+    operations:
+      - name: replaceOne
+        object: *collection0
+        arguments:
+          filter: { _id: { $gt: 1 } }
+          sort: { _id: -1 }
+          replacement: { x: 1 }
+        expectError:
+          isClientError: false
+    expectEvents:
+      - client: *client0
+        events:
+          - commandStartedEvent:
+              command:
+                update: *collection0Name
+                updates:
+                  - q: { _id: { $gt: 1 } }
+                    u: { x: 1 }
+                    sort: { _id: -1 }
+                    multi: { $$unsetOrMatches: false }
+                    upsert: { $$unsetOrMatches: false }
+    outcome:
+      - collectionName: *collection0Name
+        databaseName: *database0Name
+        documents:
+          - { _id: 1, x: 11 }
+          - { _id: 2, x: 22 }
+          - { _id: 3, x: 33 }
diff --git a/spec/spec_tests/data/crud_unified/updateOne-sort.yml b/spec/spec_tests/data/crud_unified/updateOne-sort.yml

Original file line number	Diff line number	Diff line change
`@@ -99,6 +99,7 @@ module Transformable`
`99`	`99`	`d['upsert'] = true if doc[:upsert]`
`100`	`100`	`d[Operation::COLLATION] = doc[:collation] if doc[:collation]`
`101`	`101`	`d['hint'] = doc[:hint] if doc[:hint]`
	`102`	`+ d['sort'] = doc[:sort] if doc[:sort]`
`102`	`103`	`end`
`103`	`104`	`}`
`104`	`105`
`@@ -130,6 +131,7 @@ module Transformable`
`130`	`131`	`d[Operation::COLLATION] = doc[:collation] if doc[:collation]`
`131`	`132`	`d[Operation::ARRAY_FILTERS] = doc[:array_filters] if doc[:array_filters]`
`132`	`133`	`d['hint'] = doc[:hint] if doc[:hint]`
	`134`	`+ d['sort'] = doc[:sort] if doc[:sort]`
`133`	`135`	`end`
`134`	`136`	`}`
`135`	`137`
Original file line number	Diff line number	Diff line change
`@@ -1049,6 +1049,11 @@ def parallel_scan(cursor_count, options = {})`
`1049`	`1049`	`# May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").`
`1050`	`1050`	`# @option options [ Hash ] :let Mapping of variables to use in the command.`
`1051`	`1051`	`# See the server documentation for details.`
	`1052`	`+ # @option options [ Hash ] :sort Specifies which document the operation`
	`1053`	`+ # replaces if the query matches multiple documents. The first document`
	`1054`	`+ # matched by the sort order will be replaced.`
	`1055`	`+ # This option is only supported by servers >= 8.0. Older servers will`
	`1056`	`+ # report an error for using this option.`
`1052`	`1057`	`#`
`1053`	`1058`	`# @return [ Result ] The response from the database.`
`1054`	`1059`	`#`
`@@ -1115,6 +1120,11 @@ def update_many(filter, update, options = {})`
`1115`	`1120`	`# May be specified as a Hash (e.g. { _id: 1 }) or a String (e.g. "_id_").`
`1116`	`1121`	`# @option options [ Hash ] :let Mapping of variables to use in the command.`
`1117`	`1122`	`# See the server documentation for details.`
	`1123`	`+ # @option options [ Hash ] :sort Specifies which document the operation`
	`1124`	`+ # updates if the query matches multiple documents. The first document`
	`1125`	`+ # matched by the sort order will be updated.`
	`1126`	`+ # This option is only supported by servers >= 8.0. Older servers will`
	`1127`	`+ # report an error for using this option.`
`1118`	`1128`	`#`
`1119`	`1129`	`# @return [ Result ] The response from the database.`
`1120`	`1130`	`#`