CDRIVER-3755 Provide an index creation helper

src/libmongoc/.gitignore

@@ -25,7 +25,7 @@ example-client
 example-collection-watch
 example-command-monitoring
 example-command-with-opts
-example-create-indexes
+example-manage-collection-indexes
 example-gridfs
 example-gridfs-bucket
 example-pool

src/libmongoc/CMakeLists.txt

@@ -1096,7 +1096,7 @@ if (ENABLE_EXAMPLES)
    mongoc_add_example (example-start-at-optime ${PROJECT_SOURCE_DIR}/examples/example-start-at-optime.c)
    mongoc_add_example (example-command-monitoring ${PROJECT_SOURCE_DIR}/examples/example-command-monitoring.c)
    mongoc_add_example (example-command-with-opts ${PROJECT_SOURCE_DIR}/examples/example-command-with-opts.c)
-   mongoc_add_example (example-create-indexes ${PROJECT_SOURCE_DIR}/examples/example-create-indexes.c)
+   mongoc_add_example (example-manage-collection-indexes ${PROJECT_SOURCE_DIR}/examples/example-manage-collection-indexes.c)
    mongoc_add_example (example-gridfs ${PROJECT_SOURCE_DIR}/examples/example-gridfs.c)
    mongoc_add_example (example-gridfs-bucket ${PROJECT_SOURCE_DIR}/examples/example-gridfs-bucket.c)
    if (NOT WIN32 AND ENABLE_EXAMPLES)

src/libmongoc/doc/guides.rst

@@ -16,6 +16,6 @@ Guides
    aggregate
    distinct-mapreduce
    visual-studio-guide
-   create-indexes
+   manage-collection-indexes
    debugging
    in-use-encryption

src/libmongoc/doc/manage-collection-indexes.rst

@@ -0,0 +1,30 @@
+:man_page: mongoc_manage_collection_indexes
+
+Manage Collection Indexes
+=========================
+
+To create indexes on a MongoDB collection, use :symbol:`mongoc_collection_create_indexes_with_opts`:
+
+.. literalinclude:: ../examples/example-manage-collection-indexes.c
+   :language: c
+   :start-after: // Create an index ... begin
+   :end-before: // Create an index ... end
+   :dedent: 6
+
+To list indexes, use :symbol:`mongoc_collection_find_indexes_with_opts`:
+
+.. literalinclude:: ../examples/example-manage-collection-indexes.c
+   :language: c
+   :start-after: // List indexes ... begin
+   :end-before: // List indexes ... end
+   :dedent: 6
+
+To drop an index, use :symbol:`mongoc_collection_drop_index_with_opts`. The index name may be obtained from the ``keys`` document with :symbol:`mongoc_collection_keys_to_index_string`:
+
+.. literalinclude:: ../examples/example-manage-collection-indexes.c
+   :language: c
+   :start-after: // Drop an index ... begin
+   :end-before: // Drop an index ... end
+   :dedent: 6
+
+For a full example, see `example-manage-collection-indexes.c <https://github.com/mongodb/mongo-c-driver/blob/master/src/libmongoc/examples/example-manage-collection-indexes.c>`_.

src/libmongoc/doc/mongoc_collection_create_index.rst

@@ -6,7 +6,7 @@ mongoc_collection_create_index()
 .. warning::
    .. deprecated:: 1.8.0
 
-      This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
+      This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
 
 Synopsis
 --------

src/libmongoc/doc/mongoc_collection_create_index_with_opts.rst

@@ -6,7 +6,7 @@ mongoc_collection_create_index_with_opts()
 .. warning::
    .. deprecated:: 1.8.0
 
-      This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
+      This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
 
 Synopsis
 --------

src/libmongoc/doc/mongoc_collection_create_indexes_with_opts.rst

@@ -0,0 +1,69 @@
+:man_page: mongoc_collection_create_indexes_with_opts
+
+mongoc_collection_create_indexes_with_opts()
+============================================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+   typedef struct _mongoc_index_model_t mongoc_index_model_t;
+
+   mongoc_index_model_t *
+   mongoc_index_model_new (const bson_t *keys, const bson_t *opts);
+
+   void mongoc_index_model_destroy (mongoc_index_model_t *model);
+
+   bool
+   mongoc_collection_create_indexes_with_opts (mongoc_collection_t *collection,
+                                               mongoc_index_model_t **models,
+                                               size_t n_models,
+                                               const bson_t *opts,
+                                               bson_t *reply,
+                                               bson_error_t *error);
+
+Parameters
+----------
+
+* ``collection``: A :symbol:`mongoc_collection_t`.
+* ``models``: An array of ``mongoc_index_model_t *``.
+* ``n_models``: The number of ``models``.
+* ``opts``: Optional options.
+* ``reply``: An optional location for the server reply to the ``createIndexes`` command.
+* ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
+
+.. |opts-source| replace:: ``collection``
+
+.. include:: includes/write-opts.txt
+
+Additional options passed in ``opts`` are appended to the ``createIndexes`` command. See the `MongoDB Manual for createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ for all supported options.
+
+If no write concern is provided in ``opts``, the collection's write concern is used.
+
+mongoc_index_model_t
+````````````````````
+Each ``mongoc_index_model_t`` represents an index to create. ``mongoc_index_model_new`` includes:
+
+* ``keys`` Expected to match the form of the ``key`` field in the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
+* ``opts`` Optional index options appended as a sibling to the ``key`` field in the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
+
+
+Description
+-----------
+
+This function wraps around the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
+
+Errors
+------
+
+Errors are propagated via the ``error`` parameter.
+
+Returns
+-------
+
+Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments or a server or network error.
+
+.. seealso::
+
+  | :doc:`manage-collection-indexes`.

src/libmongoc/doc/mongoc_collection_drop_index_with_opts.rst

@@ -41,3 +41,7 @@ Returns
 -------
 
 Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments or a server or network error.
+
+.. seealso::
+
+  | :doc:`manage-collection-indexes`.

src/libmongoc/doc/mongoc_collection_ensure_index.rst

@@ -6,7 +6,7 @@ mongoc_collection_ensure_index()
 .. warning::
    .. deprecated:: 1.8.0
 
-      This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
+      This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
 
 Synopsis
 --------

src/libmongoc/doc/mongoc_collection_find_indexes_with_opts.rst

@@ -43,3 +43,6 @@ In the returned cursor each result corresponds to the server's representation of
 
 The cursor functions :symbol:`mongoc_cursor_set_limit`, :symbol:`mongoc_cursor_set_batch_size`, and :symbol:`mongoc_cursor_set_max_await_time_ms` have no use on the returned cursor.
 
+.. seealso::
+
+  | :doc:`manage-collection-indexes`.

src/libmongoc/doc/mongoc_collection_keys_to_index_string.rst

@@ -15,12 +15,12 @@ Synopsis
 Parameters
 ----------
 
-* ``keys``: A :symbol:`bson:bson_t`.
+* ``keys``: A :symbol:`bson:bson_t`. This is expected to match the form of the ``key`` field in the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
 
 Description
 -----------
 
-This function returns the canonical stringification of a given key specification. See :doc:`create-indexes`.
+This function returns the canonical stringification of a given key specification. See :doc:`manage-collection-indexes` for example usage.
 
 It is a programming error to call this function on a non-standard index, such one other than a straight index with ascending and descending.
 

src/libmongoc/doc/mongoc_collection_t.rst

@@ -39,6 +39,7 @@ Read preferences and write concerns are inherited from the parent client. They c
     mongoc_collection_create_bulk_operation_with_opts
     mongoc_collection_create_index
     mongoc_collection_create_index_with_opts
+    mongoc_collection_create_indexes_with_opts
     mongoc_collection_delete
     mongoc_collection_delete_many
     mongoc_collection_delete_one

src/libmongoc/doc/mongoc_index_opt_t.rst

@@ -6,7 +6,7 @@ mongoc_index_opt_t
 .. warning::
    .. deprecated:: 1.8.0
 
-      This structure is deprecated and should not be used in new code. See :doc:`create-indexes`.
+      This structure is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
 
 Synopsis
 --------

src/libmongoc/doc/mongoc_uri_get_ssl.rst

@@ -6,7 +6,7 @@ mongoc_uri_get_ssl()
 .. warning::
    .. deprecated:: 1.15.0
 
-      This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
+      This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
 
 
 This function is deprecated and should not be used in new code.

src/libmongoc/examples/client-side-encryption-auto-decryption.c

@@ -23,8 +23,8 @@ main (void)
    bson_t *kms_providers = NULL;
    bson_error_t error = {0};
    bson_t *index_keys = NULL;
-   char *index_name = NULL;
-   bson_t *create_index_cmd = NULL;
+   bson_t *index_opts = NULL;
+   mongoc_index_model_t *index_model = NULL;
    bson_t *schema = NULL;
    mongoc_client_t *client = NULL;
    mongoc_collection_t *coll = NULL;
@@ -105,34 +105,23 @@ main (void)
    /* Create a unique index to ensure that two data keys cannot share the same
     * keyAltName. This is recommended practice for the key vault. */
    index_keys = BCON_NEW ("keyAltNames", BCON_INT32 (1));
-   index_name = mongoc_collection_keys_to_index_string (index_keys);
-   create_index_cmd = BCON_NEW ("createIndexes",
-                                KEYVAULT_COLL,
-                                "indexes",
-                                "[",
-                                "{",
-                                "key",
-                                BCON_DOCUMENT (index_keys),
-                                "name",
-                                index_name,
-                                "unique",
-                                BCON_BOOL (true),
-                                "partialFilterExpression",
-                                "{",
-                                "keyAltNames",
-                                "{",
-                                "$exists",
-                                BCON_BOOL (true),
-                                "}",
-                                "}",
-                                "}",
-                                "]");
-   ret = mongoc_client_command_simple (client,
-                                       KEYVAULT_DB,
-                                       create_index_cmd,
-                                       NULL /* read prefs */,
-                                       NULL /* reply */,
-                                       &error);
+   index_opts = BCON_NEW ("unique",
+                          BCON_BOOL (true),
+                          "partialFilterExpression",
+                          "{",
+                          "keyAltNames",
+                          "{",
+                          "$exists",
+                          BCON_BOOL (true),
+                          "}",
+                          "}");
+   index_model = mongoc_index_model_new (index_keys, index_opts);
+   ret = mongoc_collection_create_indexes_with_opts (keyvault_coll,
+                                                     &index_model,
+                                                     1,
+                                                     NULL /* opts */,
+                                                     NULL /* reply */,
+                                                     &error);
 
    if (!ret) {
       goto fail;
@@ -166,9 +155,6 @@ main (void)
       goto fail;
    }
 
-   const size_t len = strlen (to_encrypt.value.v_utf8.str);
-   BSON_ASSERT (bson_in_range_unsigned (uint32_t, len));
-
    /* Explicitly encrypt a field. */
    encrypt_opts = mongoc_client_encryption_encrypt_opts_new ();
    mongoc_client_encryption_encrypt_opts_set_algorithm (
@@ -177,6 +163,8 @@ main (void)
       encrypt_opts, "mongoc_encryption_example_4");
    to_encrypt.value_type = BSON_TYPE_UTF8;
    to_encrypt.value.v_utf8.str = "123456789";
+   const size_t len = strlen (to_encrypt.value.v_utf8.str);
+   BSON_ASSERT (bson_in_range_unsigned (uint32_t, len));
    to_encrypt.value.v_utf8.len = (uint32_t) len;
 
    ret = mongoc_client_encryption_encrypt (
@@ -221,9 +209,9 @@ main (void)
    bson_free (local_masterkey);
    bson_destroy (kms_providers);
    mongoc_collection_destroy (keyvault_coll);
+   mongoc_index_model_destroy (index_model);
+   bson_destroy (index_opts);
    bson_destroy (index_keys);
-   bson_free (index_name);
-   bson_destroy (create_index_cmd);
    mongoc_collection_destroy (coll);
    mongoc_client_destroy (client);
    bson_destroy (to_insert);