diff --git a/source/configuration.txt b/source/configuration.txt index 1c486bc..aa20b4a 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 MongoDB collection in your application. diff --git a/source/configuration/collection-config.txt b/source/configuration/collection-config.txt new file mode 100644 index 0000000..9d2c9e2 --- /dev/null +++ b/source/configuration/collection-config.txt @@ -0,0 +1,115 @@ +.. _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 {+ruby-driver+} and MongoDB server version supports. + +.. note:: + + 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 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: + +.. 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 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 +~~~~~~~~~~~~~~~~~ + +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: + +.. 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: + +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..fc687d6 --- /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 Blog + include Mongoid::Document + + store_in collection_options: { + capped: true, + size: 1024 + } +end +# end-capped-collection-config + +# start-default-collation-config +class Title + include Mongoid::Document + + store_in collection_options: { + collation: { + locale: 'fr' + } + } +end +# end-default-collation-config \ No newline at end of file