From 4fd14519f1ece0ab2a15cb15ce1ed3e6e80f412a Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 12 Sep 2024 16:49:57 -0400 Subject: [PATCH 1/6] DOCSP-41986: multikey indexes --- source/includes/indexes/indexes.php | 11 ++++ source/indexes.txt | 1 + source/indexes/index-mgmt.txt | 1 + source/indexes/multikey-index.txt | 85 +++++++++++++++++++++++++++++ 4 files changed, 98 insertions(+) create mode 100644 source/indexes/multikey-index.txt diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index 6b037dac..403ad298 100644 --- a/source/includes/indexes/indexes.php +++ b/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 diff --git a/source/indexes.txt b/source/indexes.txt index daa9e985..634dce6d 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 -------- diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt index 939b4939..4630d4ce 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` diff --git a/source/indexes/multikey-index.txt b/source/indexes/multikey-index.txt new file mode 100644 index 00000000..2e02bde3 --- /dev/null +++ b/source/indexes/multikey-index.txt @@ -0,0 +1,85 @@ +.. _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 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. + +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/>`__ From 3148b8f327a54f4f8a451aa76144e8449f56647d Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 12 Sep 2024 16:56:03 -0400 Subject: [PATCH 2/6] links --- source/indexes/index-mgmt.txt | 6 +++--- source/indexes/multikey-index.txt | 4 ++-- source/indexes/single-field-index.txt | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt index 4630d4ce..c3bcdac7 100644 --- a/source/indexes/index-mgmt.txt +++ b/source/indexes/index-mgmt.txt @@ -135,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 index 2e02bde3..2ca9f507 100644 --- a/source/indexes/multikey-index.txt +++ b/source/indexes/multikey-index.txt @@ -81,5 +81,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()` diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index cd6de01d..e44dcb89 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -92,5 +92,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()` From 54374928c4ac79dd3a87583a0f0b49953f815d90 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 12 Sep 2024 16:57:01 -0400 Subject: [PATCH 3/6] bullet pts --- source/indexes/index-mgmt.txt | 6 +++--- source/indexes/multikey-index.txt | 4 ++-- source/indexes/single-field-index.txt | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt index c3bcdac7..92fb541a 100644 --- a/source/indexes/index-mgmt.txt +++ b/source/indexes/index-mgmt.txt @@ -135,6 +135,6 @@ API Documentation To learn more about any of the methods or types discussed in this guide, see the following API documentation: -:phpmethod:`MongoDB\Collection::listIndexes()` -:phpmethod:`MongoDB\Collection::dropIndex()` -:phpmethod:`MongoDB\Collection::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 index 2ca9f507..2288409e 100644 --- a/source/indexes/multikey-index.txt +++ b/source/indexes/multikey-index.txt @@ -81,5 +81,5 @@ 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()` +- :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 e44dcb89..aa0c0404 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -92,5 +92,5 @@ 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()` +- :phpmethod:`MongoDB\Collection::createIndex()` +- :phpmethod:`MongoDB\Collection::findOne()` From 343513524d35a7753a4c12c7ebf69a058a4d4d93 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 13 Sep 2024 14:54:00 -0400 Subject: [PATCH 4/6] JS suggestion --- source/indexes/multikey-index.txt | 6 +++++- source/indexes/single-field-index.txt | 3 +++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/source/indexes/multikey-index.txt b/source/indexes/multikey-index.txt index 2288409e..b3ef21d9 100644 --- a/source/indexes/multikey-index.txt +++ b/source/indexes/multikey-index.txt @@ -23,7 +23,8 @@ 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 single field or compound indexes. +syntax that you use to create :ref:`single field +` or compound indexes. Sample Data ~~~~~~~~~~~ @@ -75,6 +76,9 @@ 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 ~~~~~~~~~~~~~~~~~ diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index aa0c0404..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. From 6e5971107a05980c770bbec0dcf7c57b62968848 Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 13 Sep 2024 16:24:44 -0400 Subject: [PATCH 5/6] fix whitespace per JM comment --- source/includes/indexes/indexes.php | 4 ++-- source/includes/usage-examples/index-code-examples.php | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index 403ad298..ae865cdb 100644 --- a/source/includes/indexes/indexes.php +++ b/source/includes/indexes/indexes.php @@ -28,7 +28,7 @@ // 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 @@ -39,5 +39,5 @@ $document = $collection->findOne( ['cast' => ['$in' => ['Aamir Khan', 'Kajol']]] ); -echo json_encode($document) , PHP_EOL; +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 From 60f5c9cfda29a67d57cca6c4d1ae6811ba9c7d1b Mon Sep 17 00:00:00 2001 From: rustagir Date: Fri, 13 Sep 2024 16:25:15 -0400 Subject: [PATCH 6/6] uncomment --- source/indexes.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/indexes.txt b/source/indexes.txt index 634dce6d..2523bfb7 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -108,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 ----------------