From 86323dfc5c97e41011cef7f001a6548c9705f623 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 27 Nov 2024 12:55:08 -0800 Subject: [PATCH 01/10] initial commit --- source/includes/reference/indexes.rb | 110 +++++++++ source/reference/indexes.txt | 357 +++++++++++---------------- 2 files changed, 249 insertions(+), 218 deletions(-) create mode 100644 source/includes/reference/indexes.rb diff --git a/source/includes/reference/indexes.rb b/source/includes/reference/indexes.rb new file mode 100644 index 00000000..221241de --- /dev/null +++ b/source/includes/reference/indexes.rb @@ -0,0 +1,110 @@ +# start create index +class Restaurant + include Mongoid::Document + + field :name, type: String + field :cuisine, type: String + field :borough, type: String + + index({ cuisine: 1}, { name: "cuisine_index", unique: false }) +end + +Restaurant.create_indexes +# end create index + +# start create alias index +class Restaurant + include Mongoid::Document + + field :borough, as: :b + + index({ b: 1}, { name: "borough_index" }) +end +# end create alias index + +# start create embedded index +class Restaurant + include Mongoid::Document + + embeds_many :addresses + index({"addresses.street": 1}) +end +# end create embedded index + +# start create compound index +class Restaurant + include Mongoid::Document + + field :name, type: String + embeds_many :addresses + + index({"addresses.street": 1, name: -1}, { name: "compound_index"}) +end +# end create compound index + +# start create 2dsphere index +class Restaurant + include Mongoid::Document + + field :location, type: Point + + index({location: "2dsphere"}, { name: "location_index"}) +end +# end create 2dsphere index + +# start create sparse index +class Restaurant + include Mongoid::Document + + field :name, type: String + field :cuisine, type: String + field :borough, type: String + + index({ borough: 1}, { sparse: true }) +end +# end create sparse index + +# start list index +Restaurant.indexes.each { |index| puts index } +# end list index + +# start create multiple indexes +class Restaurant + include Mongoid::Document + + field :name, type: String + field :cuisine, type: String + field :borough, type: String + + index({ name: 1}) + index({ cuisine: -1}) +end + +Restaurant.create_indexes +# end create multiple indexes + +# start drop indexes +Restaurant.remove_indexes +# end drop indexes + +# start create atlas search index +class Restaurant + include Mongoid::Document + + field :name, type: String + field :cuisine, type: String + field :borough, type: String + + search_index({ name: 1}) +end + +Restaurant.create_search_indexes +# end create atlas search index + +# start remove atlas search index +Restaurant.remove_search_indexes +# end remove atlas search index + +#start list atlas search index +Restaurant.search_indexes.each { |index| puts index } +# end list atlas search index \ No newline at end of file diff --git a/source/reference/indexes.txt b/source/reference/indexes.txt index 7a5d11a4..7a45246f 100644 --- a/source/reference/indexes.txt +++ b/source/reference/indexes.txt @@ -1,8 +1,8 @@ .. _indexes: -**************** -Index Management -**************** +================= +Work With Indexes +================= .. default-domain:: mongodb @@ -12,267 +12,188 @@ Index Management :depth: 2 :class: singlecol -Specifying Indexes -================== +Overview +-------- -You can define indexes on documents using the index macro. Provide the key for -the index along with a direction. Additional options can be supplied in the -second options hash parameter: +In this guide, you can learn how to use **indexes** with {+odm+}. Indexes can +improve the efficiency of queries by limiting the number of documents MongoDB +needs to scan. If your application is repeatedly running queries +on certain fields, you can create an index on those fields to improve query +performance. -.. code-block:: ruby +The following sections in this guide describe how to declare and create different +types of indexes using {+odm+}. The examples use the ``Restaurant`` model, which +maps to the ``restaurants`` collection in the ``sample_restaurants`` database. +To learn how to connect to this database +and collection using {+odm+}, see the :ref:`mongoid-quick-start-rails` or +:ref:`mongoid-quick-start-sinatra` guides. - class Person - include Mongoid::Document - field :ssn +Declare and Create an Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - index({ ssn: 1 }, { unique: true, name: "ssn_index" }) - end +When using {+odm+}, you can declare your index using the ``index`` macro and +then create it using the ``create_index`` macro. -You can define indexes on embedded document fields as well: +The following code example shows how to declare and create an ascending index +named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: -.. code-block:: ruby +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :emphasize-lines: 8, 11 + :start-after: start create index + :end-before: end create index - class Person - include Mongoid::Document - embeds_many :addresses - index "addresses.street" => 1 - end +The ``index`` macro defines the index you want to create and the ``create_index`` +macro creates the index in the ``restaurants`` collection. When defining an +index, the field you want to index on goes in the first hash object, and the +index options go in the second hash object. -You can index on multiple fields and provide direction: +Aliases and Declaring Indexes ++++++++++++++++++++++++++++++ -.. code-block:: ruby +You can use aliased field names in index definitions. For example, the following +example creates a field on the ``b`` field, which is an alias of the ``borough`` +field: - class Person - include Mongoid::Document - field :first_name - field :last_name +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create alias index + :end-before: end create alias index - index({ first_name: 1, last_name: 1 }, { unique: true }) - end +Create an Index on Embedded Document Fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Indexes can be sparse: +You can define an index on embedded document fields. The following code example +shows how to declare an ascending index on the ``street`` field in the +``Restaurant`` class where ``street`` is a field embedded within the ``address`` +field. -.. code-block:: ruby +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create embedded index + :end-before: end create embedded index - class Person - include Mongoid::Document - field :ssn +Create a Compound Index +~~~~~~~~~~~~~~~~~~~~~~~ - index({ ssn: -1 }, { sparse: true }) - end +You can define a compound index on multiple fields. The following code example +shows how to declare a compound index that is ascending on the ``address.street`` +field and descending on the ``name`` field. -For geospatial indexes, make sure the field being indexed is of type Array: +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create compound index + :end-before: end create compound index -.. code-block:: ruby +Create a Geospatial Index +~~~~~~~~~~~~~~~~~~~~~~~~~ - class Person - include Mongoid::Document - field :location, type: Array +You can define a 2dsphere index on fields that contain GeoJSON objects or +coordinate pairs. +The following example defines a 2dsphere index on a field that contains GeoJSON +objects: - index({ location: "2d" }, { min: -200, max: 200 }) - end +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create 2dsphere index + :end-before: end create 2dsphere index -Indexes can be scoped to a specific database: +For more information on 2dsphere indexes, see the :manual:`2dsphere ` +guide in the {+mdb-server+} manual. -.. code-block:: ruby +For more information on the GeoJSON type, see the :manual:`GeoJSON Objects ` +guide in the {+mdb-server+} manual. - class Person - include Mongoid::Document - field :ssn - index({ ssn: 1 }, { database: "users", unique: true, background: true }) - end +Create a Sparse Index +~~~~~~~~~~~~~~~~~~~~~ -You may use aliased field names in index definitions. Field aliases -will also be resolved on the following options: ``partial_filter_expression``, -``weights``, ``wildcard_projection``. +You can define a sparse index on fields that are not present in all documents. +The following code example defines a sparse index on the ``borough`` field: -.. code-block:: ruby +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create sparse index + :end-before: end create sparse index - class Person - include Mongoid::Document - field :a, as: :age - index({ age: 1 }, { partial_filter_expression: { age: { '$gte' => 20 } }) - end +For more information on sparse indexes, see the :manual:`Sparse Indexes ` +guide in the {+mdb-server+} manual. -.. note:: +Create Multiple Indexes +~~~~~~~~~~~~~~~~~~~~~~~ - The expansion of field name aliases in index options such as - ``partial_filter_expression`` is performed according to the behavior of MongoDB - server 6.0. Future server versions may change how they interpret these options, - and Mongoid's functionality may not support such changes. +You can define multiple indexes within your model and create them using a single +``create_indexes`` call. The following example shows how to create multiple +indexes at the same time: -Mongoid can define indexes on "foreign key" fields for associations. -This only works on the association macro that the foreign key is stored on: +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create multiple indexes + :end-before: end create multiple indexes -.. code-block:: ruby +.. TODO checkout what databases does - class Comment - include Mongoid::Document - belongs_to :post, index: true - has_and_belongs_to_many :preferences, index: true - end +List Indexes +~~~~~~~~~~~~ -*Deprecated:* In MongoDB 4.0 and earlier, users could control whether to build indexes -in the foreground (blocking) or background (non-blocking, but less efficient) using the -``background`` option. +You can list all indexes in your collection. The following example prints all +indexes in the ``Restaurant`` model: -.. code-block:: ruby +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start list index + :end-before: end list index - class Person - include Mongoid::Document - field :ssn - index({ ssn: 1 }, { unique: true, background: true }) - end +.. TODO test if there's a way to drop single index -The default value of ``background`` is controlled by Mongoid's -``background_indexing`` :ref:`configuration option `. +Drop Indexes +~~~~~~~~~~~~ -The ``background`` option has `no effect as of MongoDB 4.2 -`_. +You can drop all indexes in your collection. The following example drops all +indexes in the ``Restaurant`` model: +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start drop indexes + :end-before: end drop indexes -Specifying Search Indexes on MongoDB Atlas -========================================== +.. TODO: Is there a way to only drop 1 -If your application is connected to MongoDB Atlas, you can declare and manage -search indexes on your models. (This feature is only available on MongoDB -Atlas.) +Atlas Search Indexes +~~~~~~~~~~~~~~~~~~~~ -To declare a search index, use the ``search_index`` macro in your model: +You can declare and manage Atlas Search indexes using {+odm+}. -.. code-block:: ruby +To declare a search index, use the ``search_index`` macro within your model. The +following code example shows how to declare and create an Atlas Search index: - class Message - include Mongoid::Document +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start create atlas search index + :end-before: end create atlas search index - search_index { ... } - search_index :named_index, { ... } - end +Remove an Atlas Search Index +++++++++++++++++++++++++++++ -Search indexes may be given an explicit name; this is necessary if you have -more than one search index on a model. +To remove an Atlas Search index, use the ``remove_search_indexes`` macro. The +following code example shows how to remove an Atlas Search index from the +``restaurants`` collection: +.. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start remove atlas search index + :end-before: end remove atlas search index -Index Management Rake Tasks -=========================== +List Atlas Search Indexes ++++++++++++++++++++++++++ -When you want to create the indexes in the database, use the provided -``db:mongoid:create_indexes`` Rake task: +You can list all Atlas Search indexes in your collection by using the +``search_indexes`` macro: -.. code-block:: bash +.. literalinclude:: /includes/reference/indexes.rb - $ rake db:mongoid:create_indexes +API Documentation +----------------- -Mongoid also provides a Rake task to delete all secondary indexes. - -.. code-block:: bash - - $ rake db:mongoid:remove_indexes - -Note: the output of these Rake tasks goes to the default logger configured -by Rails. This is usually a file like ``log/development.log`` and not standard -output. - -These create/remove indexes commands also works for just one model by running -in Rails console: - -.. code-block:: ruby - - # Create indexes for Model - Model.create_indexes - - # Remove indexes for Model - Model.remove_indexes - -Managing Search Indexes on MongoDB Atlas ----------------------------------------- - -If you have defined search indexes on your model, there are rake tasks available -for creating and removing those search indexes: - -.. code-block:: bash - - $ rake db:mongoid:create_search_indexes - $ rake db:mongoid:remove_search_indexes - -By default, creating search indexes will wait for the indexes to be created, -which can take quite some time. If you want to simply let the database create -the indexes in the background, you can set the ``WAIT_FOR_SEARCH_INDEXES`` -environment variable to 0, like this: - -.. code-block:: bash - - $ rake WAIT_FOR_SEARCH_INDEXES=0 db:mongoid:create_search_indexes - -Note that the task for removing search indexes will remove all search indexes -from all models, and should be used with caution. - -You can also add and remove search indexes for a single model by invoking the -following in a Rails console: - -.. code-block:: ruby - - # Create all defined search indexes on the model; this will return - # immediately and the indexes will be created in the background. - Model.create_search_indexes - - # Remove all search indexes from the model - Model.remove_search_indexes - - # Enumerate all search indexes on the model - Model.search_indexes.each { |index| ... } - - -Telling Mongoid Where to Look For Models ----------------------------------------- - -For non-Rails applications, Mongoid's rake tasks will look for models in -``./app/models`` and ``./lib/models``. For Rails, Mongoid will look in -``./app/models`` (or wherever you've configured Rails to look for models). If -your models are in another location, you will need to tell Mongoid where to -look for them with ``Mongoid.model_paths=``. You can do this by setting it -in your application's Rakefile: - -.. code-block:: ruby - - # Rakefile - - # keep the defaults, but add more paths to look for models - Mongoid.model_paths += [ "./src/models", "./lib/documents" ] - - # or, override the defaults entirely - Mongoid.model_paths = [ "./src/models", "./lib/documents" ] - -Make sure that these paths are in your application's load path, as well. For -example: - -.. code-block:: ruby - - # Rakefile - - $LOAD_PATHS.concat [ "./src/models", "./lib/documents" ] - - -Using Rake Tasks With Non-Rails Applications --------------------------------------------- - -Mongoid's Rake tasks are automatically loaded in Rails applications using -Mongoid. When using Mongoid with a non-Rails application, these tasks must -be loaded manually: - -.. code-block:: ruby - - # Rakefile - - require 'mongoid' - load 'mongoid/tasks/database.rake' - -If your application uses Bundler, you can require ``bundler/setup`` instead of -explicitly requiring ``mongoid``: - -.. code-block:: ruby - - # Rakefile - - require 'bundler/setup' - load 'mongoid/tasks/database.rake' +To learn more about using indexes in {+odm+}, see the +`Mongoid::Indexable::ClassMethods <{+api-root+}/Indexable/ClassMethods.html>`__ +guide. \ No newline at end of file From 3f75ae0a98f00df90ecb80d51eb90c6bd7849388 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 27 Nov 2024 18:16:06 -0800 Subject: [PATCH 02/10] Edits --- source/includes/reference/indexes.rb | 27 ++++++++--- source/reference/indexes.txt | 67 +++++++++++++++++----------- 2 files changed, 60 insertions(+), 34 deletions(-) diff --git a/source/includes/reference/indexes.rb b/source/includes/reference/indexes.rb index 221241de..fb506484 100644 --- a/source/includes/reference/indexes.rb +++ b/source/includes/reference/indexes.rb @@ -23,6 +23,12 @@ class Restaurant # end create alias index # start create embedded index +class Address + include Mongoid::Document + + field :street, type: String +end + class Restaurant include Mongoid::Document @@ -38,7 +44,7 @@ class Restaurant field :name, type: String embeds_many :addresses - index({"addresses.street": 1, name: -1}, { name: "compound_index"}) + index({borough: 1, name: -1}, { name: "compound_index"}) end # end create compound index @@ -46,7 +52,7 @@ class Restaurant class Restaurant include Mongoid::Document - field :location, type: Point + field :location, type: Array index({location: "2dsphere"}, { name: "location_index"}) end @@ -64,10 +70,6 @@ class Restaurant end # end create sparse index -# start list index -Restaurant.indexes.each { |index| puts index } -# end list index - # start create multiple indexes class Restaurant include Mongoid::Document @@ -95,7 +97,18 @@ class Restaurant field :cuisine, type: String field :borough, type: String - search_index({ name: 1}) + search_index :my_search_index, + mappings: { + fields: { + name: { + type: "string" + }, + cuisine: { + type: "string" + } + }, + dynamic: true + } end Restaurant.create_search_indexes diff --git a/source/reference/indexes.txt b/source/reference/indexes.txt index 7a45246f..1103140f 100644 --- a/source/reference/indexes.txt +++ b/source/reference/indexes.txt @@ -9,7 +9,7 @@ Work With Indexes .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol Overview @@ -44,9 +44,12 @@ named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: :end-before: end create index The ``index`` macro defines the index you want to create and the ``create_index`` -macro creates the index in the ``restaurants`` collection. When defining an -index, the field you want to index on goes in the first hash object, and the -index options go in the second hash object. +macro creates the index in the ``restaurants`` collection. + +When defining an index, the first hash object contains the field you want to +index and its direction. ``1`` represents an ascending index, ``-1`` represents a +descending index. The second hash object contains index options. To learn more +about index options, see the :ref:`mongoid_indexes_api_documentation` section. Aliases and Declaring Indexes +++++++++++++++++++++++++++++ @@ -98,10 +101,10 @@ objects: :start-after: start create 2dsphere index :end-before: end create 2dsphere index -For more information on 2dsphere indexes, see the :manual:`2dsphere ` +For more information on 2dsphere indexes, see the :manual:`2dsphere ` guide in the {+mdb-server+} manual. -For more information on the GeoJSON type, see the :manual:`GeoJSON Objects ` +For more information on the GeoJSON type, see the :manual:`GeoJSON Objects ` guide in the {+mdb-server+} manual. Create a Sparse Index @@ -115,7 +118,7 @@ The following code example defines a sparse index on the ``borough`` field: :start-after: start create sparse index :end-before: end create sparse index -For more information on sparse indexes, see the :manual:`Sparse Indexes ` +For more information on sparse indexes, see the :manual:`Sparse Indexes ` guide in the {+mdb-server+} manual. Create Multiple Indexes @@ -130,21 +133,6 @@ indexes at the same time: :start-after: start create multiple indexes :end-before: end create multiple indexes -.. TODO checkout what databases does - -List Indexes -~~~~~~~~~~~~ - -You can list all indexes in your collection. The following example prints all -indexes in the ``Restaurant`` model: - -.. literalinclude:: /includes/reference/indexes.rb - :language: ruby - :start-after: start list index - :end-before: end list index - -.. TODO test if there's a way to drop single index - Drop Indexes ~~~~~~~~~~~~ @@ -156,7 +144,12 @@ indexes in the ``Restaurant`` model: :start-after: start drop indexes :end-before: end drop indexes -.. TODO: Is there a way to only drop 1 +.. note:: Default Index + + MongoDB creates a default index on the ``_id`` field during the + creation of a collection. This index prevents clients from inserting + two documents with the same values for the ``_id`` field. You cannot + drop this index. Atlas Search Indexes ~~~~~~~~~~~~~~~~~~~~ @@ -164,13 +157,19 @@ Atlas Search Indexes You can declare and manage Atlas Search indexes using {+odm+}. To declare a search index, use the ``search_index`` macro within your model. The -following code example shows how to declare and create an Atlas Search index: +following code example shows how to declare and create an Atlas Search index +named ``my_search_index``. +The index is on the ``name`` and ``cuisine`` fields and is dynamic. .. literalinclude:: /includes/reference/indexes.rb :language: ruby :start-after: start create atlas search index :end-before: end create atlas search index +To learn more about the syntax for creating an Atlas Search index, see +the :atlas:`Create an Atlas Search Index ` +guide in the MongoDB Atlas documentation. + Remove an Atlas Search Index ++++++++++++++++++++++++++++ @@ -186,14 +185,28 @@ following code example shows how to remove an Atlas Search index from the List Atlas Search Indexes +++++++++++++++++++++++++ -You can list all Atlas Search indexes in your collection by using the -``search_indexes`` macro: +You can enumerate through all Atlas Search indexes in your collection +by using the ``search_indexes`` macro. The following example enumerates through +all Atlas Search indexes in the ``restaurants`` collection and prints out their +information: .. literalinclude:: /includes/reference/indexes.rb + :language: ruby + :start-after: start list atlas search index + :end-before: end list atlas search index + +.. _mongoid-indexes-api-documentation: API Documentation ----------------- To learn more about using indexes in {+odm+}, see the `Mongoid::Indexable::ClassMethods <{+api-root+}/Indexable/ClassMethods.html>`__ -guide. \ No newline at end of file +documentation. + +To learn more about index options, see the `Mongoid::Indexable::Validators::Options +<{+api-root+}/Indexable/Validators/Options.html>`__ documentation. + +To learn more about using Atlas Search indexes in {+odm+}, see the +`Mongoid::SearchIndexable::ClassMethods <{+api-root+}/SearchIndexable/ClassMethods.html>`__ +documentation. \ No newline at end of file From da4cd3b9c9f82b3f08747c48c51ceafcfbe2539c Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Mon, 2 Dec 2024 11:23:09 -0800 Subject: [PATCH 03/10] fixes --- source/reference/indexes.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/reference/indexes.txt b/source/reference/indexes.txt index 1103140f..ffc97e7f 100644 --- a/source/reference/indexes.txt +++ b/source/reference/indexes.txt @@ -32,7 +32,7 @@ Declare and Create an Index ~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using {+odm+}, you can declare your index using the ``index`` macro and -then create it using the ``create_index`` macro. +then create it using the ``create_indexes`` macro. The following code example shows how to declare and create an ascending index named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: @@ -43,13 +43,13 @@ named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: :start-after: start create index :end-before: end create index -The ``index`` macro defines the index you want to create and the ``create_index`` +The ``index`` macro defines the index you want to create and the ``create_indexes`` macro creates the index in the ``restaurants`` collection. When defining an index, the first hash object contains the field you want to index and its direction. ``1`` represents an ascending index, ``-1`` represents a descending index. The second hash object contains index options. To learn more -about index options, see the :ref:`mongoid_indexes_api_documentation` section. +about index options, see the :ref:`mongoid-indexes-api-documentation` section. Aliases and Declaring Indexes +++++++++++++++++++++++++++++ @@ -156,7 +156,8 @@ Atlas Search Indexes You can declare and manage Atlas Search indexes using {+odm+}. -To declare a search index, use the ``search_index`` macro within your model. The +To declare a search index, use the ``search_index`` macro within your model. To +create the declared search indexes, use the ``create_search_indexes`` macro. The following code example shows how to declare and create an Atlas Search index named ``my_search_index``. The index is on the ``name`` and ``cuisine`` fields and is dynamic. From 27f70fd5f693bb0af9bf8bdb796c8fcff5f0e56a Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 13:49:42 -0800 Subject: [PATCH 04/10] Feedback --- source/includes/reference/indexes.rb | 2 +- source/reference/indexes.txt | 26 ++++++++++++++++---------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/source/includes/reference/indexes.rb b/source/includes/reference/indexes.rb index fb506484..9eebaab9 100644 --- a/source/includes/reference/indexes.rb +++ b/source/includes/reference/indexes.rb @@ -42,7 +42,7 @@ class Restaurant include Mongoid::Document field :name, type: String - embeds_many :addresses + field :borough, type: String index({borough: 1, name: -1}, { name: "compound_index"}) end diff --git a/source/reference/indexes.txt b/source/reference/indexes.txt index ffc97e7f..19a41f89 100644 --- a/source/reference/indexes.txt +++ b/source/reference/indexes.txt @@ -6,6 +6,13 @@ Work With Indexes .. default-domain:: mongodb +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, odm, optimization, efficiency, Atlas search + .. contents:: On this page :local: :backlinks: none @@ -44,10 +51,10 @@ named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: :end-before: end create index The ``index`` macro defines the index you want to create and the ``create_indexes`` -macro creates the index in the ``restaurants`` collection. +macro creates it in the ``restaurants`` collection. When defining an index, the first hash object contains the field you want to -index and its direction. ``1`` represents an ascending index, ``-1`` represents a +index and its direction. ``1`` represents an ascending index, and ``-1`` represents a descending index. The second hash object contains index options. To learn more about index options, see the :ref:`mongoid-indexes-api-documentation` section. @@ -55,7 +62,7 @@ Aliases and Declaring Indexes +++++++++++++++++++++++++++++ You can use aliased field names in index definitions. For example, the following -example creates a field on the ``b`` field, which is an alias of the ``borough`` +code creates a field on the ``b`` field, which is an alias of the ``borough`` field: .. literalinclude:: /includes/reference/indexes.rb @@ -67,9 +74,8 @@ Create an Index on Embedded Document Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can define an index on embedded document fields. The following code example -shows how to declare an ascending index on the ``street`` field in the -``Restaurant`` class where ``street`` is a field embedded within the ``address`` -field. +shows how to declare an ascending index on the ``street`` field, which is embedded +within the ``address`` field in the ``Restaurant`` model. .. literalinclude:: /includes/reference/indexes.rb :language: ruby @@ -80,7 +86,7 @@ Create a Compound Index ~~~~~~~~~~~~~~~~~~~~~~~ You can define a compound index on multiple fields. The following code example -shows how to declare a compound index that is ascending on the ``address.street`` +shows how to declare a compound index that is ascending on the ``borough`` field and descending on the ``name`` field. .. literalinclude:: /includes/reference/indexes.rb @@ -102,10 +108,10 @@ objects: :end-before: end create 2dsphere index For more information on 2dsphere indexes, see the :manual:`2dsphere ` -guide in the {+mdb-server+} manual. +guide in the MongoDB {+server-manual+}. For more information on the GeoJSON type, see the :manual:`GeoJSON Objects ` -guide in the {+mdb-server+} manual. +guide in the MongoDB {+server-manual+}. Create a Sparse Index ~~~~~~~~~~~~~~~~~~~~~ @@ -119,7 +125,7 @@ The following code example defines a sparse index on the ``borough`` field: :end-before: end create sparse index For more information on sparse indexes, see the :manual:`Sparse Indexes ` -guide in the {+mdb-server+} manual. +guide in the MongoDB {+server-manual+}. Create Multiple Indexes ~~~~~~~~~~~~~~~~~~~~~~~ From 3ba876ab1cd29daa476b6bab3b6bfa1580187dcf Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 13:56:42 -0800 Subject: [PATCH 05/10] removing --- source/data-modeling.txt | 1 + .../{reference => data-modeling}/indexes.txt | 22 +++++++++---------- .../{reference => data-modeling}/indexes.rb | 0 3 files changed, 12 insertions(+), 11 deletions(-) rename source/{reference => data-modeling}/indexes.txt (92%) rename source/includes/{reference => data-modeling}/indexes.rb (100%) diff --git a/source/data-modeling.txt b/source/data-modeling.txt index 50af17cf..2db81482 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -18,6 +18,7 @@ Model Your Data Field Behaviors Inheritance Document Validation + Indexes In this section, you can learn how to model data in {+odm+}. diff --git a/source/reference/indexes.txt b/source/data-modeling/indexes.txt similarity index 92% rename from source/reference/indexes.txt rename to source/data-modeling/indexes.txt index 19a41f89..766df6fc 100644 --- a/source/reference/indexes.txt +++ b/source/data-modeling/indexes.txt @@ -44,7 +44,7 @@ then create it using the ``create_indexes`` macro. The following code example shows how to declare and create an ascending index named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :emphasize-lines: 8, 11 :start-after: start create index @@ -65,7 +65,7 @@ You can use aliased field names in index definitions. For example, the following code creates a field on the ``b`` field, which is an alias of the ``borough`` field: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create alias index :end-before: end create alias index @@ -77,7 +77,7 @@ You can define an index on embedded document fields. The following code example shows how to declare an ascending index on the ``street`` field, which is embedded within the ``address`` field in the ``Restaurant`` model. -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create embedded index :end-before: end create embedded index @@ -89,7 +89,7 @@ You can define a compound index on multiple fields. The following code example shows how to declare a compound index that is ascending on the ``borough`` field and descending on the ``name`` field. -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create compound index :end-before: end create compound index @@ -102,7 +102,7 @@ coordinate pairs. The following example defines a 2dsphere index on a field that contains GeoJSON objects: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create 2dsphere index :end-before: end create 2dsphere index @@ -119,7 +119,7 @@ Create a Sparse Index You can define a sparse index on fields that are not present in all documents. The following code example defines a sparse index on the ``borough`` field: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create sparse index :end-before: end create sparse index @@ -134,7 +134,7 @@ You can define multiple indexes within your model and create them using a single ``create_indexes`` call. The following example shows how to create multiple indexes at the same time: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create multiple indexes :end-before: end create multiple indexes @@ -145,7 +145,7 @@ Drop Indexes You can drop all indexes in your collection. The following example drops all indexes in the ``Restaurant`` model: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start drop indexes :end-before: end drop indexes @@ -168,7 +168,7 @@ following code example shows how to declare and create an Atlas Search index named ``my_search_index``. The index is on the ``name`` and ``cuisine`` fields and is dynamic. -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start create atlas search index :end-before: end create atlas search index @@ -184,7 +184,7 @@ To remove an Atlas Search index, use the ``remove_search_indexes`` macro. The following code example shows how to remove an Atlas Search index from the ``restaurants`` collection: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start remove atlas search index :end-before: end remove atlas search index @@ -197,7 +197,7 @@ by using the ``search_indexes`` macro. The following example enumerates through all Atlas Search indexes in the ``restaurants`` collection and prints out their information: -.. literalinclude:: /includes/reference/indexes.rb +.. literalinclude:: /includes/data-modeling/indexes.rb :language: ruby :start-after: start list atlas search index :end-before: end list atlas search index diff --git a/source/includes/reference/indexes.rb b/source/includes/data-modeling/indexes.rb similarity index 100% rename from source/includes/reference/indexes.rb rename to source/includes/data-modeling/indexes.rb From cc7356760628cfebfb1185796edc1a3b559249e1 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 13:57:33 -0800 Subject: [PATCH 06/10] adding reference indexes back --- source/reference/indexes.txt | 278 +++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 source/reference/indexes.txt diff --git a/source/reference/indexes.txt b/source/reference/indexes.txt new file mode 100644 index 00000000..786dbfc6 --- /dev/null +++ b/source/reference/indexes.txt @@ -0,0 +1,278 @@ +.. _indexes: + +**************** +Index Management +**************** + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Specifying Indexes +================== + +You can define indexes on documents using the index macro. Provide the key for +the index along with a direction. Additional options can be supplied in the +second options hash parameter: + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :ssn + + index({ ssn: 1 }, { unique: true, name: "ssn_index" }) + end + +You can define indexes on embedded document fields as well: + +.. code-block:: ruby + + class Person + include Mongoid::Document + embeds_many :addresses + index "addresses.street" => 1 + end + +You can index on multiple fields and provide direction: + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :first_name + field :last_name + + index({ first_name: 1, last_name: 1 }, { unique: true }) + end + +Indexes can be sparse: + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :ssn + + index({ ssn: -1 }, { sparse: true }) + end + +For geospatial indexes, make sure the field being indexed is of type Array: + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :location, type: Array + + index({ location: "2d" }, { min: -200, max: 200 }) + end + +Indexes can be scoped to a specific database: + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :ssn + index({ ssn: 1 }, { database: "users", unique: true, background: true }) + end + +You may use aliased field names in index definitions. Field aliases +will also be resolved on the following options: ``partial_filter_expression``, +``weights``, ``wildcard_projection``. + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :a, as: :age + index({ age: 1 }, { partial_filter_expression: { age: { '$gte' => 20 } }) + end + +.. note:: + + The expansion of field name aliases in index options such as + ``partial_filter_expression`` is performed according to the behavior of MongoDB + server 6.0. Future server versions may change how they interpret these options, + and Mongoid's functionality may not support such changes. + +Mongoid can define indexes on "foreign key" fields for associations. +This only works on the association macro that the foreign key is stored on: + +.. code-block:: ruby + + class Comment + include Mongoid::Document + belongs_to :post, index: true + has_and_belongs_to_many :preferences, index: true + end + +*Deprecated:* In MongoDB 4.0 and earlier, users could control whether to build indexes +in the foreground (blocking) or background (non-blocking, but less efficient) using the +``background`` option. + +.. code-block:: ruby + + class Person + include Mongoid::Document + field :ssn + index({ ssn: 1 }, { unique: true, background: true }) + end + +The default value of ``background`` is controlled by Mongoid's +``background_indexing`` :ref:`configuration option `. + +The ``background`` option has `no effect as of MongoDB 4.2 +`_. + + +Specifying Search Indexes on MongoDB Atlas +========================================== + +If your application is connected to MongoDB Atlas, you can declare and manage +search indexes on your models. (This feature is only available on MongoDB +Atlas.) + +To declare a search index, use the ``search_index`` macro in your model: + +.. code-block:: ruby + + class Message + include Mongoid::Document + + search_index { ... } + search_index :named_index, { ... } + end + +Search indexes may be given an explicit name; this is necessary if you have +more than one search index on a model. + + +Index Management Rake Tasks +=========================== + +When you want to create the indexes in the database, use the provided +``db:mongoid:create_indexes`` Rake task: + +.. code-block:: bash + + $ rake db:mongoid:create_indexes + +Mongoid also provides a Rake task to delete all secondary indexes. + +.. code-block:: bash + + $ rake db:mongoid:remove_indexes + +Note: the output of these Rake tasks goes to the default logger configured +by Rails. This is usually a file like ``log/development.log`` and not standard +output. + +These create/remove indexes commands also works for just one model by running +in Rails console: + +.. code-block:: ruby + + # Create indexes for Model + Model.create_indexes + + # Remove indexes for Model + Model.remove_indexes + +Managing Search Indexes on MongoDB Atlas +---------------------------------------- + +If you have defined search indexes on your model, there are rake tasks available +for creating and removing those search indexes: + +.. code-block:: bash + + $ rake db:mongoid:create_search_indexes + $ rake db:mongoid:remove_search_indexes + +By default, creating search indexes will wait for the indexes to be created, +which can take quite some time. If you want to simply let the database create +the indexes in the background, you can set the ``WAIT_FOR_SEARCH_INDEXES`` +environment variable to 0, like this: + +.. code-block:: bash + + $ rake WAIT_FOR_SEARCH_INDEXES=0 db:mongoid:create_search_indexes + +Note that the task for removing search indexes will remove all search indexes +from all models, and should be used with caution. + +You can also add and remove search indexes for a single model by invoking the +following in a Rails console: + +.. code-block:: ruby + + # Create all defined search indexes on the model; this will return + # immediately and the indexes will be created in the background. + Model.create_search_indexes + + # Remove all search indexes from the model + Model.remove_search_indexes + + # Enumerate all search indexes on the model + Model.search_indexes.each { |index| ... } + + +Telling Mongoid Where to Look For Models +---------------------------------------- + +For non-Rails applications, Mongoid's rake tasks will look for models in +``./app/models`` and ``./lib/models``. For Rails, Mongoid will look in +``./app/models`` (or wherever you've configured Rails to look for models). If +your models are in another location, you will need to tell Mongoid where to +look for them with ``Mongoid.model_paths=``. You can do this by setting it +in your application's Rakefile: + +.. code-block:: ruby + + # Rakefile + + # keep the defaults, but add more paths to look for models + Mongoid.model_paths += [ "./src/models", "./lib/documents" ] + + # or, override the defaults entirely + Mongoid.model_paths = [ "./src/models", "./lib/documents" ] + +Make sure that these paths are in your application's load path, as well. For +example: + +.. code-block:: ruby + + # Rakefile + + $LOAD_PATHS.concat [ "./src/models", "./lib/documents" ] + + +Using Rake Tasks With Non-Rails Applications +-------------------------------------------- + +Mongoid's Rake tasks are automatically loaded in Rails applications using +Mongoid. When using Mongoid with a non-Rails application, these tasks must +be loaded manually: + +.. code-block:: ruby + + # Rakefile + + require 'mongoid' + load 'mongoid/tasks/database.rake' + +If your application uses Bundler, you can require ``bundler/setup`` instead of +explicitly requiring ``mongoid``: + +.. code-block:: ruby + + # Rakefile + + require 'bundler/setup' + load 'mongoid/tasks/database.rake' \ No newline at end of file From e6c1c2218eba5e3e07f4aa124cef42d9bcda3260 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 3 Dec 2024 14:01:12 -0800 Subject: [PATCH 07/10] modify id and landing page --- source/data-modeling.txt | 3 +++ source/data-modeling/indexes.txt | 2 +- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/source/data-modeling.txt b/source/data-modeling.txt index 2db81482..1e6705d1 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -33,3 +33,6 @@ In this section, you can learn how to model data in {+odm+}. - :ref:`mongoid-modeling-validation`: Learn how to create document validation rules for your model classes. + +- :ref:`mongoid-work-with-indexes`: Learn how to create and manage indexes for + your model classes. diff --git a/source/data-modeling/indexes.txt b/source/data-modeling/indexes.txt index 766df6fc..30cef015 100644 --- a/source/data-modeling/indexes.txt +++ b/source/data-modeling/indexes.txt @@ -1,4 +1,4 @@ -.. _indexes: +.. _mongoid-work-with-indexes: ================= Work With Indexes From ba6289469a3ed8a3cc38182793a3fc23e7e469d4 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 4 Dec 2024 10:22:55 -0800 Subject: [PATCH 08/10] final comments --- source/data-modeling.txt | 2 +- source/data-modeling/indexes.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/data-modeling.txt b/source/data-modeling.txt index 1e6705d1..2ff93a05 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -18,7 +18,7 @@ Model Your Data Field Behaviors Inheritance Document Validation - Indexes + Work With Indexes In this section, you can learn how to model data in {+odm+}. diff --git a/source/data-modeling/indexes.txt b/source/data-modeling/indexes.txt index 30cef015..2b49809d 100644 --- a/source/data-modeling/indexes.txt +++ b/source/data-modeling/indexes.txt @@ -62,7 +62,7 @@ Aliases and Declaring Indexes +++++++++++++++++++++++++++++ You can use aliased field names in index definitions. For example, the following -code creates a field on the ``b`` field, which is an alias of the ``borough`` +code creates an index on the ``b`` field, which is an alias of the ``borough`` field: .. literalinclude:: /includes/data-modeling/indexes.rb From ecdb7cca2624da6c51140f1419f43d87483c1a1f Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Wed, 4 Dec 2024 13:49:47 -0800 Subject: [PATCH 09/10] optimize queries with indexes --- source/data-modeling.txt | 6 +++--- source/data-modeling/indexes.txt | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/source/data-modeling.txt b/source/data-modeling.txt index 2ff93a05..5c451dd2 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -18,7 +18,7 @@ Model Your Data Field Behaviors Inheritance Document Validation - Work With Indexes + Optimize Queries With Indexes In this section, you can learn how to model data in {+odm+}. @@ -34,5 +34,5 @@ In this section, you can learn how to model data in {+odm+}. - :ref:`mongoid-modeling-validation`: Learn how to create document validation rules for your model classes. -- :ref:`mongoid-work-with-indexes`: Learn how to create and manage indexes for - your model classes. +- :ref:`mongoid-optimize-queries-with-indexes`: Learn how to create and manage + indexes for your model classes. diff --git a/source/data-modeling/indexes.txt b/source/data-modeling/indexes.txt index 2b49809d..b2ed720b 100644 --- a/source/data-modeling/indexes.txt +++ b/source/data-modeling/indexes.txt @@ -1,8 +1,8 @@ -.. _mongoid-work-with-indexes: +.. _mongoid-optimize-queries-with-indexes: -================= -Work With Indexes -================= +============================= +Optimize Queries With Indexes +============================= .. default-domain:: mongodb From f806fe419edf4fe206b9517928e4a3fa48458499 Mon Sep 17 00:00:00 2001 From: Maya Raman Date: Tue, 10 Dec 2024 10:40:14 -0500 Subject: [PATCH 10/10] command vs macro --- source/data-modeling/indexes.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/data-modeling/indexes.txt b/source/data-modeling/indexes.txt index b2ed720b..6e8dcbd6 100644 --- a/source/data-modeling/indexes.txt +++ b/source/data-modeling/indexes.txt @@ -39,7 +39,7 @@ Declare and Create an Index ~~~~~~~~~~~~~~~~~~~~~~~~~~~ When using {+odm+}, you can declare your index using the ``index`` macro and -then create it using the ``create_indexes`` macro. +then create it using the ``create_indexes`` command. The following code example shows how to declare and create an ascending index named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: @@ -51,7 +51,7 @@ named ``cuisine_index`` on the ``cuisine`` field in the ``Restaurant`` class: :end-before: end create index The ``index`` macro defines the index you want to create and the ``create_indexes`` -macro creates it in the ``restaurants`` collection. +command creates it in the ``restaurants`` collection. When defining an index, the first hash object contains the field you want to index and its direction. ``1`` represents an ascending index, and ``-1`` represents a @@ -163,9 +163,9 @@ Atlas Search Indexes You can declare and manage Atlas Search indexes using {+odm+}. To declare a search index, use the ``search_index`` macro within your model. To -create the declared search indexes, use the ``create_search_indexes`` macro. The -following code example shows how to declare and create an Atlas Search index -named ``my_search_index``. +create the search indexes declared within a model, use the ``create_search_indexes`` +command. The following code example shows how to declare and create an Atlas +Search index named ``my_search_index``. The index is on the ``name`` and ``cuisine`` fields and is dynamic. .. literalinclude:: /includes/data-modeling/indexes.rb @@ -180,7 +180,7 @@ guide in the MongoDB Atlas documentation. Remove an Atlas Search Index ++++++++++++++++++++++++++++ -To remove an Atlas Search index, use the ``remove_search_indexes`` macro. The +To remove an Atlas Search index, use the ``remove_search_indexes`` command. The following code example shows how to remove an Atlas Search index from the ``restaurants`` collection: @@ -193,7 +193,7 @@ List Atlas Search Indexes +++++++++++++++++++++++++ You can enumerate through all Atlas Search indexes in your collection -by using the ``search_indexes`` macro. The following example enumerates through +by using the ``search_indexes`` command. The following example enumerates through all Atlas Search indexes in the ``restaurants`` collection and prints out their information: