DOCSP-45206 Atlas Search Index

source/includes/indexes/atlas-search-index.rb

@@ -0,0 +1,96 @@
+require 'mongo'
+
+# Replace the placeholders with your credentials
+uri = "<connection string>"
+
+# Sets the server_api field of the options object to Stable API version 1
+options = { server_api: { version: "1" }}
+
+# Creates a new client and connect to the server
+client = Mongo::Client.new(uri, options)
+
+database = client.use('sample_mflix')
+collection = database[:movies]
+
+# start-create-search-index
+# Creates indexes on all dynamically indexable fields with a default index name
+collection.search_indexes.create_one(
+  { mappings: { dynamic: true } } 
+)
+
+# Creates an index on the specified field with the specified index name
+index-definition = {
+  mappings: {
+    dynamic: false,  
+    fields: { 
+      <field name>: {type: '<field type>'}
+    }
+  }
+}
+collection.search_indexes.create_one(index_definition, name: '<index name>')
+# end-create-search-index
+
+# start-create-multiple-search-indexes
+index_spec_1 = {
+  name: '<index 1 name>',
+  definition: {
+    mappings: {
+      dynamic: false,  
+      fields: { 
+        <field name>: {type: '<field type>'}
+      }
+    }
+  }
+}
+
+index_spec_2 = {
+  name: '<index 2 name>',
+  definition: {
+    mappings: {
+      dynamic: false,  
+      fields: { 
+        <field name>: {type: '<field type>'}
+      }
+    }
+  }
+}
+
+collection.search_indexes.create_many([index_spec_1, index_spec_2])
+# end-create-multiple-search-indexes
+
+# start-update-search-indexes
+updated_definition = {
+  mappings: {
+    dynamic: false,  
+    fields: { <updated field name>: { type: '<updated field type>' } }
+    }
+}
+
+# Specifies the index to update by using the index name
+collection.search_indexes.update_one(updated_definition, name: '<index name>')
+
+# Specifies the index to update by using the index id
+collection.search_indexes.update_one(updated_definition, id: <index id>)
+# end-update-search-indexes
+
+# start-drop-search-index
+# Specifies the index to delete by using the index name
+collection.search_indexes.drop_one(name: '<index name>')
+
+# Specifies the index to delete by using the index id
+collection.search_indexes.drop_one(id: <index id>)
+# end-drop-search-index
+
+# start-list-entire-spec
+puts collection.search_indexes.collect(&:to_json)
+# end-list-entire-spec
+
+# start-list-certain-elements
+collection.search_indexes.each do |index_spec|
+  p index_spec['id']
+  p index_spec['name']
+  p index_spec['status']
+  p index_spec['queryable']
+  p index_spec['latestDefinition']
+end
+# end-list-certain-elements

source/indexes.txt

@@ -23,9 +23,9 @@ Optimize Queries by Using Indexes
    :maxdepth: 1
 
    Single Field </indexes/single-field-index>
+   Atlas Search </indexes/atlas-search-index>
 ..   Compound </indexes/compound-index>
 ..   Multikey </indexes/multikey-index>
-..   Atlas Search </indexes/atlas-search-index>
 
 Overview
 --------

source/indexes/atlas-search-index.txt

@@ -0,0 +1,127 @@
+.. _ruby-atlas-search-index:
+
+====================
+Atlas Search Indexes
+====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: index, query, optimization, efficiency
+
+Overview
+--------
+
+:atlas:`Atlas Search </atlas-search>` enables you to perform full-text searches on
+collections hosted on MongoDB Atlas. With Atlas Search indexes, you can specify the 
+behavior of the search and which fields to index.
+
+You can call the following methods to manage you Atlas Search indexes:
+
+- ``search_indexes#create_one``
+- ``search_indexes#create_many``
+- ``search_indexes#update_one``
+- ``search_indexes#drop_one``
+
+The following sections provide code examples that demonstrate how to use
+each of the preceding commands.
+
+.. _ruby-atlas-search-index-create:
+
+Create a Search Index
+---------------------
+
+To create one or more Atlas Search indexes, use the ``search_indexes#create_one`` 
+or the ``search_indexes#create_many`` method. Both methods return immediately,
+while the indexes are asynchronously created in the background.
+
+The following code example shows how to create an Atlas Search index by providing
+an index definition and an optional name for the index:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-create-search-index
+   :end-before: end-create-search-index
+   :emphasize-lines: 15
+
+You can use ``search_indexes#create_many`` to create multiple Atlas Search indexes by 
+providing an array of index specifications. Each index specification should include a definition 
+key, which defines the index, and a name key to specify the index name. The following 
+code example shows how to create multiple search indexes:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-create-multiple-search-indexes
+   :end-before: end-create-multiple-search-indexes
+   :emphasize-lines: 25
+
+For longer index definitions, it is helpful to define the index definitions outside 
+of the method call. To learn more about the syntax of index definitions, see the 
+:atlas:`Review Atlas Search Index Syntax </atlas-search/index-definitions>` 
+guide in the Atlas manual.
+
+Update a Search Index
+---------------------
+
+To update an Atlas Search index, use the ``search_indexes#update_one`` method.
+
+To update an index, you must provide a new index definition. You must specify
+the index you want to update by using either the ``name`` or ``id`` of the index. 
+The following code shows how to update a search index:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-update-search-indexes
+   :end-before: end-update-search-indexes
+
+Delete a Search Index
+---------------------
+
+To delete an Atlas Search index, use the ``search_indexes#drop_one`` method.
+
+To delete an index, you must provide the ``id`` or ``name`` of the index. The following 
+code shows how to delete a search index from a collection:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-drop-search-index
+   :end-before: end-drop-search-index
+
+List Search Indexes
+-------------------
+
+You can use the ``search_indexes`` object to list the entire index specification 
+of each index:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-list-entire-spec
+   :end-before: end-list-entire-spec
+
+To list individual fields in the index specification for each index, iterate
+over the ``search_indexes`` object:
+
+.. literalinclude:: /includes/indexes/atlas-search-index.rb
+   :language: ruby
+   :start-after: start-list-certain-elements
+   :end-before: end-list-certain-elements
+
+Additional Information
+----------------------
+
+To learn more about MongoDB Atlas Search, see the 
+:atlas:`Atlas Search </atlas-search/atlas-search-overview/>` documentation.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the {+driver-short+} methods used in this guide, see the 
+following API documentation: