-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
Copy pathsh.addTagRange.txt
171 lines (106 loc) · 4.89 KB
/
sh.addTagRange.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
================
sh.addTagRange()
================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: sh.addTagRange(namespace, minimum, maximum, tag)
.. |method| replace:: :method:`sh.updateZoneKeyRange()`
.. include:: /includes/fact-zone-sharding-alias.rst
Attaches a range of shard key values to a shard tag created using the
:method:`sh.addShardTag()` method.
.. include:: /includes/extracts/zoned-sharding-updateZoneKeyRange-change.rst
:method:`sh.addTagRange()` takes
the following arguments:
.. list-table::
:header-rows: 1
:widths: 20 20 80
* - Parameter
- Type
- Description
* - ``namespace``
- string
- The :term:`namespace` of the sharded collection to tag.
* - ``minimum``
- document
- The minimum value of the :term:`shard key` range to include in the
tag. The minimum is an inclusive match. Specify the minimum value in
the form of ``<fieldname>:<value>``. This value must be of the same
BSON type or types as the shard key.
* - ``maximum``
- document
- The maximum value of the shard key range to include in the tag.
The maximum is an exclusive match. Specify the maximum value in the
form of ``<fieldname>:<value>``. This value must be of the same BSON
type or types as the shard key.
* - ``tag``
- string
- The name of the tag to attach the range specified by the ``minimum``
and ``maximum`` arguments to.
Use :method:`sh.addShardTag()` to ensure that the balancer migrates
documents that exist within the specified range to a specific shard
or set of shards.
Only issue :method:`sh.addTagRange()` when connected to a
:binary:`~bin.mongos` instance.
Compatibility
-------------
This method is available in deployments hosted in the following environments:
.. include:: /includes/fact-environments-atlas-only.rst
.. include:: /includes/fact-environments-atlas-support-no-free.rst
.. include:: /includes/fact-environments-onprem-only.rst
Behavior
--------
Bounds
~~~~~~
.. include:: /includes/fact-shard-ranges-inclusive-exclusive.rst
.. _addTagRange-method-init-chunk-distribution:
Initial Chunk Distribution for Empty or Non-Existing Collections
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are considering performing :ref:`zone sharding <zone-sharding>`
on an empty or non-existent collection, use :method:`sh.addTagRange()`
to create the zones and zone ranges *before* sharding the collection.
Creating zones and zone ranges on empty or non-existing collections allows
MongoDB to optimize the initial chunk creation and distribution process when
sharding the collection. This optimized process supports faster setup of zoned
sharding with less balancer overhead than creating zones after sharding. The
:ref:`balancer <sharding-balancing>` performs all chunk management after the
optimized initial chunk creation and distribution.
For an example of defining zones and zone ranges for initial chunk
distribution, see :ref:`pre-define-zone-range-example`.
Initial Chunk Distribution with Compound Hashed Shard Keys
``````````````````````````````````````````````````````````
MongoDB supports sharding collections on
:ref:`compound hashed indexes <index-type-compound-hashed>`. MongoDB can
perform optimized initial chunk creation and distribution when sharding
the empty or non-existing collection on a compound hashed shard key.
.. tabs::
.. tab:: Hashed Field Is Prefix
:tabid: hash-prefix
.. include:: /includes/extracts/zoned-sharding-chunk-distribution-compound-hashed-prefix.rst
.. tab:: Hashed Field is Not Prefix
:tabid: hash-not-prefix
.. include:: /includes/extracts/zoned-sharding-chunk-distribution-compound-hashed-not-prefix.rst
For a more complete example of defining zones and zone ranges for
initial chunk distribution on a compound hashed shard key, see
:ref:`pre-define-zone-range-hashed-example`.
Dropped Collections
~~~~~~~~~~~~~~~~~~~
.. include:: /includes/extracts/zoned-sharding-drop-collection-change.rst
In earlier versions, MongoDB does not remove the tag associations for a
dropped collection, and if you later create a new collection with the
same name, the old tag associations will apply to the new collection.
Example
-------
Given a shard key of ``{state: 1, zip: 1}``, the following operation
creates a tag range covering zip codes in New York State:
.. code-block:: javascript
sh.addTagRange( "exampledb.collection",
{ state: "NY", zip: MinKey },
{ state: "NY", zip: MaxKey },
"NY"
)