diff --git a/source/includes/indexes/index-code-examples.rb b/source/includes/indexes/index-code-examples.rb new file mode 100644 index 00000000..625eb15e --- /dev/null +++ b/source/includes/indexes/index-code-examples.rb @@ -0,0 +1,100 @@ +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 connects 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 = { + mappings: { + dynamic: false, + fields: { + : { type: '' } + } + } +} +collection.search_indexes.create_one(index_definition, 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: { : { type: '' } } + } +} + +collection.search_indexes.update_one(updated_definition, name: '') +#end-update-search-indexes + +# Delete Search Index +# start-drop-search-index +collection.search_indexes.drop_one(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 +puts collection.indexes.collect(&:to_json) +# 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 0c03d5f4..84983dc5 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:: @@ -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 ````, 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 ` +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 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 +` 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 + ` + 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 57bfc66e..1ec9c46b 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>`__