DOCSP-34184: Atlas Search indexes (#99)

(cherry picked from commit d6aa17f)

Author: norareidy

snooty.toml

@@ -9,7 +9,8 @@ intersphinx = [ "https://www.mongodb.com/docs/manual/objects.inv",
 toc_landing_pages = [
     "/fundamentals/connections",
     "/fundamentals/crud",
-    "/usage-examples"
+    "/usage-examples",
+    "/fundamentals/indexes"
     ]
 
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/fundamentals/indexes.txt

@@ -4,12 +4,23 @@
 Indexes
 =======
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, search performance
+
 .. contents:: On this page
    :local:
    :backlinks: none
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   /fundamentals/indexes/atlas-search-indexes
+
 Overview
 --------
 
@@ -298,8 +309,8 @@ in the compound index.
 .. tip:: Atlas Full Text Search
 
    Text indexes are different from Atlas full text search indexes. To
-   learn more about Atlas Search indexes, see the :atlas:`Atlas Search
-   documentation </atlas-search/>`.
+   learn more about Atlas Search indexes, see the :ref:`rust-atlas-search-indexes`
+   guide.
 
 Example
 ```````

source/fundamentals/indexes/atlas-search-indexes.txt

@@ -0,0 +1,288 @@
+.. _rust-atlas-search-indexes:
+
+====================
+Atlas Search Indexes
+====================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, full text, atlas deployment
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to create and manage **Atlas Search indexes**. These indexes
+allow you to use MongoDB's Atlas Search feature to perform fast, full-text searches
+on data stored in an Atlas cluster. An Atlas Search index configures the behavior of Atlas
+Search by specifying which fields to index, how these fields are indexed, and other optional
+settings. To learn more about Atlas Search indexes, see the :atlas:`Atlas Search documentation
+</atlas-search/>`.
+
+This guide explains how to perform the following actions to manage your Atlas Search indexes:
+
+- :ref:`rust-create-model`
+- :ref:`rust-create-search-index`
+- :ref:`rust-create-search-indexes`
+- :ref:`rust-list-search-index`
+- :ref:`rust-update-search-index`
+- :ref:`rust-drop-search-index`
+
+.. note:: 
+
+   The examples in this guide access the ``posts`` collection in the ``sample_training``
+   database, which is one of the Atlas sample datasets. For instructions on importing
+   the Atlas sample data, see :atlas:`Load Sample Data </sample-data>` in the Atlas
+   documentation.
+
+.. _rust-create-model:
+
+Create a Search Index Model
+---------------------------
+
+To create an Atlas Search index, you must first build a ``SearchIndexModel`` instance
+that sets your index specifications. To begin building a ``SearchIndexModel`` instance,
+call the ``SearchIndexModel::builder()`` method.
+
+.. note:: Instantiating Models
+   
+   The {+driver-short+} implements the Builder design pattern for the
+   creation of many different types, including ``SearchIndexModel``. You
+   can use the ``builder()`` method to construct an instance of each type
+   by chaining option builder methods.
+
+The {+driver-short+} provides the following ``SearchIndexModel`` builder methods:
+
+- ``definition()``, which accepts a BSON document parameter and sets your index definition
+- ``name()``, which accepts a string parameter and sets your index name 
+
+The BSON document that you pass to the ``definition()`` builder method must include
+the ``mappings`` field. To automatically index all supported fields in your collection,
+enable dynamic mappings by setting the ``mappings.dynamic`` nested field to ``true``. To
+index only specified fields, enable static mappings by setting the ``mappings.dynamic``
+nested field to ``false`` and including a list of fields you want to index.
+
+.. tip:: Atlas Search Field Mappings
+
+   To learn more about Atlas Search field mappings, see :atlas:`Define Field Mappings
+   </atlas-search/define-field-mappings/>` in the Atlas documentation.
+
+Example
+~~~~~~~
+
+The following example creates specifications for a index named ``example_index`` in a
+``SearchIndexModel`` instance. The code sets a static mapping to index only the ``body``
+and ``date`` fields:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/indexes.rs
+   :start-after: begin-atlas-model
+   :end-before: end-atlas-model
+   :language: rust
+   :dedent:
+
+.. _rust-create-search-index:
+
+Create a Search Index
+---------------------
+
+You can create an Atlas Search index on a collection by calling the ``create_search_index()``
+method on a ``Collection`` instance. This method accepts the following parameters:
+
+- Index model, specified in a ``SearchIndexModel`` instance
+- Index options, specified in a `CreateSearchIndexOptions
+  <{+api+}/options/struct.CreateSearchIndexOptions.html>`__ instance
+
+Example
+~~~~~~~
+
+The following example creates an Atlas Search index on the ``posts`` collection.
+The code creates a ``SearchIndexModel`` that sets the index name and enables dynamic
+mapping. Then, the code passes the ``SearchIndexModel`` instance to the ``create_search_index()``
+method to create the Atlas Search index:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/indexes.rs
+      :start-after: begin-atlas-create-one
+      :end-before: end-atlas-create-one
+      :language: rust
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Created Atlas Search index:
+      "example_index"
+
+.. _rust-create-search-indexes:
+
+Create Multiple Search Indexes
+------------------------------
+
+You can create multiple Atlas Search indexes at once by calling the ``create_search_indexes()``
+method on a ``Collection`` instance. This method accepts the following parameters:
+
+- List of index models, specified as a vector of ``SearchIndexModel`` instances
+- Index options, specified in a ``CreateSearchIndexOptions`` instance
+
+Example
+~~~~~~~
+
+The following example creates two Atlas Search indexes named ``dynamic_index`` and
+``static_index`` on the ``posts`` collection. The code creates ``SearchIndexModel``
+instances for each index that specify the index names and definitions. Then, the code
+passes these models as a vector to the ``create_search_indexes()`` method and creates
+the indexes:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/indexes.rs
+      :start-after: begin-atlas-create-many
+      :end-before: end-atlas-create-many
+      :language: rust
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      Created Atlas Search indexes:
+      ["dynamic_index", "static_index"]
+
+.. _rust-list-search-index:
+
+List Search Indexes
+-------------------
+
+You can access information about a collection's existing Atlas Search indexes
+by calling the ``list_search_indexes()`` method on the collection. This
+method accepts the following parameters:
+
+- Name of the index to retrieve information about
+- Aggregation options, specified in an `AggregateOptions
+  <{+api+}/options/struct.AggregateOptions.html>`__ instance
+- Index options, specified in a `ListSearchIndexOptions
+  <{+api+}/options/struct.ListSearchIndexOptions.html>`__ instance
+
+Example
+~~~~~~~
+
+The following example accesses information about the Atlas Search indexes created
+in the :ref:`rust-create-search-indexes` section of this page. The code calls the
+``list_search_indexes()`` method and passes a value of ``None`` for each parameter,
+which instructs the driver to return information about all Atlas Search indexes with
+default options. Then, the code outputs the search indexes:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/fundamentals/code-snippets/indexes.rs
+      :start-after: begin-atlas-list
+      :end-before: end-atlas-list
+      :language: rust
+      :dedent:
+
+   .. output::
+      :language: console
+      :visible: false
+
+      { "id": "...", "name": "dynamic_index", "status": "READY", "queryable": true, "latestDefinitionVersion": {...},
+      "latestDefinition": { "mappings": { "dynamic": true } }, "statusDetail": [...] }
+
+      { "id": "...", "name": "static_index", "status": "READY", "queryable": true, "latestDefinitionVersion": {...},
+      "latestDefinition": { "mappings": { "dynamic": false, "fields": { "title": { "type": "string" } } } },
+      "statusDetail": [...] }
+
+.. tip:: 
+
+   To learn more about iterating through a cursor, see the :ref:`rust-cursor-guide` guide.
+
+.. _rust-update-search-index:
+
+Update a Search Index
+---------------------
+
+You can update an Atlas Search index by calling the ``update_search_index()``
+method on a ``Collection`` instance. This method accepts the following parameters:
+
+- Name of the index to update
+- Modified index definition document
+- Index options, specified in an `UpdateSearchIndexOptions
+  <{+api+}/options/struct.UpdateSearchIndexOptions.html>`__ instance
+
+Example
+~~~~~~~
+
+The following example updates the Atlas Search index named ``static_index``
+created in the :ref:`rust-create-search-indexes` section of this page. The code
+creates a new index definition document that instructs the index to use dynamic
+mappings instead of static mappings. Then, the code calls the ``update_search_index()``
+method to update the index:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/indexes.rs
+   :start-after: begin-atlas-update
+   :end-before: end-atlas-update
+   :language: rust
+   :dedent:
+
+.. _rust-drop-search-index:
+
+Delete a Search Index
+---------------------
+
+You can delete an Atlas Search index by calling the ``delete_search_index()``
+method on a ``Collection`` instance. This method accepts the following parameters:
+
+- Name of the index to delete
+- Index options, specified in a `DropSearchIndexOptions
+  <{+api+}/options/struct.DropSearchIndexOptions.html>`__ instance
+
+Example
+~~~~~~~
+
+The following example deletes the Atlas Search index named ``example_index``
+created in the :ref:`rust-create-search-index` section of this page. The code
+passes the index name to the ``delete_search_index()`` method to delete the index:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/indexes.rs
+   :start-after: begin-atlas-drop
+   :end-before: end-atlas-drop
+   :language: rust
+   :dedent:
+   
+Additional Information
+----------------------
+
+To learn about other indexes you can create by using the {+driver-short+}, see the
+:ref:`rust-indexes` guide.
+
+To learn more about Atlas Search, see the following Atlas documentation:
+
+- :atlas:`Atlas Search Best Practices </atlas-search/best-practices/>`
+- :atlas:`Tune Atlas Search Performance </atlas-search/performance/>`
+- :atlas:`Atlas Search M0, M2, and M5 Limitations </atlas-search/limitations/>`
+- :atlas:`FAQ: Atlas Search </atlas-search/faq/>`
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the methods and types mentioned in this
+guide, see the following API documentation:
+
+- `create_search_index() <{+api+}/struct.Collection.html#method.create_search_index>`__
+- `SearchIndexModel <{+api+}/struct.SearchIndexModel.html>`__
+- `create_search_indexes() <{+api+}/struct.Collection.html#method.create_search_indexes>`__
+- `list_search_indexes() <{+api+}/struct.Collection.html#method.list_search_indexes>`__
+- `update_search_index() <{+api+}/struct.Collection.html#method.create_search_index>`__
+- `drop_search_index() <{+api+}/struct.Collection.html#method.create_search_index>`__