diff --git a/snooty.toml b/snooty.toml index c79411ba..ae8757e1 100644 --- a/snooty.toml +++ b/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"] diff --git a/source/includes/indexes/single-field.rb b/source/includes/indexes/single-field.rb new file mode 100644 index 00000000..bbf1ff95 --- /dev/null +++ b/source/includes/indexes/single-field.rb @@ -0,0 +1,37 @@ +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-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 diff --git a/source/index.txt b/source/index.txt index 906cd450..d1b12dea 100644 --- a/source/index.txt +++ b/source/index.txt @@ -16,6 +16,7 @@ Connect Write Data Read Data + Indexes View the Source API Documentation <{+api-root+}> Compatibility @@ -24,7 +25,6 @@ Databases & Collections Write Data Operations on Replica Sets - Indexes Monitor Your Application Data Aggregation Security diff --git a/source/indexes.txt b/source/indexes.txt new file mode 100644 index 00000000..454bb8fd --- /dev/null +++ b/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 +.. Compound +.. Multikey +.. Atlas Search + +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 diff --git a/source/indexes/single-field-index.txt b/source/indexes/single-field-index.txt new file mode 100644 index 00000000..61cf10d5 --- /dev/null +++ b/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 ` +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 +`. 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 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 ` 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>`__