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
--------

0 commit comments

Comments
 (0)