From f28a372b6feb720ebbd16bd0d1f647cc2ab1e901 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Dec 2024 19:08:27 -0500 Subject: [PATCH 1/8] DOCSP-45204 Compound Index --- source/includes/indexes/compound.rb | 41 +++++++++ source/indexes.txt | 2 +- source/indexes/compound-index.txt | 124 ++++++++++++++++++++++++++++ 3 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 source/includes/indexes/compound.rb create mode 100644 source/indexes/compound-index.txt diff --git a/source/includes/indexes/compound.rb b/source/includes/indexes/compound.rb new file mode 100644 index 00000000..cb762498 --- /dev/null +++ b/source/includes/indexes/compound.rb @@ -0,0 +1,41 @@ +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) + +# start-sample-data +database = client.use('sample_mflix') +collection = database[:movies] +# end-sample-data + +# start-index-compound +# Creates an index on the "runtime" and "year" field +collection.indexes.create_one({ runtime: -1, year: 1 }) +# end-index-compound + +# start-index-compound-query +# Finds a document with the specified runtime and release year +# by using the newly created index +filter = { '$and' => [ + { 'runtime': { '$gt' => 90 } }, + { 'year': { '$gt' => 2005 } } + ] } +doc = collection.find(filter).first + +if doc + puts doc.to_json +else + puts "No document found" +end +# end-index-compound-query + +# start-check-compound-index +# Lists all indexes on the collection +puts collection.indexes.collect(&:to_json) +# end-check-compound-index diff --git a/source/indexes.txt b/source/indexes.txt index 454bb8fd..a6f0ef95 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -23,7 +23,7 @@ Optimize Queries by Using Indexes :maxdepth: 1 Single Field -.. Compound + Compound .. Multikey .. Atlas Search diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt new file mode 100644 index 00000000..bfa82817 --- /dev/null +++ b/source/indexes/compound-index.txt @@ -0,0 +1,124 @@ +.. ruby-compound-index: + +================ +Compound Indexes +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: index, query, optimization, efficiency + +Overview +-------- + +**Compound indexes** hold references to multiple +fields within a collection's documents, improving query and sort +performance. + +When creating a compound index, you must specify the following details: + +- The fields on which to create the index + +- The sort order for each field (ascending or descending) + +Sample Data +~~~~~~~~~~~ + +The examples in this guide use the ``movies`` collection in the +``sample_mflix`` database from the :atlas:`Atlas sample datasets +`. To access this collection from your {+language+} +application, create a ``Mongo::Client`` object that connects to +an Atlas cluster and assign the following values to your ``database`` +and ``collection`` +variables: + +.. literalinclude:: /includes/indexes/single-field.rb + :start-after: start-sample-data + :end-before: end-sample-data + :language: ruby + :copyable: + +To learn how to create a free MongoDB Atlas cluster and +load the sample datasets, see the :atlas:`Get Started with Atlas +` guide. + +Create a Compound Index +----------------------- + +Use the ``create_one`` method to create a compound index. The following +example creates an index in descending order on the ``runtime`` field and +in ascending order on the ``year`` field: + +.. literalinclude:: /includes/indexes/compound.rb + :start-after: start-index-compound + :end-before: end-index-compound + :language: ruby + :copyable: + +Verify Index Creation +--------------------- + +You can verify that the index was created by listing the indexes in the +collection. You should see an index for ``runtime`` and ``year`` in the list, +as shown in the following output: + + +.. io-code-block:: + :copyable: true + + .. input:: /includes/indexes/compound.rb + :start-after: start-check-compound-index + :end-before: end-check-compound-index + :language: ruby + + .. output:: + :visible: true + + {"v": 2, "key": {"runtime": -1, "year": 1}, "name": "runtime_-1_year_1"} + +Example Query +------------- + +The following is an example of a query that is covered by the index +created on the ``runtime`` and ``year`` fields: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/indexes/compound.rb + :start-after: start-index-compound-query + :end-before: end-index-compound-query + :language: ruby + + .. output:: + :visible: false + + {"_id":...,"runtime": 91,...,"title": "Monster House",...,"year": 2006,...} + +Additional Information +---------------------- + +To view runnable examples that demonstrate how to manage indexes, see +:ref:`ruby-indexes`. + +To learn more about compound indexes, see :manual:`Compound +Indexes ` in the {+mdb-server+} manual. + +API Documentation +~~~~~~~~~~~~~~~~~ + +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>`__ +- `find <{+api-root+}/Mongo/Collection.html#find-instance_method>`__ From fdd4dc9347f2fe200c6d842f1fff94d6e2793e50 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Dec 2024 19:13:42 -0500 Subject: [PATCH 2/8] fix ref --- source/indexes/compound-index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index bfa82817..25373850 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -1,4 +1,4 @@ -.. ruby-compound-index: +.. _ruby-compound-index: ================ Compound Indexes From cffb0880fad10af99b00df3766b4d30c1d13b9bb Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Dec 2024 19:16:06 -0500 Subject: [PATCH 3/8] fix code comment spacing --- source/includes/indexes/compound.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/indexes/compound.rb b/source/includes/indexes/compound.rb index cb762498..99120191 100644 --- a/source/includes/indexes/compound.rb +++ b/source/includes/indexes/compound.rb @@ -20,8 +20,8 @@ # end-index-compound # start-index-compound-query -# Finds a document with the specified runtime and release year -# by using the newly created index +# Finds a document with the specified runtime and release year by using the +# newly created index filter = { '$and' => [ { 'runtime': { '$gt' => 90 } }, { 'year': { '$gt' => 2005 } } From 13917aa3f3653bfd1ca2846ea835eb00cf174a97 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Dec 2024 19:18:07 -0500 Subject: [PATCH 4/8] specify create one ref --- source/indexes/compound-index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index 25373850..d4b6e3f3 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -120,5 +120,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 3d55188453ce8b0e525b388e0947c0b6736b823a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 16 Dec 2024 19:19:57 -0500 Subject: [PATCH 5/8] bold single field --- source/indexes/single-field-index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt index 61cf10d5..57bfc66e 100644 --- a/source/indexes/single-field-index.txt +++ b/source/indexes/single-field-index.txt @@ -20,7 +20,7 @@ Single Field Indexes Overview -------- -Single field indexes are indexes with a reference to a single field of a +**Single field indexes** are indexes with a reference to a single field of a document in a collection. These indexes improve single field query and sort performance. They also support :manual:`TTL Indexes ` that automatically remove documents from a collection after a certain From 72778beee106927a2a5f1a7a183bb809d50f50a6 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 17 Dec 2024 11:52:40 -0500 Subject: [PATCH 6/8] tech review comment --- source/includes/indexes/compound.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/indexes/compound.rb b/source/includes/indexes/compound.rb index 99120191..dabdf675 100644 --- a/source/includes/indexes/compound.rb +++ b/source/includes/indexes/compound.rb @@ -23,8 +23,8 @@ # Finds a document with the specified runtime and release year by using the # newly created index filter = { '$and' => [ - { 'runtime': { '$gt' => 90 } }, - { 'year': { '$gt' => 2005 } } + { runtime: { '$gt' => 90 } }, + { year: { '$gt' => 2005 } } ] } doc = collection.find(filter).first From 241a5e2558350ed91a5203d0fbc911850d5c2e35 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Thu, 19 Dec 2024 17:49:55 -0500 Subject: [PATCH 7/8] remove comments from snippet and spacing fix --- source/includes/indexes/compound.rb | 7 +++---- source/indexes/compound-index.txt | 3 ++- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/source/includes/indexes/compound.rb b/source/includes/indexes/compound.rb index dabdf675..4c0f9a26 100644 --- a/source/includes/indexes/compound.rb +++ b/source/includes/indexes/compound.rb @@ -14,14 +14,13 @@ collection = database[:movies] # end-sample-data -# start-index-compound # Creates an index on the "runtime" and "year" field +# start-index-compound collection.indexes.create_one({ runtime: -1, year: 1 }) # end-index-compound +# Finds a document with the specified runtime and release year by using the newly created index # start-index-compound-query -# Finds a document with the specified runtime and release year by using the -# newly created index filter = { '$and' => [ { runtime: { '$gt' => 90 } }, { year: { '$gt' => 2005 } } @@ -35,7 +34,7 @@ end # end-index-compound-query -# start-check-compound-index # Lists all indexes on the collection +# start-check-compound-index puts collection.indexes.collect(&:to_json) # end-check-compound-index diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index d4b6e3f3..9df98ea4 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -64,6 +64,8 @@ in ascending order on the ``year`` field: :language: ruby :copyable: +To verify the index's creation, you can list the + Verify Index Creation --------------------- @@ -71,7 +73,6 @@ You can verify that the index was created by listing the indexes in the collection. You should see an index for ``runtime`` and ``year`` in the list, as shown in the following output: - .. io-code-block:: :copyable: true From 3cd16f2f20f95720bb84bcba6d30c532121d9e93 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 20 Dec 2024 15:18:33 -0500 Subject: [PATCH 8/8] repeated text --- source/indexes/compound-index.txt | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/source/indexes/compound-index.txt b/source/indexes/compound-index.txt index 9df98ea4..426fea72 100644 --- a/source/indexes/compound-index.txt +++ b/source/indexes/compound-index.txt @@ -62,9 +62,7 @@ in ascending order on the ``year`` field: :start-after: start-index-compound :end-before: end-index-compound :language: ruby - :copyable: - -To verify the index's creation, you can list the + :copyable: Verify Index Creation ---------------------