From e8badd1c81ce38c999e34a94d27076c02a68f954 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 19 Dec 2024 16:37:13 -0500 Subject: [PATCH 1/8] DOCSP-45202 Index Overview --- .../includes/indexes/index-code-examples.rb | 108 ++++++++ source/includes/indexes/index-starter-code.rb | 19 ++ source/indexes.txt | 238 +++++++++++++++++- 3 files changed, 364 insertions(+), 1 deletion(-) create mode 100644 source/includes/indexes/index-code-examples.rb create mode 100644 source/includes/indexes/index-starter-code.rb diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb new file mode 100644 index 00000000..2227fa58 --- /dev/null +++ b/source/includes/indexes/index-code-examples.rb @@ -0,0 +1,108 @@ +require 'mongo' + +# Replace the placeholders with your credentials +uri = "" + +# 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('') +collection = database[:] + +# Single Field +# start-index-single +collection.indexes.create_one({ : 1 }) +# end-index-single + +# Compound +# start-index-compound +collection.indexes.create_one({ : -1, : 1 }) +# end-index-compound + +# Multikey +# start-index-multikey +collection.indexes.create_one({ : 1 }) +# end-index-multikey + +# Geospatial +# start-index-geospatial +collection.indexes.create_one({ : '2dsphere' }) +# end-index-geospatial + +# Atlas Search + +# Create Search Index +# start-create-search-index +index_definition = { + definition: { + mappings: { + dynamic: false, + fields: { + : { + type: '' + } + } + } + } +} +collection.database.command( + createSearchIndexes: '', + indexes: [index_definition] +) +# end-create-search-index + +# List Search Indexes +# start-list-search-indexes +collection.database.command(listSearchIndexes: '') +# end-list-search-indexes + +# Update Search Indexes +#start-update-search-indexes +collection.database.command( + updateSearchIndex: '', + name: '' +) +#end-update-search-indexes + +# Delete Search Index +# start-drop-search-index +result = collection.database.command( + dropSearchIndex: '', + name: '' +) +# end-drop-search-index + +# Text Index +# start-text +collection.indexes.create_one( { : => 'text' } ) +# end-text + +# Create Many +# start-index-create-many +collection.indexes.create_many([ + { key: { : 1 } }, + { key: { : -1 } }, +]) +# end-index-create-many + +# Delete an Index +# start-drop-single-index +collection.indexes.drop_one( '' ) +# 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 +all_indexes.each do |index| + puts index +end +# end-list-indexes + +client.close diff --git a/source/includes/indexes/index-starter-code.rb b/source/includes/indexes/index-starter-code.rb new file mode 100644 index 00000000..deb89e74 --- /dev/null +++ b/source/includes/indexes/index-starter-code.rb @@ -0,0 +1,19 @@ +require 'mongo' + +# Replace the placeholders with your credentials +uri = "" + +# 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('') +collection = database[:] + +# Start example code here + +# End example code here + +client.close diff --git a/source/indexes.txt b/source/indexes.txt index 454bb8fd..e78e92a8 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -33,4 +33,240 @@ 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 ````, 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:`scala-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 ` +guide in the {+mdb-server+} manual. + +For more information about the GeoJSON type, see the +:manual:`GeoJSON Objects ` 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 a 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 +------------------- + +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 that can be added +when creating indexes. These options mirror the options supported by the +:manual:`createIndex command`. + +.. 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 + ` + in the {+mdb-server+} manual. From 38ba81a14c4d3a9b150bfa5be847f5312ea60966 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 19 Dec 2024 17:23:42 -0500 Subject: [PATCH 2/8] edits --- .../includes/indexes/index-code-examples.rb | 8 +--- source/indexes.txt | 39 +++++++++++++++---- 2 files changed, 33 insertions(+), 14 deletions(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index 2227fa58..9f992981 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -36,15 +36,11 @@ # Create Search Index # start-create-search-index -index_definition = { +index_definition = { definition: { mappings: { dynamic: false, - fields: { - : { - type: '' - } - } + fields: { : {type: ''} } } } } diff --git a/source/indexes.txt b/source/indexes.txt index e78e92a8..b49bacd6 100644 --- a/source/indexes.txt +++ b/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:: @@ -35,7 +35,7 @@ different types of indexes by using the {+driver-long+}. 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 ````, with the relevant values for +code examples, such as ````, with the relevant values for your MongoDB deployment. Sample Application @@ -91,7 +91,7 @@ The following example creates a multikey index on the specified array-valued fie :start-after: start-index-multikey :end-before: end-index-multikey -To learn more about multikey indexes, see the :ref:`scala-multikey-index` guide. +To learn more about multikey indexes, see the :ref:`ruby-multikey-index` guide. Geospatial Index ---------------- @@ -123,7 +123,7 @@ 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 a specified field: +The following example creates an Atlas Search index on the specified field: .. literalinclude:: /includes/indexes/index-code-examples.rb :language: ruby @@ -131,6 +131,9 @@ The following example creates an Atlas Search index on a specified field: :end-before: end-create-search-index :dedent: +To learn more about creating search indexes, see the :ref:`ruby-atlas-search-index-create` +guide. + List Search Indexes ~~~~~~~~~~~~~~~~~~~ @@ -143,6 +146,9 @@ collection: :end-before: end-list-search-indexes :dedent: +To learn more about listing search indexes, see the :ref:`kotlin-sync-atlas-search-index-list` +guide. + Update Search Indexes ~~~~~~~~~~~~~~~~~~~~~ @@ -155,6 +161,9 @@ new index definition: :end-before: end-update-search-indexes :dedent: +To learn more about updating search indexes, see the :ref:`ruby-atlas-search-index-update` +guide. + Delete Search Indexes ~~~~~~~~~~~~~~~~~~~~~ @@ -166,6 +175,9 @@ The following example deletes an Atlas Search index with the specified name: :end-before: end-drop-search-index :dedent: +To learn more about deleting search indexes, see the :ref:`ruby-atlas-search-index-drop` +guide. + Text Index ---------- @@ -183,6 +195,14 @@ The following example creates a text index on the specified string field: 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 ---------- @@ -215,9 +235,10 @@ collection: Index Options ------------- -The following is a full list of the available options that can be added +The following is a full list of the available options you can add when creating indexes. These options mirror the options supported by the -:manual:`createIndex command`. +``createIndex`` command. For more information, see the :manual:`createIndex command +` in the {+mdb-server+} manual. .. list-table:: :header-rows: 1 @@ -264,9 +285,11 @@ when creating indexes. These options mirror the options supported by the - 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 + - ``“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 ` in the {+mdb-server+} manual. From dbe21b341052488fc8889c23d21f567c6adcaa0f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 19 Dec 2024 17:34:01 -0500 Subject: [PATCH 3/8] fix ref --- source/indexes.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/indexes.txt b/source/indexes.txt index b49bacd6..1dba02c1 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -146,7 +146,7 @@ collection: :end-before: end-list-search-indexes :dedent: -To learn more about listing search indexes, see the :ref:`kotlin-sync-atlas-search-index-list` +To learn more about listing search indexes, see the :ref:`ruby-atlas-search-index-list` guide. Update Search Indexes From 9116c92980e2cfdadcec754d3bfa6a4dbe837b73 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 19 Dec 2024 21:19:18 -0500 Subject: [PATCH 4/8] atlas search updates --- source/includes/indexes/index-code-examples.rb | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index 9f992981..374434c7 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -37,6 +37,7 @@ # Create Search Index # start-create-search-index index_definition = { + name: '', definition: { mappings: { dynamic: false, @@ -57,15 +58,22 @@ # Update Search Indexes #start-update-search-indexes +updated_definition = { + mappings: { + dynamic: false, + fields: { : { type: '' } } + } +} collection.database.command( updateSearchIndex: '', - name: '' + name: '', + definition: updated_definition ) #end-update-search-indexes # Delete Search Index # start-drop-search-index -result = collection.database.command( +collection.database.command( dropSearchIndex: '', name: '' ) From a6c714dde7348c7aaa6b324997b64a1ef63be23a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 8 Jan 2025 18:55:52 -0500 Subject: [PATCH 5/8] small fix --- source/includes/indexes/index-code-examples.rb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index 374434c7..d7ee7640 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -6,7 +6,7 @@ # 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 +# Creates a new client and connects to the server client = Mongo::Client.new(uri, options) database = client.use('') From a18ad37c1a7e2484a0608a3fac6147bbe25c3d21 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 13 Jan 2025 16:08:13 -0500 Subject: [PATCH 6/8] add api section, edit atlas search examples --- .../includes/indexes/index-code-examples.rb | 32 +++++++------------ source/indexes.txt | 11 +++++++ source/indexes/single-field-index.txt | 2 +- 3 files changed, 23 insertions(+), 22 deletions(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index d7ee7640..b9460299 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -36,24 +36,20 @@ # Create Search Index # start-create-search-index -index_definition = { - name: '', - definition: { - mappings: { - dynamic: false, - fields: { : {type: ''} } +index_definition = { + mappings: { + dynamic: false, + fields: { + : {type: ''} } } } -collection.database.command( - createSearchIndexes: '', - indexes: [index_definition] -) +collection.search_indexes.create_one(index_definition, name: '') # end-create-search-index # List Search Indexes # start-list-search-indexes -collection.database.command(listSearchIndexes: '') +puts collection.search_indexes.collect(&:to_json) # end-list-search-indexes # Update Search Indexes @@ -61,22 +57,16 @@ updated_definition = { mappings: { dynamic: false, - fields: { : { type: '' } } + fields: { : { type: '' } } } } -collection.database.command( - updateSearchIndex: '', - name: '', - definition: updated_definition -) + +collection.search_indexes.update_one(updated_definition, name: '') #end-update-search-indexes # Delete Search Index # start-drop-search-index -collection.database.command( - dropSearchIndex: '', - name: '' -) +collection.search_indexes.drop_one(name: '') # end-drop-search-index # Text Index diff --git a/source/indexes.txt b/source/indexes.txt index 1dba02c1..2e99749d 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -293,3 +293,14 @@ when creating indexes. These options mirror the options supported by the For more information, see :manual:`commitQuorom ` 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>`__ diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index 61cf10d5..0c137473 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -131,5 +131,5 @@ To learn more about any of the methods discussed 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 <{+api-root+}/Mongo/Index/View.html#create_one-instance_method>`__ - `find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__ From 86c618956795184fc99859f3a708b4a0b6e1cc50 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 13 Jan 2025 16:26:43 -0500 Subject: [PATCH 7/8] edits --- source/includes/indexes/index-code-examples.rb | 4 +--- source/indexes.txt | 12 ------------ 2 files changed, 1 insertion(+), 15 deletions(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index b9460299..c7e42070 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -94,9 +94,7 @@ # List an Index # start-list-indexes -all_indexes.each do |index| - puts index -end +puts collection.indexes.collect(&:to_json) # end-list-indexes client.close diff --git a/source/indexes.txt b/source/indexes.txt index 2e99749d..ffb5f34e 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -131,9 +131,6 @@ The following example creates an Atlas Search index on the specified field: :end-before: end-create-search-index :dedent: -To learn more about creating search indexes, see the :ref:`ruby-atlas-search-index-create` -guide. - List Search Indexes ~~~~~~~~~~~~~~~~~~~ @@ -146,9 +143,6 @@ collection: :end-before: end-list-search-indexes :dedent: -To learn more about listing search indexes, see the :ref:`ruby-atlas-search-index-list` -guide. - Update Search Indexes ~~~~~~~~~~~~~~~~~~~~~ @@ -161,9 +155,6 @@ new index definition: :end-before: end-update-search-indexes :dedent: -To learn more about updating search indexes, see the :ref:`ruby-atlas-search-index-update` -guide. - Delete Search Indexes ~~~~~~~~~~~~~~~~~~~~~ @@ -175,9 +166,6 @@ The following example deletes an Atlas Search index with the specified name: :end-before: end-drop-search-index :dedent: -To learn more about deleting search indexes, see the :ref:`ruby-atlas-search-index-drop` -guide. - Text Index ---------- From e10fed3a486213ad3499855b7ef1f57f6e04c0fc Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 16 Jan 2025 10:11:23 -0500 Subject: [PATCH 8/8] tech review --- source/includes/indexes/index-code-examples.rb | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb index c7e42070..625eb15e 100644 --- a/source/includes/indexes/index-code-examples.rb +++ b/source/includes/indexes/index-code-examples.rb @@ -4,7 +4,7 @@ uri = "" # Sets the server_api field of the options object to Stable API version 1 -options = { server_api: { version: "1" }} +options = { server_api: { version: '1' }} # Creates a new client and connects to the server client = Mongo::Client.new(uri, options) @@ -40,7 +40,7 @@ mappings: { dynamic: false, fields: { - : {type: ''} + : { type: '' } } } } @@ -71,7 +71,7 @@ # Text Index # start-text -collection.indexes.create_one( { : => 'text' } ) +collection.indexes.create_one({ : 'text' }) # end-text # Create Many