DOCSP-41986: multikey indexes

source/includes/indexes/indexes.php

@@ -30,3 +30,14 @@
 $document = $collection->findOne(['title' => 'Sweethearts']);
 echo json_encode($document) , PHP_EOL;
 // end-index-single-query
+
+// start-multikey
+$indexName = $collection->createIndex(['cast' => 1]);
+// end-multikey
+
+// start-index-array-query
+$document = $collection->findOne(
+    ['cast' => ['$in' => ['Aamir Khan', 'Kajol']]]
+);
+echo json_encode($document) , PHP_EOL;
+// end-index-array-query

source/indexes.txt

@@ -24,6 +24,7 @@ Optimize Queries by Using Indexes
 
    /indexes/index-mgmt
    /indexes/single-field-index
+   /indexes/multikey-index
 
 Overview
 --------

source/indexes/index-mgmt.txt

@@ -67,6 +67,7 @@ The following pages describe different index types and provide sample
 code to programmatically create each type of index.
 
 - :ref:`php-single-field-index`
+- :ref:`php-multikey-index`
 
 .. - :ref:`php-compound-index`
 .. - :ref:`php-atlas-search-index`
@@ -134,6 +135,6 @@ API Documentation
 To learn more about any of the methods or types discussed in this
 guide, see the following API documentation:
 
-- `MongoDB\\Collection::listIndexes() <{+api+}/method/MongoDBCollection-listIndexes/>`__
-- `MongoDB\\Collection::dropIndex() <{+api+}/method/MongoDBCollection-dropIndex/>`__
-- `MongoDB\\Collection::dropIndexes() <{+api+}/method/MongoDBCollection-dropIndexes/>`__
+- :phpmethod:`MongoDB\Collection::listIndexes()`
+- :phpmethod:`MongoDB\Collection::dropIndex()`
+- :phpmethod:`MongoDB\Collection::dropIndexes()`

source/indexes/multikey-index.txt

@@ -0,0 +1,89 @@
+.. _php-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 the performance of queries
+on array-valued fields. You can create a multikey index on a collection
+by using the ``MongoDB\Collection::createIndex()`` method and the same
+syntax that you use to create :ref:`single field
+<php-single-field-index>` or compound indexes.
+
+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
+-----------------------
+
+Use the ``MongoDB\Collection::createIndex()`` method to create a
+multikey index. The following example creates an index in ascending
+order on the array-valued ``cast`` field:
+
+.. literalinclude:: /includes/indexes/indexes.php
+   :start-after: start-multikey
+   :end-before: end-multikey
+   :language: php
+   :copyable:
+   :dedent:
+
+The following is an example of a query that is covered by the index
+created in the preceding code example:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/indexes/indexes.php
+      :start-after: start-index-array-query
+      :end-before: end-index-array-query
+      :language: php
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":...,"title":"Holi",...,"cast":["Ashutosh Gowariker",
+      "Aamir Khan","Rahul Ranade","Sanjeev Gandhi"],...}
+
+Additional Information
+----------------------
+
+Multikey indexes behave differently from other indexes in terms of query
+coverage, index bound computation, and sort behavior. To learn more
+about the behavior and limitations of multikey indexes, see
+:manual:`Multikey Indexes </core/index-multikey>` in the {+mdb-server+}
+manual.
+
+To view runnable examples that demonstrate how to manage indexes, see
+:ref:`php-indexes`.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about any of the methods discussed in this guide, see the following API
+documentation:
+
+- :phpmethod:`MongoDB\Collection::createIndex()`
+- :phpmethod:`MongoDB\Collection::findOne()`

source/indexes/single-field-index.txt

@@ -83,6 +83,9 @@ created in the preceding code example:
 Additional Information
 ----------------------
 
+To view runnable examples that demonstrate how to manage indexes, see
+:ref:`php-indexes`.
+
 To learn more about single-field indexes, see :manual:`Single Field
 Indexes </core/index-single>` in the {+mdb-server+} manual.
 
@@ -92,5 +95,5 @@ API Documentation
 To learn more about any of the methods discussed in this guide, see the following API
 documentation:
 
-- `MongoDB\\Collection::createIndex() <{+api+}/method/MongoDBCollection-createIndex/>`__
-- `MongoDB\\Collection::findOne() <{+api+}/method/MongoDBCollection-findOne/>`__
+- :phpmethod:`MongoDB\Collection::createIndex()`
+- :phpmethod:`MongoDB\Collection::findOne()`