CDRIVER-5640 support sort option for update+replace (#1789)

* add `sort` to `mongoc_bulk_update_one_opts_t` and `mongoc_bulk_replace_one_opts_t`

Required to permit passing "sort". The collection bulk operations reject extra fields (refer CDRIVER-2665).

* add `sort`  to `mongoc_update_one_opts_t` and `mongoc_replace_one_opts_t`

Not strictly needed. `mongoc_collection_update_one` and `mongoc_collection_replace_one` already accept the `sort` option as part of `opts`. Adding the option generates documentation.

* regenerate options by running `python build/generate-opts.py`

* sync tests from: mongodb/specifications@24817a5

* add `mongoc_bulkwrite_replaceoneopts_set_sort`

* add `mongoc_bulkwrite_updateoneopts_set_sort`

* support `sort` in unified test runner

* support `sort` in `mongoc_collection_update_one` and `mongoc_collection_replace_one`

* support `sort` in `mongoc_bulk_operation_update_one_with_opts` and `mongoc_bulk_operation_replace_one_with_opts`

Author: kevinAlbs

build/generate-opts.py

@@ -214,6 +214,7 @@ def __init__(self, items, **defaults):
     ('mongoc_update_one_opts_t', Struct([
         ('update', {'type': 'mongoc_update_opts_t'}),
         array_filters_option,
+        ('sort', {'type': 'document', 'help': 'Specify a sort order when matching documents.'})
     ], validate='_mongoc_default_update_vflags')),
 
     ('mongoc_update_many_opts_t', Struct([
@@ -223,6 +224,7 @@ def __init__(self, items, **defaults):
 
     ('mongoc_replace_one_opts_t', Struct([
         ('update', {'type': 'mongoc_update_opts_t'}),
+        ('sort', {'type': 'document', 'help': 'Specify a sort order when matching documents.'})
     ], validate='_mongoc_default_replace_vflags')),
 
     ('mongoc_bulk_opts_t', Struct([
@@ -251,6 +253,7 @@ def __init__(self, items, **defaults):
     ('mongoc_bulk_update_one_opts_t', Struct(
         [
             ('update', {'type': 'mongoc_bulk_update_opts_t'}),
+            ('sort', {'type': 'document', 'help': 'Specify a sort order when matching documents.'}),
             array_filters_option,
         ],
         multi='false',
@@ -267,7 +270,10 @@ def __init__(self, items, **defaults):
         allow_extra=False)),
 
     ('mongoc_bulk_replace_one_opts_t', Struct(
-        [('update', {'type': 'mongoc_bulk_update_opts_t'})],
+        [
+            ('update', {'type': 'mongoc_bulk_update_opts_t'}),
+            ('sort', {'type': 'document', 'help': 'Specify a sort order when matching documents.'})
+        ],
         multi='false',
         validate='_mongoc_default_replace_vflags',
         allow_extra=False)),

src/libmongoc/doc/includes/bulk-replace-one-opts.txt

@@ -9,3 +9,4 @@
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: If true, insert a document if none match ``selector``.
+* ``sort``: Specify a sort order when matching documents.

src/libmongoc/doc/includes/bulk-update-one-opts.txt

@@ -9,4 +9,5 @@
 * ``collation``: Configure textual comparisons. See `Setting Collation Order <setting_collation_order_>`_, and `the MongoDB Manual entry on Collation <https://www.mongodb.com/docs/manual/reference/collation/>`_. Collation requires MongoDB 3.2 or later, otherwise an error is returned.
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: If true, insert a document if none match ``selector``.
+* ``sort``: Specify a sort order when matching documents.
 * ``arrayFilters``: An array of filters specifying to which array elements an update should apply.

src/libmongoc/doc/includes/replace-one-opts.txt

@@ -14,3 +14,4 @@
 * ``hint``: A document or string that specifies the index to use to support the query predicate.
 * ``upsert``: When true, creates a new document if no document matches the query.
 * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.
+* ``sort``: Specify a sort order when matching documents.

src/libmongoc/doc/includes/update-one-opts.txt

@@ -15,3 +15,4 @@
 * ``upsert``: When true, creates a new document if no document matches the query.
 * ``let``: A BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language.
 * ``arrayFilters``: An array of filters specifying to which array elements an update should apply.
+* ``sort``: Specify a sort order when matching documents.

src/libmongoc/doc/mongoc_bulkwrite_replaceoneopts_set_sort.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_bulkwrite_replaceoneopts_set_sort
+
+mongoc_bulkwrite_replaceoneopts_set_sort()
+==========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_replaceoneopts_set_sort (mongoc_bulkwrite_replaceoneopts_t *self, bson_t* sort);
+
+Description
+-----------
+
+``sort`` specifies a sorting order if the query matches multiple documents.
+The first document matched by the sort order will be replaced.
+This option is only sent if the caller explicitly provides a value.

src/libmongoc/doc/mongoc_bulkwrite_replaceoneopts_t.rst

@@ -23,4 +23,5 @@ Synopsis
     mongoc_bulkwrite_replaceoneopts_set_collation
     mongoc_bulkwrite_replaceoneopts_set_hint
     mongoc_bulkwrite_replaceoneopts_set_upsert
+    mongoc_bulkwrite_replaceoneopts_set_sort
     mongoc_bulkwrite_replaceoneopts_destroy

src/libmongoc/doc/mongoc_bulkwrite_updateoneopts_set_sort.rst

@@ -0,0 +1,19 @@
+:man_page: mongoc_bulkwrite_updateoneopts_set_sort
+
+mongoc_bulkwrite_updateoneopts_set_sort()
+=========================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   void
+   mongoc_bulkwrite_updateoneopts_set_sort (mongoc_bulkwrite_updateoneopts_t *self, bson_t* sort);
+
+Description
+-----------
+
+``sort`` specifies a sorting order if the query matches multiple documents.
+The first document matched by the sort order will be updated.
+This option is only sent if the caller explicitly provides a value.

src/libmongoc/doc/mongoc_bulkwrite_updateoneopts_t.rst

@@ -24,4 +24,5 @@ Synopsis
     mongoc_bulkwrite_updateoneopts_set_collation
     mongoc_bulkwrite_updateoneopts_set_hint
     mongoc_bulkwrite_updateoneopts_set_upsert
+    mongoc_bulkwrite_updateoneopts_set_sort
     mongoc_bulkwrite_updateoneopts_destroy

src/libmongoc/src/mongoc/mongoc-bulk-operation.c

@@ -408,7 +408,8 @@ _mongoc_bulk_operation_update_append (mongoc_bulk_operation_t *bulk,
                                       const bson_t *document,
                                       const mongoc_bulk_update_opts_t *update_opts,
                                       const bson_t *array_filters,
-                                      const bson_t *extra_opts)
+                                      const bson_t *extra_opts,
+                                      const bson_t *sort)
 {
    mongoc_write_command_t command = {0};
    mongoc_write_command_t *last;
@@ -437,6 +438,10 @@ _mongoc_bulk_operation_update_append (mongoc_bulk_operation_t *bulk,
       bson_append_value (&opts, "hint", 4, &update_opts->hint);
    }
 
+   if (!bson_empty0 (sort)) {
+      bson_append_document (&opts, "sort", 4, sort);
+   }
+
    if (extra_opts) {
       bson_concat (&opts, extra_opts);
    }
@@ -483,6 +488,7 @@ _mongoc_bulk_operation_update_with_opts (mongoc_bulk_operation_t *bulk,
                                          const bson_t *array_filters,
                                          const bson_t *extra_opts,
                                          bool multi,
+                                         const bson_t *sort,
                                          bson_error_t *error) /* OUT */
 {
    ENTRY;
@@ -507,7 +513,7 @@ _mongoc_bulk_operation_update_with_opts (mongoc_bulk_operation_t *bulk,
       RETURN (false);
    }
 
-   _mongoc_bulk_operation_update_append (bulk, selector, document, update_opts, array_filters, extra_opts);
+   _mongoc_bulk_operation_update_append (bulk, selector, document, update_opts, array_filters, extra_opts, sort);
 
    RETURN (true);
 }
@@ -538,6 +544,7 @@ mongoc_bulk_operation_update_one_with_opts (mongoc_bulk_operation_t *bulk,
                                                   &update_opts.arrayFilters,
                                                   &update_opts.extra,
                                                   false /* multi */,
+                                                  &update_opts.sort,
                                                   error);
 
    _mongoc_bulk_update_one_opts_cleanup (&update_opts);
@@ -570,6 +577,7 @@ mongoc_bulk_operation_update_many_with_opts (mongoc_bulk_operation_t *bulk,
                                                   &update_opts.arrayFilters,
                                                   &update_opts.extra,
                                                   true /* multi */,
+                                                  NULL /* sort */,
                                                   error);
 
    _mongoc_bulk_update_many_opts_cleanup (&update_opts);
@@ -674,7 +682,8 @@ mongoc_bulk_operation_replace_one_with_opts (mongoc_bulk_operation_t *bulk,
       GOTO (done);
    }
 
-   _mongoc_bulk_operation_update_append (bulk, selector, document, update_opts, NULL, &repl_opts.extra);
+   _mongoc_bulk_operation_update_append (
+      bulk, selector, document, update_opts, NULL, &repl_opts.extra, &repl_opts.sort);
    ret = true;
 
 done:

src/libmongoc/src/mongoc/mongoc-bulkwrite.c

@@ -326,6 +326,7 @@ struct _mongoc_bulkwrite_updateoneopts_t {
    bson_t *collation;
    bson_value_t hint;
    mongoc_optional_t upsert;
+   bson_t *sort;
 };
 
 mongoc_bulkwrite_updateoneopts_t *
@@ -361,6 +362,13 @@ mongoc_bulkwrite_updateoneopts_set_upsert (mongoc_bulkwrite_updateoneopts_t *sel
    mongoc_optional_set_value (&self->upsert, upsert);
 }
 void
+mongoc_bulkwrite_updateoneopts_set_sort (mongoc_bulkwrite_updateoneopts_t *self, const bson_t *sort)
+{
+   BSON_ASSERT_PARAM (self);
+   BSON_OPTIONAL_PARAM (sort);
+   set_bson_opt (&self->sort, sort);
+}
+void
 mongoc_bulkwrite_updateoneopts_destroy (mongoc_bulkwrite_updateoneopts_t *self)
 {
    if (!self) {
@@ -369,6 +377,7 @@ mongoc_bulkwrite_updateoneopts_destroy (mongoc_bulkwrite_updateoneopts_t *self)
    bson_destroy (self->arrayfilters);
    bson_destroy (self->collation);
    bson_value_destroy (&self->hint);
+   bson_destroy (self->sort);
    bson_free (self);
 }
 
@@ -422,6 +431,9 @@ mongoc_bulkwrite_append_updateone (mongoc_bulkwrite_t *self,
    if (mongoc_optional_is_set (&opts->upsert)) {
       BSON_ASSERT (BSON_APPEND_BOOL (&op, "upsert", mongoc_optional_value (&opts->upsert)));
    }
+   if (opts->sort) {
+      BSON_ASSERT (BSON_APPEND_DOCUMENT (&op, "sort", opts->sort));
+   }
 
    BSON_ASSERT (_mongoc_buffer_append (&self->ops, bson_get_data (&op), op.len));
 
@@ -436,6 +448,7 @@ struct _mongoc_bulkwrite_replaceoneopts_t {
    bson_t *collation;
    bson_value_t hint;
    mongoc_optional_t upsert;
+   bson_t *sort;
 };
 
 mongoc_bulkwrite_replaceoneopts_t *
@@ -464,13 +477,21 @@ mongoc_bulkwrite_replaceoneopts_set_upsert (mongoc_bulkwrite_replaceoneopts_t *s
    mongoc_optional_set_value (&self->upsert, upsert);
 }
 void
+mongoc_bulkwrite_replaceoneopts_set_sort (mongoc_bulkwrite_replaceoneopts_t *self, const bson_t *sort)
+{
+   BSON_ASSERT_PARAM (self);
+   BSON_OPTIONAL_PARAM (sort);
+   set_bson_opt (&self->sort, sort);
+}
+void
 mongoc_bulkwrite_replaceoneopts_destroy (mongoc_bulkwrite_replaceoneopts_t *self)
 {
    if (!self) {
       return;
    }
    bson_destroy (self->collation);
    bson_value_destroy (&self->hint);
+   bson_destroy (self->sort);
    bson_free (self);
 }
 
@@ -542,6 +563,9 @@ mongoc_bulkwrite_append_replaceone (mongoc_bulkwrite_t *self,
    if (mongoc_optional_is_set (&opts->upsert)) {
       BSON_ASSERT (BSON_APPEND_BOOL (&op, "upsert", mongoc_optional_value (&opts->upsert)));
    }
+   if (opts->sort) {
+      BSON_ASSERT (BSON_APPEND_DOCUMENT (&op, "sort", opts->sort));
+   }
 
    BSON_ASSERT (_mongoc_buffer_append (&self->ops, bson_get_data (&op), op.len));
 

src/libmongoc/src/mongoc/mongoc-bulkwrite.h

@@ -151,6 +151,8 @@ mongoc_bulkwrite_updateoneopts_set_hint (mongoc_bulkwrite_updateoneopts_t *self,
 MONGOC_EXPORT (void)
 mongoc_bulkwrite_updateoneopts_set_upsert (mongoc_bulkwrite_updateoneopts_t *self, bool upsert);
 MONGOC_EXPORT (void)
+mongoc_bulkwrite_updateoneopts_set_sort (mongoc_bulkwrite_updateoneopts_t *self, const bson_t *sort);
+MONGOC_EXPORT (void)
 mongoc_bulkwrite_updateoneopts_destroy (mongoc_bulkwrite_updateoneopts_t *self);
 MONGOC_EXPORT (bool)
 mongoc_bulkwrite_append_updateone (mongoc_bulkwrite_t *self,
@@ -191,6 +193,8 @@ mongoc_bulkwrite_replaceoneopts_set_hint (mongoc_bulkwrite_replaceoneopts_t *sel
 MONGOC_EXPORT (void)
 mongoc_bulkwrite_replaceoneopts_set_upsert (mongoc_bulkwrite_replaceoneopts_t *self, bool upsert);
 MONGOC_EXPORT (void)
+mongoc_bulkwrite_replaceoneopts_set_sort (mongoc_bulkwrite_replaceoneopts_t *self, const bson_t *sort);
+MONGOC_EXPORT (void)
 mongoc_bulkwrite_replaceoneopts_destroy (mongoc_bulkwrite_replaceoneopts_t *self);
 MONGOC_EXPORT (bool)
 mongoc_bulkwrite_append_replaceone (mongoc_bulkwrite_t *self,

src/libmongoc/src/mongoc/mongoc-collection.c

@@ -2017,6 +2017,7 @@ _mongoc_collection_update_or_replace (mongoc_collection_t *collection,
                                       bool multi,
                                       bool bypass,
                                       const bson_t *array_filters,
+                                      const bson_t *sort,
                                       bson_t *extra,
                                       bson_t *reply,
                                       bson_error_t *error)
@@ -2058,6 +2059,10 @@ _mongoc_collection_update_or_replace (mongoc_collection_t *collection,
       bson_append_array (extra, "arrayFilters", 12, array_filters);
    }
 
+   if (!bson_empty0 (sort)) {
+      bson_append_document (extra, "sort", 4, sort);
+   }
+
    if (multi) {
       bson_append_bool (extra, "multi", 5, true);
    }
@@ -2180,6 +2185,7 @@ mongoc_collection_update_one (mongoc_collection_t *collection,
                                                false /* multi */,
                                                update_one_opts.update.bypass,
                                                &update_one_opts.arrayFilters,
+                                               &update_one_opts.sort,
                                                &update_one_opts.extra,
                                                reply,
                                                error);
@@ -2224,6 +2230,7 @@ mongoc_collection_update_many (mongoc_collection_t *collection,
                                                true /* multi */,
                                                update_many_opts.update.bypass,
                                                &update_many_opts.arrayFilters,
+                                               NULL /* sort */,
                                                &update_many_opts.extra,
                                                reply,
                                                error);
@@ -2268,6 +2275,7 @@ mongoc_collection_replace_one (mongoc_collection_t *collection,
                                                false /* multi */,
                                                replace_one_opts.update.bypass,
                                                NULL,
+                                               &replace_one_opts.sort,
                                                &replace_one_opts.extra,
                                                reply,
                                                error);

src/libmongoc/src/mongoc/mongoc-opts-private.h

@@ -84,6 +84,7 @@ typedef struct _mongoc_delete_many_opts_t {
 typedef struct _mongoc_update_one_opts_t {
    mongoc_update_opts_t update;
    bson_t arrayFilters;
+   bson_t sort;
    bson_t extra;
 } mongoc_update_one_opts_t;
 
@@ -95,6 +96,7 @@ typedef struct _mongoc_update_many_opts_t {
 
 typedef struct _mongoc_replace_one_opts_t {
    mongoc_update_opts_t update;
+   bson_t sort;
    bson_t extra;
 } mongoc_replace_one_opts_t;
 
@@ -123,6 +125,7 @@ typedef struct _mongoc_bulk_update_opts_t {
 
 typedef struct _mongoc_bulk_update_one_opts_t {
    mongoc_bulk_update_opts_t update;
+   bson_t sort;
    bson_t arrayFilters;
    bson_t extra;
 } mongoc_bulk_update_one_opts_t;
@@ -135,6 +138,7 @@ typedef struct _mongoc_bulk_update_many_opts_t {
 
 typedef struct _mongoc_bulk_replace_one_opts_t {
    mongoc_bulk_update_opts_t update;
+   bson_t sort;
    bson_t extra;
 } mongoc_bulk_replace_one_opts_t;