diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php new file mode 100644 index 00000000..6b037dac --- /dev/null +++ b/source/includes/indexes/indexes.php @@ -0,0 +1,32 @@ +sample_mflix; +$collection = $database->movies; + +// start-list-indexes +foreach ($collection->listIndexes() as $indexInfo) { + echo $indexInfo; +} +// end-list-indexes + +// start-remove-index +$collection->dropIndex('_title_'); +// end-remove-index + +// start-remove-all-indexes +$collection->dropIndexes(); +// end-remove-all-indexes + +// start-index-single +$indexName = $collection->createIndex(['title' => 1]); +// end-index-single + +// start-index-single-query +$document = $collection->findOne(['title' => 'Sweethearts']); +echo json_encode($document) , PHP_EOL; +// end-index-single-query diff --git a/source/indexes.txt b/source/indexes.txt index cd9fa904..daa9e985 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -18,11 +18,12 @@ Optimize Queries by Using Indexes :description: Learn how to use indexes by using the MongoDB PHP Library. :keywords: query, optimization, efficiency, usage example, code example -.. .. toctree:: -.. :titlesonly: -.. :maxdepth: 1 -.. -.. /work-with-indexes +.. toctree:: + :titlesonly: + :maxdepth: 1 + + /indexes/index-mgmt + /indexes/single-field-index Overview -------- diff --git a/source/indexes/index-mgmt.txt b/source/indexes/index-mgmt.txt new file mode 100644 index 00000000..939b4939 --- /dev/null +++ b/source/indexes/index-mgmt.txt @@ -0,0 +1,139 @@ +.. _php-index-mgmt: + +=================================== +Index Considerations and Management +=================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: query, optimization, efficiency + +Overview +-------- + +In this guide, you can learn about using **indexes** to improve the +efficiency of your queries and add functionality to querying and +storing documents. + +Without a relevant index, MongoDB scans every document in a collection +to find the documents that match a query. These collection scans are +slow and can negatively affect the performance of your application. +However, if the appropriate index exists, MongoDB can use the index to +reduce the number of documents to inspect. + +Operational Considerations +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To improve query performance, build indexes on fields that appear often in +your application's queries or operations that return sorted results. Each +index that you add consumes disk space and memory, so we recommend +that you track memory and disk usage when doing capacity planning. In addition, +when a write operation updates an indexed field, MongoDB updates the related +index, which can negatively impact performance for write operations. + +You can use :manual:`wildcard indexes ` in your +MongoDB application to query against fields whose names are not known in +advance or are arbitrary. Wildcard indexes are *not* designed to replace +workload-based index planning. + +To learn more about designing your data model and choosing +indexes, see the :manual:`Indexes +` section of the Operational +Factors and Data Models guide in the {+mdb-server+} manual. + +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 an Index +--------------- + +MongoDB supports several index types to help query your data. +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-compound-index` +.. - :ref:`php-atlas-search-index` + +List Indexes +------------ + +You can retrieve a list of indexes on a collection by calling the +``MongoDB\Collection::listIndexes()`` method: + +.. literalinclude:: /includes/indexes/indexes.php + :language: php + :start-after: start-list-indexes + :end-before: end-list-indexes + :dedent: + +Remove an Index +--------------- + +You can remove any unused index except the default unique index on the +``_id`` field. + +The following sections provide examples that show how to remove one or +more indexes from a collection. + +Delete a Single Index +~~~~~~~~~~~~~~~~~~~~~ + +Pass the name of an index to the ``MongoDB\Collection::dropIndex()`` +method to remove an index from a collection. + +The following example removes the ``'_title_'`` index from the +``movies`` collection: + +.. literalinclude:: /includes/indexes/indexes.php + :language: php + :start-after: start-remove-index + :end-before: end-remove-index + :dedent: + +.. note:: + + You cannot remove a single field from a compound index. You must + drop the entire index and create a new one to update the indexed + fields. + +Delete All Indexes +~~~~~~~~~~~~~~~~~~ + +You can delete all indexes by calling the +``MongoDB\Collection::dropIndexes()`` method on a collection: + +.. literalinclude:: /includes/indexes/indexes.php + :language: php + :start-after: start-remove-all-indexes + :end-before: end-remove-all-indexes + :dedent: + +The ``dropIndexes()`` method returns information about the number of +indexes removed and a success message. + +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/>`__ diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt new file mode 100644 index 00000000..cd6de01d --- /dev/null +++ b/source/indexes/single-field-index.txt @@ -0,0 +1,96 @@ +.. _php-single-field-index: + +==================== +Single Field Indexes +==================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: index, query, optimization, efficiency + +Overview +-------- + +Single field indexes are indexes with a reference to a single field of a +document in a collection. These indexes improve single field query and +sort performance. They also support :manual:`TTL Indexes ` +that automatically remove documents from a collection after a certain +amount of time or at a specified clock time. + +When creating a single-field index, you must specify the following +details: + +- The field on which to create the index +- The sort order for the indexed values as either ascending or + descending + +.. note:: + + The default ``_id_`` index is an example of a single-field index. + This index is automatically created on the ``_id`` field when a new + collection is created. + +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 Single-Field Index +------------------------- + +Use the ``MongoDB\Collection::createIndex()`` method to create a single +field index. The following example creates an index in ascending order on the +``title`` field: + +.. literalinclude:: /includes/indexes/indexes.php + :start-after: start-index-single + :end-before: end-index-single + :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-single-query + :end-before: end-index-single-query + :language: php + :dedent: + + .. output:: + :visible: false + + {"_id":...,"plot":"A musical comedy duo...", + "genres":["Musical"],...,"title":"Sweethearts",...} + +Additional Information +---------------------- + +To learn more about single-field indexes, see :manual:`Single Field +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/>`__