Skip to content

Commit ca45383

Browse files
kevinAlbsvector-of-booleramongodb
authored
CDRIVER-3755 Provide an index creation helper (#1303)
* format mongoc-collection.c * add `mongoc_collection_create_indexes_with_opts` * make `assert_match_bson` a macro Includes the caller's file and line number on error. * fixup `hex_to_bin` helper - return NULL if `hex` is NULL - set `len` to 0 on error This fixes a possible crash if LOCAL_MASTERKEY is not set in the example. * update legacy test runner to use `mongoc_collection_create_indexes_with_opts` * use `mongoc_collection_create_indexes_with_opts` in `create_collection_with_encryptedFields` * use `mongoc_collection_create_indexes_with_opts` in `operation_create_index` * fix placement of `strlen` `strlen` was called was before `to_encrypt.value.v_utf8.str` was assigned. This resulted in a `strlen` call with `NULL` argument. * use `mongoc_collection_create_indexes_with_opts` in examples * add documentation page for `mongoc_collection_create_indexes_with_opts` * update "Creating Indexes" guide * add file name to example error message Co-authored-by: vector-of-bool <[email protected]> * fix documented type of `models` to include `*` Co-authored-by: Ezra Chung <[email protected]> * simplify error handling Co-authored-by: Ezra Chung <[email protected]> * revise assert message Co-authored-by: Ezra Chung <[email protected]> * use `mongoc_collection_create_indexes_with_opts` in more tests * rename FAIL to HANDLE_ERROR * document "success" and "failure" paths in example * rename guide page to "Manage Collection Indexes" * rename guide file to `manage-collection-indexes.rst` * rename `example-create-indexes.c` to `example-manage-collection-indexes.c` * add "See Also" sections * link to `createIndexes` documentation for form of `keys` * document `mongoc_index_model_t` * change `BSON_ASSERT` to `return NULL;` * make pointer argument const --------- Co-authored-by: vector-of-bool <[email protected]> Co-authored-by: Ezra Chung <[email protected]>
1 parent b3a11d0 commit ca45383

34 files changed

+781
-440
lines changed

‎src/libmongoc/.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ example-client
2525
example-collection-watch
2626
example-command-monitoring
2727
example-command-with-opts
28-
example-create-indexes
28+
example-manage-collection-indexes
2929
example-gridfs
3030
example-gridfs-bucket
3131
example-pool

‎src/libmongoc/CMakeLists.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1092,7 +1092,7 @@ if (ENABLE_EXAMPLES)
10921092
mongoc_add_example (example-start-at-optime ${PROJECT_SOURCE_DIR}/examples/example-start-at-optime.c)
10931093
mongoc_add_example (example-command-monitoring ${PROJECT_SOURCE_DIR}/examples/example-command-monitoring.c)
10941094
mongoc_add_example (example-command-with-opts ${PROJECT_SOURCE_DIR}/examples/example-command-with-opts.c)
1095-
mongoc_add_example (example-create-indexes ${PROJECT_SOURCE_DIR}/examples/example-create-indexes.c)
1095+
mongoc_add_example (example-manage-collection-indexes ${PROJECT_SOURCE_DIR}/examples/example-manage-collection-indexes.c)
10961096
mongoc_add_example (example-gridfs ${PROJECT_SOURCE_DIR}/examples/example-gridfs.c)
10971097
mongoc_add_example (example-gridfs-bucket ${PROJECT_SOURCE_DIR}/examples/example-gridfs-bucket.c)
10981098
if (NOT WIN32 AND ENABLE_EXAMPLES)

‎src/libmongoc/doc/create-indexes.rst

Lines changed: 0 additions & 25 deletions
This file was deleted.

‎src/libmongoc/doc/guides.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,6 @@ Guides
1616
aggregate
1717
distinct-mapreduce
1818
visual-studio-guide
19-
create-indexes
19+
manage-collection-indexes
2020
debugging
2121
in-use-encryption

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

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
:man_page: mongoc_manage_collection_indexes
2+
3+
Manage Collection Indexes
4+
=========================
5+
6+
To create indexes on a MongoDB collection, use :symbol:`mongoc_collection_create_indexes_with_opts`:
7+
8+
.. literalinclude:: ../examples/example-manage-collection-indexes.c
9+
:language: c
10+
:start-after: // Create an index ... begin
11+
:end-before: // Create an index ... end
12+
:dedent: 6
13+
14+
To list indexes, use :symbol:`mongoc_collection_find_indexes_with_opts`:
15+
16+
.. literalinclude:: ../examples/example-manage-collection-indexes.c
17+
:language: c
18+
:start-after: // List indexes ... begin
19+
:end-before: // List indexes ... end
20+
:dedent: 6
21+
22+
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`:
23+
24+
.. literalinclude:: ../examples/example-manage-collection-indexes.c
25+
:language: c
26+
:start-after: // Drop an index ... begin
27+
:end-before: // Drop an index ... end
28+
:dedent: 6
29+
30+
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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ mongoc_collection_create_index()
66
.. warning::
77
.. deprecated:: 1.8.0
88

9-
This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
9+
This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
1010

1111
Synopsis
1212
--------

‎src/libmongoc/doc/mongoc_collection_create_index_with_opts.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ mongoc_collection_create_index_with_opts()
66
.. warning::
77
.. deprecated:: 1.8.0
88

9-
This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
9+
This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
1010

1111
Synopsis
1212
--------

‎src/libmongoc/doc/mongoc_collection_create_indexes_with_opts.rst

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
:man_page: mongoc_collection_create_indexes_with_opts
2+
3+
mongoc_collection_create_indexes_with_opts()
4+
============================================
5+
6+
Synopsis
7+
--------
8+
9+
.. code-block:: c
10+
11+
typedef struct _mongoc_index_model_t mongoc_index_model_t;
12+
13+
mongoc_index_model_t *
14+
mongoc_index_model_new (const bson_t *keys, const bson_t *opts);
15+
16+
void mongoc_index_model_destroy (mongoc_index_model_t *model);
17+
18+
bool
19+
mongoc_collection_create_indexes_with_opts (mongoc_collection_t *collection,
20+
mongoc_index_model_t **models,
21+
size_t n_models,
22+
const bson_t *opts,
23+
bson_t *reply,
24+
bson_error_t *error);
25+
26+
Parameters
27+
----------
28+
29+
* ``collection``: A :symbol:`mongoc_collection_t`.
30+
* ``models``: An array of ``mongoc_index_model_t *``.
31+
* ``n_models``: The number of ``models``.
32+
* ``opts``: Optional options.
33+
* ``reply``: An optional location for the server reply to the ``createIndexes`` command.
34+
* ``error``: An optional location for a :symbol:`bson_error_t <errors>` or ``NULL``.
35+
36+
.. |opts-source| replace:: ``collection``
37+
38+
.. include:: includes/write-opts.txt
39+
40+
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.
41+
42+
If no write concern is provided in ``opts``, the collection's write concern is used.
43+
44+
mongoc_index_model_t
45+
````````````````````
46+
Each ``mongoc_index_model_t`` represents an index to create. ``mongoc_index_model_new`` includes:
47+
48+
* ``keys`` Expected to match the form of the ``key`` field in the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
49+
* ``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.
50+
51+
52+
Description
53+
-----------
54+
55+
This function wraps around the `createIndexes <https://www.mongodb.com/docs/manual/reference/command/createIndexes/>`_ command.
56+
57+
Errors
58+
------
59+
60+
Errors are propagated via the ``error`` parameter.
61+
62+
Returns
63+
-------
64+
65+
Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments or a server or network error.
66+
67+
.. seealso::
68+
69+
| :doc:`manage-collection-indexes`.

‎src/libmongoc/doc/mongoc_collection_drop_index_with_opts.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,7 @@ Returns
4141
-------
4242

4343
Returns ``true`` if successful. Returns ``false`` and sets ``error`` if there are invalid arguments or a server or network error.
44+
45+
.. seealso::
46+
47+
| :doc:`manage-collection-indexes`.

‎src/libmongoc/doc/mongoc_collection_ensure_index.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ mongoc_collection_ensure_index()
66
.. warning::
77
.. deprecated:: 1.8.0
88

9-
This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
9+
This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
1010

1111
Synopsis
1212
--------

‎src/libmongoc/doc/mongoc_collection_find_indexes_with_opts.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,6 @@ In the returned cursor each result corresponds to the server's representation of
4343

4444
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.
4545

46+
.. seealso::
47+
48+
| :doc:`manage-collection-indexes`.

‎src/libmongoc/doc/mongoc_collection_keys_to_index_string.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ Synopsis
1515
Parameters
1616
----------
1717

18-
* ``keys``: A :symbol:`bson:bson_t`.
18+
* ``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.
1919

2020
Description
2121
-----------
2222

23-
This function returns the canonical stringification of a given key specification. See :doc:`create-indexes`.
23+
This function returns the canonical stringification of a given key specification. See :doc:`manage-collection-indexes` for example usage.
2424

2525
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.
2626

‎src/libmongoc/doc/mongoc_collection_t.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Read preferences and write concerns are inherited from the parent client. They c
3939
mongoc_collection_create_bulk_operation_with_opts
4040
mongoc_collection_create_index
4141
mongoc_collection_create_index_with_opts
42+
mongoc_collection_create_indexes_with_opts
4243
mongoc_collection_delete
4344
mongoc_collection_delete_many
4445
mongoc_collection_delete_one

‎src/libmongoc/doc/mongoc_index_opt_t.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ mongoc_index_opt_t
66
.. warning::
77
.. deprecated:: 1.8.0
88

9-
This structure is deprecated and should not be used in new code. See :doc:`create-indexes`.
9+
This structure is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
1010

1111
Synopsis
1212
--------

‎src/libmongoc/doc/mongoc_uri_get_ssl.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ mongoc_uri_get_ssl()
66
.. warning::
77
.. deprecated:: 1.15.0
88

9-
This function is deprecated and should not be used in new code. See :doc:`create-indexes`.
9+
This function is deprecated and should not be used in new code. See :doc:`manage-collection-indexes`.
1010

1111

1212
This function is deprecated and should not be used in new code.

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

Lines changed: 23 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ main (void)
2323
bson_t *kms_providers = NULL;
2424
bson_error_t error = {0};
2525
bson_t *index_keys = NULL;
26-
char *index_name = NULL;
27-
bson_t *create_index_cmd = NULL;
26+
bson_t *index_opts = NULL;
27+
mongoc_index_model_t *index_model = NULL;
2828
bson_t *schema = NULL;
2929
mongoc_client_t *client = NULL;
3030
mongoc_collection_t *coll = NULL;
@@ -105,34 +105,23 @@ main (void)
105105
/* Create a unique index to ensure that two data keys cannot share the same
106106
* keyAltName. This is recommended practice for the key vault. */
107107
index_keys = BCON_NEW ("keyAltNames", BCON_INT32 (1));
108-
index_name = mongoc_collection_keys_to_index_string (index_keys);
109-
create_index_cmd = BCON_NEW ("createIndexes",
110-
KEYVAULT_COLL,
111-
"indexes",
112-
"[",
113-
"{",
114-
"key",
115-
BCON_DOCUMENT (index_keys),
116-
"name",
117-
index_name,
118-
"unique",
119-
BCON_BOOL (true),
120-
"partialFilterExpression",
121-
"{",
122-
"keyAltNames",
123-
"{",
124-
"$exists",
125-
BCON_BOOL (true),
126-
"}",
127-
"}",
128-
"}",
129-
"]");
130-
ret = mongoc_client_command_simple (client,
131-
KEYVAULT_DB,
132-
create_index_cmd,
133-
NULL /* read prefs */,
134-
NULL /* reply */,
135-
&error);
108+
index_opts = BCON_NEW ("unique",
109+
BCON_BOOL (true),
110+
"partialFilterExpression",
111+
"{",
112+
"keyAltNames",
113+
"{",
114+
"$exists",
115+
BCON_BOOL (true),
116+
"}",
117+
"}");
118+
index_model = mongoc_index_model_new (index_keys, index_opts);
119+
ret = mongoc_collection_create_indexes_with_opts (keyvault_coll,
120+
&index_model,
121+
1,
122+
NULL /* opts */,
123+
NULL /* reply */,
124+
&error);
136125

137126
if (!ret) {
138127
goto fail;
@@ -166,9 +155,6 @@ main (void)
166155
goto fail;
167156
}
168157

169-
const size_t len = strlen (to_encrypt.value.v_utf8.str);
170-
BSON_ASSERT (bson_in_range_unsigned (uint32_t, len));
171-
172158
/* Explicitly encrypt a field. */
173159
encrypt_opts = mongoc_client_encryption_encrypt_opts_new ();
174160
mongoc_client_encryption_encrypt_opts_set_algorithm (
@@ -177,6 +163,8 @@ main (void)
177163
encrypt_opts, "mongoc_encryption_example_4");
178164
to_encrypt.value_type = BSON_TYPE_UTF8;
179165
to_encrypt.value.v_utf8.str = "123456789";
166+
const size_t len = strlen (to_encrypt.value.v_utf8.str);
167+
BSON_ASSERT (bson_in_range_unsigned (uint32_t, len));
180168
to_encrypt.value.v_utf8.len = (uint32_t) len;
181169

182170
ret = mongoc_client_encryption_encrypt (
@@ -221,9 +209,9 @@ main (void)
221209
bson_free (local_masterkey);
222210
bson_destroy (kms_providers);
223211
mongoc_collection_destroy (keyvault_coll);
212+
mongoc_index_model_destroy (index_model);
213+
bson_destroy (index_opts);
224214
bson_destroy (index_keys);
225-
bson_free (index_name);
226-
bson_destroy (create_index_cmd);
227215
mongoc_collection_destroy (coll);
228216
mongoc_client_destroy (client);
229217
bson_destroy (to_insert);

0 commit comments

Comments
 (0)