diff --git a/source/includes/usage-examples/index-code-examples.php b/source/includes/usage-examples/index-code-examples.php new file mode 100644 index 00000000..4dee0dc4 --- /dev/null +++ b/source/includes/usage-examples/index-code-examples.php @@ -0,0 +1,101 @@ +sample_db; +$collection = $database->sample_coll; + +// start-to-json +function toJSON(object $document): string +{ + return MongoDB\BSON\Document::fromPHP($document)->toRelaxedExtendedJSON(); +} +// end-to-json + +// start-single-field +$indexName = $collection->createIndex(['' => 1]); +// end-single-field + +// start-compound +$indexName = $collection->createIndex( + ['' => 1, '' => 1] +); +// end-compound + +// start-multikey +$indexName = $collection->createIndex(['' => 1]); +// end-multikey + +// start-search-create +$indexName = $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => ''] +); +// end-search-create + +// start-search-list +foreach ($collection->listSearchIndexes() as $indexInfo) { + echo toJSON($indexInfo) , PHP_EOL; +} +// end-search-list + +// start-search-update +$collection->updateSearchIndex( + '', + ['mappings' => [ + 'dynamic' => false, + 'fields' => [ + '' => [ + 'type' => 'string', + 'analyzer' => 'lucene.standard' + ] + ] + ]] + ); +// end-search-update + +// start-search-delete +$collection->dropSearchIndex(''); +// end-search-delete + +// start-text +$indexName = $collection->createIndex(['' => 'text']); +// end-text + +// start-geo +$indexName = $collection->createIndex( + [ '' => '2dsphere'] +); +// end-geo + +// start-unique +$indexName = $collection->createIndex(['' => 1], ['unique' => true]); +// end-unique + +// start-wildcard +$indexName = $collection->createIndex(['$**' => 1]); +// end-wildcard + +// start-clustered +$options = [ + 'clusteredIndex' => [ + 'key' => ['_id' => 1], + 'unique' => true + ] +]; + +$database->createCollection('', $options); +// end-clustered + +// start-list +foreach ($collection->listIndexes() as $indexInfo) { + echo $indexInfo; +} +// end-list + +// start-remove +$collection->dropIndex(''); +// end-remove \ No newline at end of file diff --git a/source/includes/usage-examples/sample-app-intro.rst b/source/includes/usage-examples/sample-app-intro.rst new file mode 100644 index 00000000..cee5f2d7 --- /dev/null +++ b/source/includes/usage-examples/sample-app-intro.rst @@ -0,0 +1,10 @@ +Sample Application +~~~~~~~~~~~~~~~~~~ + +You can use the following sample application to test the code examples on this +page. To use the sample application, perform the following steps: + +1. Ensure you have the {+php-library+} installed in your project. +#. Copy the following code and paste it into a new ``.php`` file. +#. Copy a code example from this page and paste it on the specified + lines in the file. diff --git a/source/includes/usage-examples/sample-app.php b/source/includes/usage-examples/sample-app.php new file mode 100644 index 00000000..f9d2cb83 --- /dev/null +++ b/source/includes/usage-examples/sample-app.php @@ -0,0 +1,12 @@ +selectCollection('', ''); + +// Start example code here + +// End example code here diff --git a/source/index.txt b/source/index.txt index 72d8b53b..b4b4841a 100644 --- a/source/index.txt +++ b/source/index.txt @@ -14,6 +14,7 @@ MongoDB PHP Library /read /write /aggregation + /indexes /tutorial /upgrade /reference diff --git a/source/indexes.txt b/source/indexes.txt new file mode 100644 index 00000000..cd9fa904 --- /dev/null +++ b/source/indexes.txt @@ -0,0 +1,299 @@ +.. _php-indexes: + +================================= +Optimize Queries by Using Indexes +================================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :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 + +Overview +-------- + +On this page, you can see copyable code examples that show how to manage +different types of indexes by using the {+php-library+}. + +.. .. tip:: +.. +.. To learn more about working with indexes, see the :ref:`php-work-indexes` +.. guide. To learn more about any of the indexes shown on this page, see the link +.. provided in each section. + +To use an example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Make sure to set the ``MONGODB_URI`` environment variable to the +connection string for your MongoDB deployment, and replace the +```` and ```` placeholders with values for your +target namespace. + +.. _php-index-sample: + +.. include:: /includes/usage-examples/sample-app-intro.rst + +.. literalinclude:: /includes/usage-examples/sample-app.php + :language: php + :copyable: + :linenos: + :emphasize-lines: 10-12 + +Some examples use the ``toJSON()`` function to represent change events, which are BSON +documents, as Extended JSON. To use this function, paste the following code into your +application file: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :language: php + :dedent: + :start-after: start-to-json + :end-before: end-to-json + +Single Field Index +------------------ + +The following example creates an ascending index on the specified field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-single-field + :end-before: end-single-field + :language: php + :copyable: + :dedent: + +.. To learn more about single field indexes, see the +.. :ref:`php-single-field-index` guide. + +Compound Index +-------------- + +The following example creates a compound index of two ascending indexes +on the specified fields: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-compound + :end-before: end-compound + :language: php + :copyable: + :dedent: + +.. To learn more about compound indexes, see the :ref:`php-compound-index` guide. + +Multikey Index +-------------- + +The following example creates an ascending multikey index on the +specified array-valued field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-multikey + :end-before: end-multikey + :language: php + :copyable: + :dedent: + +.. TODO To learn more about multikey indexes, see the :ref:`php-multikey-index` +.. guide. + +Geospatial Index +---------------- + +The following example creates a 2dsphere index on the specified field +that has GeoJSON object values: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-geo + :end-before: end-geo + :language: php + :copyable: + :dedent: + +To learn more about the GeoJSON data type, see :manual:`GeoJSON Objects +` in the {+mdb-server+} manual. + +.. TODO: To learn more about geospatial indexes, see the :ref:`php-geospatial-index` +.. guide. + +Unique Index +------------ + +The following example creates an ascending unique index on the specified +field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-unique + :end-before: end-unique + :language: php + :copyable: + :dedent: + +.. TODO: To learn more about unique indexes, see the :ref:`php-unique-index` +.. guide. + +Wildcard Index +-------------- + +The following example creates an ascending wildcard index on the +collection: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-wildcard + :end-before: end-wildcard + :language: php + :copyable: + :dedent: + +.. TODO: To learn more about wildcard indexes, see the :ref:`php-wildcard-index` +.. guide. + +Clustered Index +--------------- + +You can create a clustered index when creating a new collection in a +specified database. The following example creates a new collection with an +ascending clustered index on the ``_id`` field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-clustered + :end-before: end-clustered + :language: php + :copyable: + :dedent: + +.. TODO: To learn more about clustered indexes, see the :ref:`php-clustered-index` +.. guide. + +Text Index +---------- + +The following example creates a text index on the specified string field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-text + :end-before: end-text + :language: php + :copyable: + :dedent: + +.. TODO: To learn more about text indexes, see the :ref:`php-text-index` +.. guide. + +List Indexes +------------ + +The following example prints a list of indexes in the +specified collection: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-list + :end-before: end-list + :language: php + :copyable: + :dedent: + +Delete an Index +--------------- + +The following example deletes an index with the specified name: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-remove + :end-before: end-remove + :language: php + :copyable: + :dedent: + +.. TODO: To learn more about removing indexes, see :ref:`php-indexes-remove` +.. in the Work with Indexes guide. + +Atlas Search Index Management +----------------------------- + +The following sections contain code examples that describe how to manage +:atlas:`Atlas Search indexes `. + +.. note:: Search Index Management is Asynchronous + + The {+php-library+} manages Atlas Search indexes asynchronously. The + library methods described in the following sections return the server + response immediately, but the changes to your Search indexes take + place in the background and might not complete until some time later. + +.. To learn more about Atlas Search indexes, see the :ref:`php-atlas-search-index` +.. guide. + +Create Search Index +~~~~~~~~~~~~~~~~~~~ + +The following example creates an Atlas Search index on the specified field: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-search-create + :end-before: end-search-create + :language: php + :copyable: + :dedent: + +.. To learn more about creating search indexes, see the +.. :ref:`php-atlas-search-index-create` guide. + +List Search Indexes +~~~~~~~~~~~~~~~~~~~ + +The following example prints a list of Atlas Search indexes in the +specified collection: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-search-list + :end-before: end-search-list + :language: php + :copyable: + :dedent: + +.. To learn more about listing search indexes, see the :ref:`php-atlas-search-index-list` +.. guide. + +Update Search Indexes +~~~~~~~~~~~~~~~~~~~~~ + +The following example updates an existing Atlas Search index with the specified +new index definition: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-search-update + :end-before: end-search-update + :language: php + :copyable: + :dedent: + +.. To learn more about updating search indexes, see the :ref:`php-atlas-search-index-update` +.. guide. + +Delete Search Indexes +~~~~~~~~~~~~~~~~~~~~~ + +The following example deletes an Atlas Search index with the specified name: + +.. literalinclude:: /includes/usage-examples/index-code-examples.php + :start-after: start-search-delete + :end-before: end-search-delete + :language: php + :copyable: + :dedent: + +.. To learn more about deleting search indexes, see the :ref:`php-atlas-search-index-drop` +.. guide. \ No newline at end of file