/
sh.removeRangeFromZone.txt
177 lines (114 loc) · 4.98 KB
/
sh.removeRangeFromZone.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
172
173
174
175
176
========================
sh.removeRangeFromZone()
========================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: sh.removeRangeFromZone(namespace, minimum, maximum)
.. versionadded:: 3.4
Removes the association between a range of shard key values and a
:term:`zone`.
:method:`sh.removeRangeFromZone()` 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 associate with the zone.
The collection must be sharded for the operation to succeed.
* - ``minimum``
- document
- The inclusive lower bound of the range of :term:`shard key` values.
Specify each field of the shard key in the form of ``<fieldname> : <value>``.
The value must be of the same BSON type or types as the shard key.
* - ``maximum``
- document
- The exclusive upper bound of the range of :term:`shard key` values.
Specify each field of the shard key in the form of ``<fieldname> : <value>``.
The value must be of the same BSON type or types as the shard key.
Use :method:`sh.removeRangeFromZone()` to remove the association between
unused, out of date, or conflicting ranges and a zone.
If no range matches the minimum and maximum bounds passed to
:method:`~sh.removeShardFromZone()`, nothing is removed.
Only issue :method:`sh.removeTagRange()` when connected to a
:binary:`~bin.mongos` instance.
Behavior
--------
:method:`sh.removeShardFromZone()` does not remove the zone associated to the
specified range.
See the :ref:`zone <zone-sharding>` manual page for more information on zones
in sharded clusters.
Balancer
~~~~~~~~
Removing the association between a range and a zone removes the constraints
keeping chunks covered by the range on the shards inside that zone. During the
next balancer round, the balancer may migrate chunks that were previously
covered by the zone.
See the documentation for the :ref:`sharded cluster balancer
<sharding-balancing>` for more information on how migrations work in a sharded
cluster.
Security
~~~~~~~~
For sharded clusters running with :ref:`authentication <authentication>`, you
must authenticate as either:
- a user whose privileges include the specified actions on various
collections in the ``config`` database:
- :authaction:`find` on the ``config.shards`` collection
- :authaction:`find`, :authaction:`update`, and :authaction:`remove`
on the ``config.tags`` collection;
or, alternatively
- a user whose privileges include :authaction:`enableSharding` on the
:ref:`cluster <resource-specific-collection>` resource (available
starting in version 3.6.16).
The :authrole:`clusterAdmin` or :authrole:`clusterManager` built-in roles have
the appropriate permissions for issuing :method:`sh.removeRangeFromZone()`.
See the documentation page for :ref:`Role-Based Access Control
<authorization>` for more information.
Example
-------
Given a sharded collection ``exampledb.collection`` with a shard key of ``{ a
: 1 }``, the following operation removes the range with a lower bound of ``1``
and an upper bound of ``10``:
.. code-block:: javascript
sh.removeRangeFromZone( "exampledb.collection",
{ a : 1 },
{ a : 10 }
)
The ``min`` and ``max`` must match exactly the bounds of the target range.
The following operation attempts to remove the previously created range, but
specifies ``{ a : 0 }`` as the ``min`` bound:
.. code-block:: javascript
admin = db.getSiblingDB("admin")
admin.runCommand(
{
updateZoneKeyRange : "exampledb.collection",
min : { a : 0 },
max : { a : 10 },
zone : null
}
)
While the range of ``{ a : 0 }`` and ``{ a : 10 }`` encompasses the existing
range, it is not an exact match and therefore
:method:`sh.removeRangeFromZone()` does not remove anything.
Compound Shard Key
~~~~~~~~~~~~~~~~~~
Given a sharded collection ``exampledb.collection`` with a shard key of
``{ a : 1, b : 1 }``, the following operation removes the range with a lower
bound of ``{ a : 1, b : 1}`` and an upper bound of ``{ a : 10, b : 10 }``:
.. code-block:: javascript
sh.removeRangeFromZone( "exampledb.collection",
{ a : 1, b : 1 },
{ a : 10, b : 10 }
)
Given the previous example, if there was an existing range with a lower bound
of ``{ a : 1, b : 5 }`` and an upper bound of ``{ a : 10, b : 1 }``, the
operation would *not* remove that range, as it is not an exact match of the
minimum and maximum passed to :method:`sh.removeRangeFromZone()`.