diff --git a/source/includes/indexes/indexes-async.py b/source/includes/indexes/indexes-async.py new file mode 100644 index 00000000..ce63111a --- /dev/null +++ b/source/includes/indexes/indexes-async.py @@ -0,0 +1,198 @@ +# start-index-single +await movies.create_index("title") +# end-index-single + +# start-index-single-collation +from pymongo.collation import Collation + +await movies.create_index("title", collation=Collation(locale='fr_CA')) +# end-index-single-collation + +# start-compound-index +await movies.create_index([("type", pymongo.ASCENDING), ("genre", pymongo.ASCENDING)]) +# end-compound-index + +# start-compound-index-collation +from pymongo.collation import Collation + +await movies.create_index([("type", pymongo.ASCENDING), ("genre", pymongo.ASCENDING)], + collation=Collation(locale='fr_CA')) +# end-compound-index-collation + +# start-index-multikey +result = await movies.create_index("cast") +# end-index-multikey + +# start-index-multikey-collation +from pymongo.collation import Collation + +result = await movies.create_index("cast", collation=Collation(locale='fr_CA')) +# end-index-multikey-collation + +# start-index-text-single +await movies.create_index( + [( "plot", "text" )] +) +# end-index-text-single + +# start-index-text-single-collation +from pymongo.collation import Collation + +await movies.create_index( + [( "plot", "text" )], + collation=Collation(locale='fr_CA') +) +# end-index-text-single-collation + +# start-index-text-multi +from pymongo.collation import Collation + +result = await myColl.create_index( + [("title", "text"), ("genre", "text")], + default_language="english", + weights={ "title": 10, "genre": 3 }, + collation=Collation(locale='fr_CA') +) +# end-index-text-multi + +# start-index-geo +await theaters.create_index( + [( "location.geo", "2dsphere" )] +) +# end-index-geo + +# start-index-geo-collation +from pymongo.collation import Collation + +await theaters.create_index( + [( "location.geo", "2dsphere" )], + collation=Collation(locale='fr_CA')) +# end-index-geo-collation + +# start-index-wildcard +await movies.create_index({ "location.$**": pymongo.ASCENDING }) +# end-index-wildcard + +# start-index-wildcard-collation +await movies.create_index({ "location.$**": pymongo.ASCENDING }, + collation=Collation(locale='fr_CA')) +# end-index-wildcard-collation + +# start-index-unique +await theaters.create_index("theaterId", unique=True) +# end-index-unique + +# start-index-unique-collation +await theaters.create_index("theaterId", unique=True, collation=Collation(locale='fr_CA')) +# end-index-unique-collation + +# start-index-clustered +await sample_mflix.create_collection("movies", clusteredIndex={ + "key": { "_id": 1 }, + "unique": True +}) +# end-index-clustered + +# start-remove-index +await movies.drop_index("_title_") +# end-remove-index + +# start-create-search-index +index = { + "definition": { + "mappings": { + "dynamic": True + } + }, + "name": "", +} + +await collection.create_search_index(index) +# end-create-search-index + +# start-create-vector-search-index +from pymongo.operations import SearchIndexModel + +search_index_model = SearchIndexModel( + definition={ + "fields": [ + { + "type": "vector", + "numDimensions": , + "path": "", + "similarity": "" + } + ] + }, + name="my_vector_index", + type="vectorSearch", +) + +indexes = [search_idx, vector_idx] + +await collection.create_search_indexes(models=indexes) +# end-create-search-indexes + +# start-list-search-indexes +results = await (await collection.list_search_indexes()).to_list() + +async for index in results: + print(index) +# end-list-search-indexes + +# start-update-search-indexes +new_index_definition = { + "mappings": { + "dynamic": False + } +} + +await collection.update_search_index("my_index", new_index) +# end-update-search-indexes + +# start-update-vector-search-indexes +new_index_definition = { + "fields": [ + { + "type": "vector", + "numDimensions": 1536, + "path": "", + "similarity": "euclidean" + }, + ] +} + +await collection.update_search_index("my_vector_index", new_index_definition) +# end-update-vector-search-indexes + +# start-delete-search-indexes +await collection.drop_search_index("my_index") +# end-delete-search-indexes \ No newline at end of file diff --git a/source/indexes.txt b/source/indexes.txt index 8e56da5c..f19e37bb 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -82,13 +82,28 @@ specific clock time. The ``_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. -The following example creates an index in ascending order on the ``title`` field: +The following example creates an index in ascending order on the ``title`` field. Select +the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :start-after: start-index-single - :end-before: end-index-single - :language: python - :copyable: +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-single + :end-before: end-index-single + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-single + :end-before: end-index-single + :language: python + :copyable: The following is an example of a query that is covered by the index created in the preceding code example: @@ -107,12 +122,29 @@ Compound Indexes :manual:`Compound indexes ` hold references to multiple fields within a collection's documents, improving query and sort performance. -The following example creates a compound index on the ``type`` and ``genre`` fields: +The following example creates a compound index on the ``type`` and ``genre`` fields. +Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding +code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-compound-index - :end-before: end-compound-index +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-compound-index + :end-before: end-compound-index + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-compound-index + :end-before: end-compound-index + :language: python + :copyable: The following is an example of a query that uses the index created in the preceding code example: @@ -132,14 +164,31 @@ Multikey Indexes (Indexes on Array Fields) **Multikey indexes** are indexes that improve performance for queries that specify a field with an index that contains an array value. You can define a multikey index by using the -same syntax as a single field or compound index. +same syntax as a single field or compound index. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: -The following example creates a multikey index on the ``cast`` field: +The following example creates a multikey index on the ``cast`` field. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-multikey - :end-before: end-index-multikey +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-multikey + :end-before: end-index-multikey + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-multikey + :end-before: end-index-multikey + :language: python + :copyable: The following is an example of a query that uses the index created in the preceding code example: @@ -202,21 +251,53 @@ and the `create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ methods to create Atlas Search indexes or Atlas Vector Search indexes. -The following code example shows how to create a single Atlas Search index: +The following code example shows how to create a single Atlas Search index. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-search-index - :end-before: end-create-search-index +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-create-search-index + :end-before: end-create-search-index + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-create-search-index + :end-before: end-create-search-index + :language: python + :copyable: The following code example shows how to create a single Atlas Vector Search index by using the `SearchIndexModel <{+api-root+}pymongo/operations.html#pymongo.operations.SearchIndexModel>`__ -object: +object. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-vector-search-index - :end-before: end-create-vector-search-index +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-create-vector-search-index + :end-before: end-create-vector-search-index + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-create-vector-search-index + :end-before: end-create-vector-search-index + :language: python + :copyable: You can use the `create_search_indexes() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.create_search_indexes>`__ method to create multiple indexes. These indexes can be Atlas Search or @@ -224,12 +305,28 @@ Vector Search indexes. The ``create_search_indexes()`` method takes a list of ``SearchIndexModel`` objects that correspond to each index you want to create. The following code example shows how to create an Atlas Search index and an Atlas -Vector Search index: +Vector Search index. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab +to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-create-search-indexes - :end-before: end-create-search-indexes +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-create-search-indexes + :end-before: end-create-search-indexes + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-create-search-indexes + :end-before: end-create-search-indexes + :language: python + :copyable: .. _pymongo-atlas-search-index-list: @@ -242,13 +339,28 @@ method to get information about the Atlas Search and Vector Search indexes of a collection. The following code example shows how to print a list of the search indexes of -a collection: +a collection. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see +the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-list-search-indexes - :end-before: end-list-search-indexes +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-list-search-indexes + :end-before: end-list-search-indexes + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-list-search-indexes + :end-before: end-list-search-indexes + :language: python + :copyable: .. _pymongo-atlas-search-index-update: @@ -259,7 +371,8 @@ You can use the `update_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.update_search_index>`__ method to update an Atlas Search or Vector Search index. -The following code example shows how to update an Atlas Search index: +The following code example shows how to update an Atlas Search index. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: .. literalinclude:: /includes/indexes/indexes.py :language: python @@ -267,13 +380,28 @@ The following code example shows how to update an Atlas Search index: :start-after: start-update-search-indexes :end-before: end-update-search-indexes -The following code example shows how to update an Atlas Vector Search index: +The following code example shows how to update an Atlas Vector Search index. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-update-vector-search-indexes - :end-before: end-update-vector-search-indexes +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-update-vector-search-indexes + :end-before: end-update-vector-search-indexes + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-update-vector-search-indexes + :end-before: end-update-vector-search-indexes + :language: python + :copyable: .. _pymongo-atlas-search-index-drop: @@ -284,13 +412,28 @@ You can use the `drop_search_index() <{+api-root+}pymongo/collection.html#pymongo.collection.Collection.drop_search_index>`__ method to remove an Atlas Search or Vector Search index. -The following code shows how to delete a search index from a collection: +The following code shows how to delete a search index from a collection. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :dedent: - :start-after: start-delete-search-indexes - :end-before: end-delete-search-indexes +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-delete-search-indexes + :end-before: end-delete-search-indexes + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-delete-search-indexes + :end-before: end-delete-search-indexes + :language: python + :copyable: .. _pymongo-text-index: @@ -312,12 +455,28 @@ language as an option when creating the index. Text Index on a Single Field ```````````````````````````` -The following example creates a text index on the ``plot`` field: +The following example creates a text index on the ``plot`` field. Select the +:guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-single - :end-before: end-index-text-single +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-text-single + :end-before: end-index-text-single + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-text-single + :end-before: end-index-text-single + :language: python + :copyable: The following is an example of a query that uses the index created in the preceding code example: @@ -336,12 +495,28 @@ index. A text search runs on all the text fields within the compound index. The following example creates a compound text index for the ``title`` and ``genre`` -fields: +fields. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-text-multi - :end-before: end-index-text-multi +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-text-multi + :end-before: end-index-text-multi + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-text-multi + :end-before: end-index-text-multi + :language: python + :copyable: For more information, see :manual:`Compound Text Index Restrictions ` and @@ -391,12 +566,28 @@ database is a GeoJSON Point object that describes the coordinates of the theater Create a Geospatial Index ````````````````````````` -The following example creates a ``2dsphere`` index on the ``location.geo`` field: +The following example creates a ``2dsphere`` index on the ``location.geo`` field. Select +the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-geo - :end-before: end-index-geo +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-geo + :end-before: end-index-geo + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-geo + :end-before: end-index-geo + :language: python + :copyable: MongoDB also supports ``2d`` indexes for calculating distances on a Euclidean plane and for working with the "legacy coordinate pairs" syntax used in MongoDB 2.2 and earlier. For more information, @@ -418,12 +609,28 @@ of a collection. To create a unique index, perform the following steps: Create a Unique Index ````````````````````` -The following example creates a descending unique index on the ``theaterId`` field: +The following example creates a descending unique index on the ``theaterId`` field. Select +the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-unique - :end-before: end-index-unique +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-unique + :end-before: end-index-unique + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-unique + :end-before: end-index-unique + :language: python + :copyable: For more information, see the :manual:`Unique Indexes ` guide in the {+mdb-server+} manual. @@ -440,12 +647,29 @@ Create a Wildcard Index ``````````````````````` The following example creates an ascending wildcard index on all -values of the ``location`` field, including values nested in subdocuments and arrays: - -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-wildcard - :end-before: end-index-wildcard +values of the ``location`` field, including values nested in subdocuments and arrays. +Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the corresponding +code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-wildcard + :end-before: end-index-wildcard + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-wildcard + :end-before: end-index-wildcard + :language: python + :copyable: For more information, see the :manual:`Wildcard Indexes` page in the {+mdb-server+} manual. @@ -466,12 +690,28 @@ Create a Clustered Index ```````````````````````` The following example creates a clustered index on the ``_id`` field in -a new ``movie_reviews`` collection: +a new ``movie_reviews`` collection. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-index-clustered - :end-before: end-index-clustered +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-index-clustered + :end-before: end-index-clustered + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-index-clustered + :end-before: end-index-clustered + :language: python + :copyable: For more information, see the :manual:`Clustered Index ` @@ -496,12 +736,28 @@ Pass an instance of an index or the index name to the ``drop_index()`` method to remove an index from a collection. The following example removes an index with the name ``"_title_"`` from the ``movies`` -collection: +collection. Select the :guilabel:`Synchronous` or :guilabel:`Asynchronous` tab to see the +corresponding code: -.. literalinclude:: /includes/indexes/indexes.py - :language: python - :start-after: start-remove-index - :end-before: end-remove-index +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. literalinclude:: /includes/indexes/indexes.py + :start-after: start-remove-index + :end-before: end-remove-index + :language: python + :copyable: + + .. tab:: Asynchronous + :tabid: async + + .. literalinclude:: /includes/indexes/indexes-async.py + :start-after: start-remove-index + :end-before: end-remove-index + :language: python + :copyable: .. note:: @@ -513,18 +769,43 @@ Remove All Indexes ~~~~~~~~~~~~~~~~~~ Starting with MongoDB 4.2, you can drop all indexes by calling the -``drop_indexes()`` method on your collection: +``drop_indexes()`` method on your collection. Select the :guilabel:`Synchronous` or +:guilabel:`Asynchronous` tab to see the corresponding code: + +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python -.. code-block:: java + collection.drop_indexes() + + .. tab:: Asynchronous + :tabid: async - collection.drop_indexes() + .. code-block:: python + + await collection.drop_indexes() For earlier versions of MongoDB, pass ``"*"`` as a parameter to your call to ``drop_index()`` on your collection: -.. code-block:: java +.. tabs:: + + .. tab:: Synchronous + :tabid: sync + + .. code-block:: python + + collection.drop_index("*") + + .. tab:: Asynchronous + :tabid: async + + .. code-block:: python - collection.drop_index("*") + await collection.drop_index("*") Troubleshooting ---------------