diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index 6b037dac..ae865cdb 100644 --- a/source/includes/indexes/indexes.php +++ b/source/includes/indexes/indexes.php @@ -28,5 +28,16 @@ // start-index-single-query $document = $collection->findOne(['title' => 'Sweethearts']); -echo json_encode($document) , PHP_EOL; +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 diff --git a/source/includes/usage-examples/index-code-examples.php b/source/includes/usage-examples/index-code-examples.php index 4dee0dc4..779e3a4e 100644 --- a/source/includes/usage-examples/index-code-examples.php +++ b/source/includes/usage-examples/index-code-examples.php @@ -38,7 +38,7 @@ function toJSON(object $document): string // start-search-list foreach ($collection->listSearchIndexes() as $indexInfo) { - echo toJSON($indexInfo) , PHP_EOL; + echo toJSON($indexInfo), PHP_EOL; } // end-search-list diff --git a/source/indexes.txt b/source/indexes.txt index daa9e985..2523bfb7 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -24,6 +24,7 @@ Optimize Queries by Using Indexes /indexes/index-mgmt /indexes/single-field-index + /indexes/multikey-index Overview -------- @@ -107,8 +108,8 @@ specified array-valued field: :copyable: :dedent: -.. TODO To learn more about multikey indexes, see the :ref:`php-multikey-index` -.. guide. +To learn more about multikey indexes, see the :ref:`php-multikey-index` +guide. Geospatial Index ---------------- diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt index 939b4939..92fb541a 100644 --- a/source/indexes/index-mgmt.txt +++ b/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()` diff --git a/source/indexes/multikey-index.txt b/source/indexes/multikey-index.txt new file mode 100644 index 00000000..b3ef21d9 --- /dev/null +++ b/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 +` 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 +`. To learn how to create a free MongoDB Atlas cluster and +load the sample datasets, see the :atlas:`Get Started with Atlas +` 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 ` 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()` diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index cd6de01d..d5eac3d7 100644 --- a/source/indexes/single-field-index.txt +++ b/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 ` 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()`