DOCSP-45203 Single Field Indexes

snooty.toml

@@ -3,7 +3,8 @@ title = "Ruby MongoDB Driver"
 toc_landing_pages = [
     "/get-started",
     "/connect",
-    "/write"
+    "/write",
+    "/indexes"
 ]
 
 intersphinx = ["https://www.mongodb.com/docs/manual/objects.inv"]

source/includes/indexes/single-field.rb

@@ -0,0 +1,37 @@
+require 'mongo'
+
+# Replace the placeholders with your credentials
+uri = "<connection string>"
+
+# Sets the server_api field of the options object to Stable API version 1
+options = { server_api: { version: "1" }}
+
+# Creates a new client and connect to the server
+client = Mongo::Client.new(uri, options)
+
+# start-sample-data
+database = client.use('sample_mflix')
+collection = database[:movies]
+# end-sample-data
+
+# start-index-single
+# Creates an index on the "title" field
+collection.indexes.create_one({ title: 1 })
+# end-index-single
+
+# start-index-single-query
+# Finds a document with the title "Sweethearts" by using the newly created index
+filter = { title: 'Sweethearts' }
+doc = collection.find(filter).first
+
+if doc
+  puts doc.to_json
+else
+  puts "No document found"
+end
+# end-index-single-query
+
+# start-check-single-index
+# Lists all indexes on the collection
+puts collection.indexes.collect(&:to_json)
+# end-check-single-index

source/index.txt

@@ -16,6 +16,7 @@
    Connect </connect>
    Write Data </write>
    Read Data </read>
+   Indexes </indexes>
    View the Source <https://github.com/mongodb/mongo-ruby-driver>
    API Documentation <{+api-root+}>
    Compatibility </compatibility>
@@ -24,7 +25,6 @@
  Databases & Collections </databases-collections>
  Write Data </write>
  Operations on Replica Sets </read-write-pref>
- Indexes </indexes>
  Monitor Your Application </monitoring>
  Data Aggregation </aggregation>
  Security </security>

source/indexes.txt

@@ -0,0 +1,36 @@
+.. _ruby-indexes:
+
+=================================
+Optimize Queries by Using Indexes
+=================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :description: Learn how to use indexes by using the MongoDB Scala Driver.
+   :keywords: query, optimization, efficiency, usage example, code example
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 1
+
+   Single Field </indexes/single-field-index>
+..   Compound </indexes/compound-index>
+..   Multikey </indexes/multikey-index>
+..   Atlas Search </indexes/atlas-search-index>
+
+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

source/indexes/single-field-index.txt

@@ -0,0 +1,135 @@
+.. _ruby-single-field-index:
+
+====================
+Single Field Indexes
+====================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: index, query, optimization, efficiency
+
+Overview
+--------
+
+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 </core/index-ttl>`
+that automatically remove documents from a collection after a certain
+amount of time or at a specified clock time.
+
+When creating a single field index, you must specify the following
+details:
+
+- The field on which to create the index
+- The sort order for the indexed values as either ascending or
+  descending
+
+.. note::
+
+   The default ``_id_`` index is an example of a single field index.
+   This index is automatically created on the ``_id`` field when a new
+   collection is created.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``movies`` collection in the
+``sample_mflix`` database from the :atlas:`Atlas sample datasets
+</sample-data>`. 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
+</getting-started>` guide.
+
+Create a Single Field Index
+---------------------------
+
+Use the ``create_one`` method to create a single
+field index. The following example creates an index in ascending order on the
+``title`` field:
+
+.. literalinclude:: /includes/indexes/single-field.rb
+   :start-after: start-index-single
+   :end-before: end-index-single
+   :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 ``title`` in the list, as shown 
+in the following output:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/indexes/single-field.rb
+      :start-after: start-check-single-index
+      :end-before: end-check-single-index
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: true
+
+      {"v": 2, "key": {"title": 1}, "name": "title_1"}
+
+Example Query
+-------------
+
+The following is an example of a query that is covered by the index
+created on the ``title`` field:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input:: /includes/indexes/single-field.rb
+      :start-after: start-index-single-query
+      :end-before: end-index-single-query
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id":...,"plot":"A musical comedy duo...",
+      "genres":["Musical"],...,"title":"Sweethearts",...}
+
+Additional Information
+----------------------
+
+To view runnable examples that demonstrate how to manage indexes, see
+:ref:`ruby-indexes`.
+
+To learn more about single field indexes, see :manual:`Single Field
+Indexes </core/index-single>` 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>`__