Skip to content

DOCSP-42743 Collection config #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 24, 2025
Merged

DOCSP-42743 Collection config #95

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0ef4d5e
Collection configuration page:
jordan-smith721 Jan 23, 2025
f4b9e22
typos
jordan-smith721 Jan 23, 2025
a38b330
feedback
jordan-smith721 Jan 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions source/configuration.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,7 @@ Configuration
Logging </configuration/logging-config>
Query Cache Middleware </configuration/query-cache-config>
Forking Servers </configuration/forking-server-config>

.. Collection Configuration </configuration/collection-config>
Collection Configuration </configuration/collection-config>

In this section, you can learn how to configure different options with {+odm+}.

Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
for a collection in your application.
for a MongoDB collection in your application.

104 changes: 104 additions & 0 deletions source/configuration/collection-config.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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

Check failure on line 37 in source/configuration/collection-config.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.Wordiness] Consider using 'before' instead of 'prior to'.

Raw Output:
{"message": "[MongoDB.Wordiness] Consider using 'before' instead of 'prior to'.", "location": {"path": "source/configuration/collection-config.txt", "range": {"start": {"line": 37, "column": 4}}}, "severity": "ERROR"}

Check failure on line 37 in source/configuration/collection-config.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.ConciseTerms] 'before' is preferred over 'prior to'.

Raw Output:
{"message": "[MongoDB.ConciseTerms] 'before' is preferred over 'prior to'.", "location": {"path": "source/configuration/collection-config.txt", "range": {"start": {"line": 37, "column": 4}}}, "severity": "ERROR"}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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
You must explicitly create a collection before you apply any collection options. To learn
how to create a collection by using a Rake task, see the

:ref:`mongoid-create-collection-rake` section of this guide.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: consider linking to docs in server or atlas about creating collections.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ended up rewording this section to better match what the original docs were saying. It says that it "should be done" by the Rake task so it seems to me like they want to point users that way rather than other ways of creating collection


To learn more about collection options available in the {+ruby-driver+}, see the
:ruby:`Collections </reference/collection-tasks/>` guide in the {+ruby-driver+}
documentation.

The following sections show examples of how to configure collection options with
{+odm+}.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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+}:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
collection with
{+odm+}:
collection:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: could be helpful to describe what the options in the code are doing. Or you can link out to docs on time series collections or both ideally

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I linked out to the manual for descriptions since the functionality of the collection isn't the focus of this page


.. 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 collection with {+odm+}:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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+}:
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

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+}:

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: same comment about explaining + linking

.. 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
39 changes: 39 additions & 0 deletions source/includes/configuration/collection-config.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

S: consider renaming these models as Name isnt very clear that its not a placeholder

Loading