DOCSP-45202 Index Overview

source/includes/indexes/index-code-examples.rb

@@ -0,0 +1,100 @@
+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 connects to the server
+client = Mongo::Client.new(uri, options)
+
+database = client.use('<database name>')
+collection = database[:<collection name>]
+
+# Single Field
+# start-index-single
+collection.indexes.create_one({ <field name>: 1 })
+# end-index-single
+
+# Compound
+# start-index-compound
+collection.indexes.create_one({ <field name 1>: -1, <field name 2>: 1 })
+# end-index-compound
+
+# Multikey
+# start-index-multikey
+collection.indexes.create_one({ <field name>: 1 })
+# end-index-multikey
+
+# Geospatial
+# start-index-geospatial
+collection.indexes.create_one({ <GeoJSON field name>: '2dsphere' })
+# end-index-geospatial
+
+# Atlas Search
+
+# Create Search Index
+# start-create-search-index
+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
+
+# List Search Indexes
+# start-list-search-indexes
+puts collection.search_indexes.collect(&:to_json)
+# end-list-search-indexes
+
+# Update Search Indexes
+#start-update-search-indexes
+updated_definition = {
+  mappings: {
+    dynamic: false,  
+    fields: { <updated field name>: { type: '<updated field type>' } }
+    }
+}
+
+collection.search_indexes.update_one(updated_definition, name: '<index name>')
+#end-update-search-indexes
+
+# Delete Search Index
+# start-drop-search-index
+collection.search_indexes.drop_one(name: '<index name>')
+# end-drop-search-index
+
+# Text Index
+# start-text
+collection.indexes.create_one({ <field name>: 'text' })
+# end-text
+
+# Create Many
+# start-index-create-many
+collection.indexes.create_many([
+  { key: { <field name 1>: 1 } },
+  { key: { <field name 2>: -1 } },
+])
+# end-index-create-many
+
+# Delete an Index
+# start-drop-single-index
+collection.indexes.drop_one( '<index name>' )
+# end-drop-single-index
+
+# Drops all indexes in the collection.
+# start-drop-all-index
+collection.indexes.drop_all
+# end-drop-all-index
+
+# List an Index
+# start-list-indexes
+puts collection.indexes.collect(&:to_json)
+# end-list-indexes
+
+client.close

source/includes/indexes/index-starter-code.rb

@@ -0,0 +1,19 @@
+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('<database name>')
+collection = database[:<collection name>]
+
+# Start example code here
+
+# End example code here
+
+client.close

source/indexes.txt

@@ -15,7 +15,7 @@ Optimize Queries by Using Indexes
    :values: reference
 
 .. meta::
-   :description: Learn how to use indexes by using the MongoDB Scala Driver.
+   :description: Learn how to use indexes by using the MongoDB Ruby Driver.
    :keywords: query, optimization, efficiency, usage example, code example
 
 .. toctree::
@@ -33,4 +33,262 @@ Overview
 On this page, you can see copyable code examples that show how to manage
 different types of indexes by using the {+driver-long+}.
 
-.. TODO
+To use an example from this page, copy the code example into the sample 
+application or your own application. Be sure to replace all placeholders in the 
+code examples, such as ``<connection string>``, with the relevant values for 
+your MongoDB deployment.
+
+Sample Application
+~~~~~~~~~~~~~~~~~~
+
+You can use the following sample application to test the code on this page. To
+use the sample application, perform the following steps:
+
+1. Ensure you have the {+driver-short+} installed in your project. See the 
+   :ref:`ruby-quick-start-download-and-install` guide to learn more.
+
+#. Copy the following code and paste it into a new ``.rb`` file.
+
+#. Copy a code example from this page and paste it on the specified lines in the
+   file.
+
+.. literalinclude:: /includes/indexes/index-starter-code.rb
+   :language: ruby
+   :emphasize-lines: 15-17
+
+Single Field Index
+------------------
+
+The following example creates an ascending index on the specified field:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-index-single
+   :end-before: end-index-single
+
+To learn more about single field indexes, see the :ref:`ruby-single-field-index`
+guide.
+
+Compound Index
+--------------
+
+The following example creates a compound index on the two specified fields.
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-index-compound
+   :end-before: end-index-compound
+
+To learn more about compound indexes, see the :ref:`ruby-compound-index` guide.
+
+Multikey Index
+--------------
+
+The following example creates a multikey index on the specified array-valued field:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-index-multikey
+   :end-before: end-index-multikey
+
+To learn more about multikey indexes, see the :ref:`ruby-multikey-index` guide.
+
+Geospatial Index
+----------------
+
+The following example creates a 2dsphere index on the specified field that
+contains GeoJSON objects:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-index-geospatial
+   :end-before: end-index-geospatial
+
+For more information on 2dsphere indexes, see the 
+:manual:`2dsphere Indexes </core/indexes/index-types/geospatial/2dsphere/>`
+guide in the {+mdb-server+} manual.
+
+For more information about the GeoJSON type, see the 
+:manual:`GeoJSON Objects </reference/geojson/>` guide in
+the {+mdb-server+} manual.
+
+Atlas Search Index Management
+-----------------------------
+
+The following sections contain code examples that describe how to manage 
+Atlas Search indexes.
+
+To learn more about search indexes, see the :ref:`ruby-atlas-search-index` guide.
+
+Create Search Index
+~~~~~~~~~~~~~~~~~~~
+
+The following example creates an Atlas Search index on the specified field:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-create-search-index
+   :end-before: end-create-search-index
+   :dedent:
+
+List Search Indexes
+~~~~~~~~~~~~~~~~~~~
+
+The following example prints a list of Atlas Search indexes in the specified 
+collection:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-list-search-indexes
+   :end-before: end-list-search-indexes
+   :dedent:
+
+Update Search Indexes
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example updates an existing Atlas Search index with the specified
+new index definition:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-update-search-indexes
+   :end-before: end-update-search-indexes
+   :dedent:
+
+Delete Search Indexes
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example deletes an Atlas Search index with the specified name:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-drop-search-index
+   :end-before: end-drop-search-index
+   :dedent:
+
+Text Index
+----------
+
+The following example creates a text index on the specified string field:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :start-after: start-text
+   :end-before: end-text
+   :language: ruby
+   :dedent:
+
+.. TODO: To learn more about text indexes, see the :ref:`ruby-text-index`
+.. guide.
+
+Create Many Indexes
+-------------------
+
+The following example creates multiple indexes on the given array of index specifications:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :start-after: start-index-create-many
+   :end-before: end-index-create-many
+   :language: ruby
+   :dedent:
+
+Drop Index
+----------
+
+The following example deletes an index with the specified name:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-drop-single-index
+   :end-before: end-drop-single-index
+
+The following example shows how to delete all indexes in a collection:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-drop-all-index
+   :end-before: end-drop-all-index
+
+List Indexes
+------------
+
+The following example prints a list of all indexes in the specified 
+collection:
+
+.. literalinclude:: /includes/indexes/index-code-examples.rb
+   :language: ruby
+   :start-after: start-list-indexes
+   :end-before: end-list-indexes
+   :dedent:
+
+Index Options
+-------------
+
+The following is a full list of the available options you can add
+when creating indexes. These options mirror the options supported by the
+``createIndex`` command. For more information, see the :manual:`createIndex command 
+</reference/method/db.collection.createIndex/>` in the {+mdb-server+} manual.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 80
+
+   * - Option
+     - Description
+   * - ``:background``
+     - Either ``true`` or ``false``. Tells the index to be created in the background.
+   * - ``:expire_after``
+     - Number of seconds to expire documents in the collection after.
+   * - ``:name``
+     - The name of the index.
+   * - ``:sparse``
+     - Whether the index should be sparse or not, either ``true`` or ``false``.
+   * - ``:storage_engine``
+     - The name of the storage engine for this particular index.
+   * - ``:version``
+     - The index format version to use.
+   * - ``:default_language``
+     - The default language of text indexes.
+   * - ``:language_override``
+     - The field name to use when overriding the default language.
+   * - ``:text_version``
+     - The version format for text index storage.
+   * - ``:weights``
+     - A document specifying fields and weights in text search.
+   * - ``:sphere_version``
+     - The 2d sphere index version.
+   * - ``:bits``
+     - Sets the maximum boundary for latitude and longitude in the 2d index.
+   * - ``:max``
+     - Maximum boundary for latitude and longitude in the 2d index.
+   * - ``:min``
+     - Minimum boundary for latitude and longitude in the 2d index.
+   * - ``:bucket_size``
+     - The number of units within which to group the location values in a geo haystack index.
+   * - ``:partial_filter_expression``
+     - A filter for a partial index.
+   * - ``:hidden``
+     - A Boolean specifying whether the index should be hidden; a hidden index 
+       is one that exists on the collection but will not be used by the query planner.
+   * - ``:commit-quorum``
+     - Specify how many data-bearing members of a replica set, including the primary, must 
+       complete the index builds successfully before the primary marks the indexes as ready. 
+       Potential values are:
+
+       - integer from 0 to the number of members of the replica set
+       - ``“majority”`` indicating that a majority of data bearing nodes must vote
+       - ``“votingMembers”`` which means that all voting data bearing nodes must vote
+
+       For more information, see :manual:`commitQuorom 
+       </reference/method/db.collection.createIndex/#std-label-createIndex-method-commitQuorum>` 
+       in the {+mdb-server+} manual.
+
+API Documentation
+-----------------
+
+To learn more about the methods or objects used in this guide, see the following 
+API documentation:
+
+- `indexes <{+api-root+}/Mongo/Collection.html#indexes-instance_method>`__
+- `create_one <{+api-root+}/Mongo/Index/View.html#create_one-instance_method>`__
+- `drop_one <{+api-root+}/Mongo/Index/View.html#drop_one-instance_method>`__
+- `drop_all <{+api-root+}/Mongo/Index/View.html#drop_all-instance_method>`__