DOCSP-43086: Multikey Indexes

source/includes/indexes/indexes.c

@@ -95,7 +95,41 @@ main (int argc, char *argv[])
         bson_destroy (filter);
         // end-index-compound-query
     }
-        {
+    {
+        // start-index-multikey
+        bson_error_t error;
+        bson_t *keys = BCON_NEW ("cast", BCON_INT32 (1));
+        mongoc_index_model_t *index_model = mongoc_index_model_new (keys, NULL);
+
+        if (mongoc_collection_create_indexes_with_opts (collection, &index_model, 1, NULL, NULL, &error)) {
+            printf ("Successfully created index\n");
+        } else {
+            fprintf (stderr, "Failed to create index: %s", error.message);
+        }
+
+        bson_destroy (keys);
+        mongoc_index_model_destroy (index_model);
+        // end-index-multikey
+    }
+    {
+        // start-index-multikey-query
+        const bson_t *doc;
+        bson_t *filter = BCON_NEW ("cast", BCON_UTF8 ("Viola Davis"));
+
+        mongoc_cursor_t *results =
+            mongoc_collection_find_with_opts (collection, filter, NULL, NULL);
+
+        while (mongoc_cursor_next (results, &doc)) {
+            char *str = bson_as_canonical_extended_json (doc, NULL);
+            printf ("%s\n", str);
+            bson_free (str);
+        }
+
+        mongoc_cursor_destroy (results);
+        bson_destroy (filter);
+        // end-index-multikey-query
+    }
+    {
         // start-create-search-index
         bson_t cmd;
         bson_error_t error;
@@ -201,7 +235,6 @@ main (int argc, char *argv[])
         // end-drop-search-index
     }
 
-
     mongoc_collection_destroy (collection);
     mongoc_client_destroy (client);
     mongoc_cleanup ();

source/indexes.txt

@@ -92,8 +92,7 @@ The following example creates an ascending multikey index on the specified array
    :copyable:
    :dedent:
 
-To learn more about multikey indexes, see the :ref:`c-multikey-index`
-guide.
+To learn more about multikey indexes, see the :ref:`c-multikey-index` guide.
 
 Geospatial Index
 ----------------

source/indexes/multikey-index.txt

@@ -0,0 +1,80 @@
+.. _c-multikey-index:
+
+================
+Multikey Indexes
+================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: index, query, optimization, efficiency
+
+Overview
+--------
+
+**Multikey indexes** are indexes that improve performance for queries on array-valued
+fields. You can define a multikey index by using the same syntax as
+a single field or compound index.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``movies`` collection in the ``sample_mflix``
+database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see the
+:atlas:`Get Started with Atlas </getting-started>` guide.
+
+Create a Multikey Index
+-----------------------
+
+The following example creates a multikey index on the ``cast`` field:
+
+.. literalinclude:: /includes/indexes/indexes.c
+   :language: c
+   :start-after: start-index-multikey
+   :end-before: end-index-multikey
+   :copyable:
+   :dedent:
+
+The following example performs a query that uses the index created in the preceding code
+sample:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/indexes/indexes.c
+      :start-after: start-index-multikey-query
+      :end-before: end-index-multikey-query
+      :language: c
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      { "_id" : ..., "cast" : [ "Kelsey Grammer", "Cary Elwes", "Viola Davis", "John C. McGinley" ], "title" : "The Pentagon Wars", ... }
+      { "_id" : ..., "cast" : [ "George Clooney", "Natascha McElhone", "Viola Davis", "Jeremy Davies" ], "title" : "Solaris", ... }
+      { "_id" : ..., "cast" : [ "Meryl Streep", "Philip Seymour Hoffman", "Amy Adams", "Viola Davis" ], "title" : "Doubt", ... }
+      { "_id" : ..., "cast" : [ "Hugh Jackman", "Jake Gyllenhaal", "Viola Davis", "Maria Bello" ], "title" : "Prisoners", ... }
+      { "_id" : ..., "cast" : [ "Emma Stone", "Viola Davis", "Bryce Dallas Howard", "Octavia Spencer" ], "title" : "The Help", ... }
+      ...
+
+Multikey indexes behave differently from other indexes in terms of query coverage, index bound computation, and
+sort behavior. To learn more about multikey indexes, including a discussion of their behavior and limitations,
+see the :manual:`Multikey Indexes </core/index-multikey>` guide in the {+mdb-server+} manual.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the functions discussed in this guide, see the following API
+documentation:
+
+- `mongoc_collection_find_with_opts() <{+api-libmongoc+}/mongoc_collection_find_with_opts.html>`_
+- `mongoc_collection_create_indexes_with_opts() <{+api-libmongoc+}/mongoc_collection_create_indexes_with_opts.html>`_

source/work-with-indexes.txt

@@ -21,6 +21,7 @@ Work with Indexes
 
    /indexes/single-field-index.txt
    /indexes/compound-index.txt
+   /indexes/multikey-index.txt
    /indexes/atlas-search-index.txt
 
 Overview
@@ -70,6 +71,7 @@ code for creating each index type.
 
 - :ref:`c-single-field-index`
 - :ref:`c-compound-index`
+- :ref:`c-multikey-index`
 - :ref:`c-atlas-search-index`
 
 Remove an Index