From 0ef4d5e9adc208cadf2fa0f5931a5fd78d89732e Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 23 Jan 2025 10:23:16 -0800 Subject: [PATCH 1/3] Collection configuration page: --- source/configuration.txt | 6 +- source/configuration/collection-config.txt | 104 ++++++++++++++++++ .../configuration/collection-config.rb | 39 +++++++ 3 files changed, 147 insertions(+), 2 deletions(-) create mode 100644 source/configuration/collection-config.txt create mode 100644 source/includes/configuration/collection-config.rb diff --git a/source/configuration.txt b/source/configuration.txt index 1c486bc..120bb27 100644 --- a/source/configuration.txt +++ b/source/configuration.txt @@ -20,8 +20,7 @@ Configuration Logging Query Cache Middleware Forking Servers - -.. Collection Configuration + Collection Configuration In this section, you can learn how to configure different options with {+odm+}. @@ -42,3 +41,6 @@ In this section, you can learn how to configure different options with {+odm+}. - :ref:`mongoid-forking-server-config`: Learn how to configure your application to use a forking web server. + +- :ref:`mongoid-collection-config`: Learn how to specify configuration options + for a collection in your application. diff --git a/source/configuration/collection-config.txt b/source/configuration/collection-config.txt new file mode 100644 index 0000000..cf236ee --- /dev/null +++ b/source/configuration/collection-config.txt @@ -0,0 +1,104 @@ +.. _mongoid-collection-config: + +======================== +Collection Configuration +======================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, collections, time series, capped collection + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to specify configuration options for a +collection in your {+odm+} application. + +Configure Collection Options +---------------------------- + +You can specify configuration options for a collection by using the +``:collection_options`` argument with the ``store_in`` +macro. The ``:collection_options`` argument accepts any collection option that +your driver and server version supports. + +.. note:: + + To apply the collection options, your collection must be explicitly created + prior to use. To learn how to create a collection using a Rake task, see the + :ref:`mongoid-create-collection-rake` section of this guide. + +To learn more about collection options available in the {+ruby-driver+}, see the +:ruby:`Collections ` guide in the {+ruby-driver+} +documentation. + +The following sections show examples of how to configure collection options with +{+odm+}. + +Time Series Collection +~~~~~~~~~~~~~~~~~~~~~~ + +Time series collections efficiently store sequences of measurements over a +period of time. The following example shows how to configure a time series +collection with +{+odm+}: + +.. literalinclude:: /includes/configuration/collection-config.rb + :language: ruby + :start-after: # start-time-series-config + :end-before: # end-time-series-config + +Capped Collection +~~~~~~~~~~~~~~~~~ + +Capped collections have maximum size or document counts that prevent them from +growing beyond maximum thresholds. The following example shows how to configure +a capped collectionq with {+odm+}: + +.. literalinclude:: /includes/configuration/collection-config.rb + :language: ruby + :start-after: # start-capped-config + :end-before: # end-capped-config + +Default Collation +~~~~~~~~~~~~~~~~~ + +Collations are sets of rules for how to compare strings, typically in a +particular natural language. The following example shows how to specify a +default collation to use on a +collection with {+odm+}: + +.. literalinclude:: /includes/configuration/collection-config.rb + :language: ruby + :start-after: # start-default-collation-config + :end-before: # end-default-collation-config + +.. _mongoid-create-collection-rake: + +Collection Management Rake Task +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To apply the collection options you specify in your {+odm+} application, you +must explicitly create the corresponding collection. To do so, use the +``db:mongoid:create_collections`` Rake task by running the following command in +your shell: + +.. code-block:: bash + + rake db:mongoid:create_collections + +You can also run the ``create_collection`` command on a single model in the +Rails console, as shown in the following example: + +.. code-block:: ruby + + Model.create_collection diff --git a/source/includes/configuration/collection-config.rb b/source/includes/configuration/collection-config.rb new file mode 100644 index 0000000..b3291ea --- /dev/null +++ b/source/includes/configuration/collection-config.rb @@ -0,0 +1,39 @@ +# start-time-series-config +class Measurement + include Mongoid::Document + + field :temperature, type: Integer + field :timestamp, type: Time + + store_in collection_options: { + time_series: { + timeField: "timestamp", + granularity: "minutes" + }, + expire_after: 604800 + } +end +# end-time-series-config + +# start-capped-collection-config +class Name + include Mongoid::Document + + store_in collection_options: { + capped: true, + size: 1024 + } +end +# end-capped-collection-config + +# start-default-collation-config +class Name + include Mongoid::Document + + store_in collection_options: { + collation: { + locale: 'fr' + } + } +end +# end-default-collation-config \ No newline at end of file From f4b9e22fa819c76bf37b662e56835df96cf875ce Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Thu, 23 Jan 2025 10:36:25 -0800 Subject: [PATCH 2/3] typos --- source/configuration/collection-config.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/configuration/collection-config.txt b/source/configuration/collection-config.txt index cf236ee..625cc19 100644 --- a/source/configuration/collection-config.txt +++ b/source/configuration/collection-config.txt @@ -62,12 +62,12 @@ Capped Collection Capped collections have maximum size or document counts that prevent them from growing beyond maximum thresholds. The following example shows how to configure -a capped collectionq with {+odm+}: +a capped collection with {+odm+}: .. literalinclude:: /includes/configuration/collection-config.rb :language: ruby - :start-after: # start-capped-config - :end-before: # end-capped-config + :start-after: # start-capped-collection-config + :end-before: # end-capped-collection-config Default Collation ~~~~~~~~~~~~~~~~~ @@ -85,7 +85,7 @@ collection with {+odm+}: .. _mongoid-create-collection-rake: Collection Management Rake Task -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------- To apply the collection options you specify in your {+odm+} application, you must explicitly create the corresponding collection. To do so, use the From a38b3300b9152f62a812da27360956cbb014a4bd Mon Sep 17 00:00:00 2001 From: Jordan Smith Date: Fri, 24 Jan 2025 07:05:36 -0800 Subject: [PATCH 3/3] feedback --- source/configuration.txt | 2 +- source/configuration/collection-config.txt | 33 ++++++++++++------- .../configuration/collection-config.rb | 4 +-- 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/source/configuration.txt b/source/configuration.txt index 120bb27..aa20b4a 100644 --- a/source/configuration.txt +++ b/source/configuration.txt @@ -43,4 +43,4 @@ In this section, you can learn how to configure different options with {+odm+}. application to use a forking web server. - :ref:`mongoid-collection-config`: Learn how to specify configuration options - for a collection in your application. + for a MongoDB collection in your application. diff --git a/source/configuration/collection-config.txt b/source/configuration/collection-config.txt index 625cc19..9d2c9e2 100644 --- a/source/configuration/collection-config.txt +++ b/source/configuration/collection-config.txt @@ -29,45 +29,52 @@ Configure Collection Options You can specify configuration options for a collection by using the ``:collection_options`` argument with the ``store_in`` macro. The ``:collection_options`` argument accepts any collection option that -your driver and server version supports. +your {+ruby-driver+} and MongoDB server version supports. .. note:: - To apply the collection options, your collection must be explicitly created - prior to use. To learn how to create a collection using a Rake task, see the - :ref:`mongoid-create-collection-rake` section of this guide. + You must explicitly create a collection to apply any specified collection + options. Create your collection by running the collection management Rake task, as + shown in :ref:`mongoid-create-collection-rake` section of this guide. To learn more about collection options available in the {+ruby-driver+}, see the :ruby:`Collections ` guide in the {+ruby-driver+} documentation. -The following sections show examples of how to configure collection options with -{+odm+}. +The following sections show examples of how to configure collection options when +using {+odm+}. Time Series Collection ~~~~~~~~~~~~~~~~~~~~~~ Time series collections efficiently store sequences of measurements over a period of time. The following example shows how to configure a time series -collection with -{+odm+}: +collection: .. literalinclude:: /includes/configuration/collection-config.rb :language: ruby :start-after: # start-time-series-config :end-before: # end-time-series-config + :emphasize-lines: 7-13 + +To learn more about time series collections, see the :manual:`Time Series Collections +` guide in the MongoDB {+server-manual+}. Capped Collection ~~~~~~~~~~~~~~~~~ Capped collections have maximum size or document counts that prevent them from -growing beyond maximum thresholds. The following example shows how to configure -a capped collection with {+odm+}: +growing beyond a specified threshold. The following example shows how to configure +a capped collection: .. literalinclude:: /includes/configuration/collection-config.rb :language: ruby :start-after: # start-capped-collection-config :end-before: # end-capped-collection-config + :emphasize-lines: 4-7 + +To learn more about capped collections, see the :manual:`Capped Collections +` guide in the MongoDB {+server-manual+}. Default Collation ~~~~~~~~~~~~~~~~~ @@ -75,12 +82,16 @@ Default Collation Collations are sets of rules for how to compare strings, typically in a particular natural language. The following example shows how to specify a default collation to use on a -collection with {+odm+}: +collection: .. literalinclude:: /includes/configuration/collection-config.rb :language: ruby :start-after: # start-default-collation-config :end-before: # end-default-collation-config + :emphasize-lines: 4-8 + +To learn more about collations, see the :manual:`Collation +` guide in the MongoDB {+server-manual+}. .. _mongoid-create-collection-rake: diff --git a/source/includes/configuration/collection-config.rb b/source/includes/configuration/collection-config.rb index b3291ea..fc687d6 100644 --- a/source/includes/configuration/collection-config.rb +++ b/source/includes/configuration/collection-config.rb @@ -16,7 +16,7 @@ class Measurement # end-time-series-config # start-capped-collection-config -class Name +class Blog include Mongoid::Document store_in collection_options: { @@ -27,7 +27,7 @@ class Name # end-capped-collection-config # start-default-collation-config -class Name +class Title include Mongoid::Document store_in collection_options: {