Skip to content

Commit ca9a84d

Browse files
jordan-smith721jordan-smith721
authored
DOCSP-45357 Sharding Configuration (#76)
1 parent 469d562 commit ca9a84d

File tree

7 files changed

+280
-5
lines changed

7 files changed

+280
-5
lines changed

‎snooty.toml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,9 @@ toc_landing_pages = [
1111
"/quick-start-sinatra",
1212
"/interact-data",
1313
"/interact-data/specify-query",
14-
"/data-modeling"
15-
]
14+
"/data-modeling",
15+
"/configuration",
16+
]
1617

1718
[constants]
1819
rails-6-version = 6.0

‎source/configuration.txt‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. _mongoid-configuration:
2+
3+
=============
4+
Configuration
5+
=============
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: ruby framework, odm, setup, config
13+
14+
.. toctree::
15+
:caption: Configuration
16+
17+
Sharding </configuration/sharding>
18+
19+
In this section, you can learn how to configure different options with {+odm+}.
20+
21+
- :ref:`Sharding Configuration <mongoid-sharding-configuration>`: Learn how to configure
22+
sharding in your {+odm+} application.

‎source/configuration/sharding.txt‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
.. _mongoid-sharding-configuration:
2+
3+
======================
4+
Sharding Configuration
5+
======================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: ruby framework, odm, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
Sharding is a way to distribute your data across multiple machines. MongoDB
24+
uses sharding to support deployments with large data sets and high
25+
throughput operations. In this guide, you can learn how to configure sharding in
26+
your {+odm+} application.
27+
28+
Declare Shard keys
29+
------------------
30+
31+
MongoDB uses shard keys to distribute a collection's documents across
32+
shards. A shard key is an indexed field, or multiple fields covered by a
33+
compound index, that determines the distribution of the collection's
34+
documents among the cluster's shards. In your
35+
{+odm+} application, you can declare a shard key by
36+
using the ``shard_key`` macro when you create a model.
37+
38+
The following example creates a ``Person`` class with a shard key on the
39+
``ssn`` field:
40+
41+
.. literalinclude:: /includes/configuration/sharding.rb
42+
:language: ruby
43+
:start-after: # start-shard-key
44+
:end-before: # end-shard-key
45+
:emphasize-lines: 6
46+
47+
.. note::
48+
49+
To shard a collection, the collection must have an index that starts with the
50+
shard key. The index can be on only the shard key, or it can be a compound index
51+
where the shard key is the prefix. You can use {+odm+}'s index-management
52+
functionality to create the index. To learn more about index management with
53+
{+odm+}, see the :ref:`Index Management <mongoid-indexes>` guide.
54+
55+
If a model declares a shard key, {+odm+} expects the sharded collection to
56+
use the declared key for sharding. When {+odm+} reloads models, it provides
57+
the shard key along with the ``_id`` field to the ``find`` command to improve query
58+
performance. If the collection is not sharded with the specified shard key,
59+
queries might not return the expected results.
60+
61+
Syntax
62+
~~~~~~
63+
64+
You can declare shard keys by using either the full MongoDB
65+
syntax or by using a shorthand syntax.
66+
67+
The full syntax follows the format
68+
of the ``mongosh`` :manual:`shardCollection()
69+
</reference/method/sh.shardCollection>` method, and allows you to specify the
70+
following types of shard keys:
71+
72+
- Ranged keys
73+
- Hashed keys
74+
- Compound keys
75+
76+
The full syntax also allows you to specify collection and sharding options.
77+
78+
The following example creates each of the preceding type of shard key on the
79+
``sson`` field:
80+
81+
.. literalinclude:: /includes/configuration/sharding.rb
82+
:language: ruby
83+
:start-after: # start-shard-key-formats
84+
:end-before: # end-shard-key-formats
85+
86+
The shorthand syntax allows you to declare a shard key by specifying only the
87+
field name. This syntax supports only ranged and compound shard keys, and does not allow you
88+
to specify collection or sharding options.
89+
90+
The following example creates a ranged and a compound shard key:
91+
92+
.. literalinclude:: /includes/configuration/sharding.rb
93+
:language: ruby
94+
:start-after: # start-shard-key-shorthand
95+
:end-before: # end-shard-key-shorthand
96+
97+
Specify Associated and Embedded Fields
98+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
99+
100+
You can specify a shard key on a ``belongs_to`` association in place of a field
101+
name. When doing so, {+odm+} creates the shard key on the primary key of the
102+
associated collection.
103+
104+
The following example creates a shard key on the ``belongs_to`` association in a
105+
``Person`` model. Because the associated ``country`` collection has a primary
106+
key called ``country_id``, {+odm+} shards by that field:
107+
108+
.. literalinclude:: /includes/configuration/sharding.rb
109+
:language: ruby
110+
:start-after: # start-shard-key-association
111+
:end-before: # end-shard-key-association
112+
113+
You can specify a shard key on an embedded document by using dot notation to
114+
delimit the field names. The following example creates a shard key on the
115+
``address.city`` field:
116+
117+
.. literalinclude:: /includes/configuration/sharding.rb
118+
:language: ruby
119+
:start-after: # start-shard-key-embedded
120+
:end-before: # end-shard-key-embedded
121+
122+
.. note::
123+
124+
Because the period (``.``) character is used to delimit embedded fields, {+odm+} does
125+
not support creating shard keys on fields with names that contain a period
126+
character.
127+
128+
Sharding Management Rake Tasks
129+
------------------------------
130+
131+
You can shard collections in your database according to the shard keys defined
132+
in your {+odm+} models by running the ``db:mongoid:shard_collections`` rake
133+
task. To ensure that the collections contain indexes that start with the shard
134+
key, you can first run the ``db:mongoid:create_indexes`` rake task.
135+
136+
Run the following rake commands to create the indexes and shard the collections
137+
based on your model's shard keys:
138+
139+
.. code-block:: bash
140+
141+
rake db:mongoid:create_indexes
142+
rake db:mongoid:shard_collections
143+
144+
Index management and sharding rake tasks do not stop when they encounter an
145+
error with a particular model class. Instead, they log the error and continue
146+
processing the next model. To ensure the rake tasks did not encounter any
147+
errors, check the output of the {+odm+} logger configured for your application.
148+
149+
.. note::
150+
151+
When performing schema-related operations in a sharded cluster, nodes might
152+
contain out-of-date local configuration-related cache data. To clear the caches,
153+
run the :manual:`flushRouterConfig </reference/command/flushRouterConfig/>`
154+
command on each ``mongos`` node.
155+
156+
157+
Additional Information
158+
----------------------
159+
160+
To learn more about sharding with MongoDB, see the :manual:`Sharding
161+
</sharding>` guide in the MongoDB {+server-manual+}.
162+
163+
API Documentation
164+
~~~~~~~~~~~~~~~~~
165+
166+
To learn more about the ``shard_key`` macro discussed in this
167+
guide, see the `shard_key
168+
<{+api-root+}/Shardable/ClassMethods.html#shard_key-instance_method>`__ API
169+
documentation.

‎source/data-relationships/associations.txt‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. _mongoid_associations:
2+
3+
============
4+
Associations
5+
============
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: ruby framework, odm, code example
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
Associations in {+odm+} allow you to create relationships between models.

‎source/includes/configuration/sharding.rb‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# start-shard-key
2+
class Person
3+
include Mongoid::Document
4+
5+
field :ssn
6+
7+
shard_key ssn: 1
8+
9+
# The collection must also have an index that starts with the shard key.
10+
index ssn: 1
11+
end
12+
# end-shard-key
13+
14+
# start-shard-key-formats
15+
# Create a ranged shard key
16+
shard_key ssn: 1
17+
18+
# Create a compound shard key
19+
shard_key ssn: 1, country: 1
20+
21+
# Create a hashed shard key
22+
shard_key ssn: :hashed
23+
24+
# Specify a shard key option
25+
shard_key {ssn: :hashed}, unique: true
26+
# end-shard-key-formats
27+
28+
# start-shard-key-shorthand
29+
# Create a ranged shard key
30+
shard_key :ssn
31+
32+
# Create a compound shard key
33+
shard_key :ssn, :country
34+
# end-shard-key-shorthand
35+
36+
# start-shard-key-association
37+
class Person
38+
include Mongoid::Document
39+
40+
belongs_to :country
41+
42+
# Shards by country_id
43+
shard_key country: 1
44+
45+
# The collection must have an index that starts with the shard key
46+
index country: 1
47+
end
48+
# end-shard-key-association
49+
50+
# start-shard-key-embedded
51+
class Person
52+
include Mongoid::Document
53+
54+
field :address
55+
56+
shard_key "address.city"
57+
end
58+
# end-shard-key-embedded

‎source/index.txt‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@ MongoDB in Ruby. To work with {+odm+} from the command line using
1717
Add {+odm+} to an Existing Application </add-existing>
1818
Interact with Data </interact-data>
1919
Model Your Data </data-modeling>
20-
installation-configuration
21-
tutorials
22-
schema-configuration
20+
Configuration </configuration>
21+
.. installation-configuration
22+
.. tutorials
23+
.. schema-configuration
2324
working-with-data
2425
API <https://mongodb.com/docs/mongoid/master/api/>
2526
/release-notes

‎source/reference/indexes.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
.. _mongoid-indexes:
12
.. _indexes:
23

34
****************

0 commit comments

Comments
 (0)