/
administer-shard-tags.txt
118 lines (82 loc) · 3.64 KB
/
administer-shard-tags.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
=================
Manage Shard Tags
=================
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
In a sharded cluster, you can use tags to associate specific ranges of
a :term:`shard key` with a specific :term:`shard` or subset of shards.
Tag a Shard
-----------
Associate tags with a particular shard using the
:method:`sh.addShardTag()` method when connected to a :binary:`~bin.mongos`
instance. A single shard may have multiple tags, and multiple shards
may also have the same tag.
.. example::
The following example adds the tag ``NYC`` to two shards, and the tags
``SFO`` and ``NRT`` to a third shard:
.. code-block:: javascript
sh.addShardTag("shard0000", "NYC")
sh.addShardTag("shard0001", "NYC")
sh.addShardTag("shard0002", "SFO")
sh.addShardTag("shard0002", "NRT")
You may remove tags from a particular shard using the
:method:`sh.removeShardTag()` method when connected to a
:binary:`~bin.mongos` instance, as in the following example, which removes
the ``NRT`` tag from a shard:
.. code-block:: javascript
sh.removeShardTag("shard0002", "NRT")
Tag a Shard Key Range
---------------------
To assign a tag to a range of shard keys use the
:method:`sh.addTagRange()` method when connected to a
:binary:`~bin.mongos` instance. Any given shard key range may only have
*one* assigned tag. You cannot overlap defined ranges, or tag the same
range more than once.
.. example::
Given a collection named ``users`` in the ``records`` database,
sharded by the ``zipcode`` field. The following operations assign:
- two ranges of zip codes in Manhattan and Brooklyn the ``NYC`` tag
- one range of zip codes in San Francisco the ``SFO`` tag
.. code-block:: javascript
sh.addTagRange("records.users", { zipcode: "10001" }, { zipcode: "10281" }, "NYC")
sh.addTagRange("records.users", { zipcode: "11201" }, { zipcode: "11240" }, "NYC")
sh.addTagRange("records.users", { zipcode: "94102" }, { zipcode: "94135" }, "SFO")
.. note::
.. include:: /includes/fact-shard-ranges-inclusive-exclusive.rst
Remove a Tag From a Shard Key Range
-----------------------------------
The :binary:`~bin.mongod` does not provide a helper for removing a tag
range. You may delete tag assignment from a shard key range by removing
the corresponding document from the :data:`~config.tags` collection of
the ``config`` database.
Each document in the :data:`~config.tags` holds the :term:`namespace`
of the sharded collection and a minimum shard key value.
.. example::
The following example removes the ``NYC`` tag assignment for the
range of zip codes within Manhattan:
.. code-block:: javascript
use config
db.tags.remove({ _id: { ns: "records.users", min: { zipcode: "10001" }}, tag: "NYC" })
View Existing Shard Tags
------------------------
The output from :method:`sh.status()` lists tags associated with a
shard, if any, for each shard. A shard's tags exist in the shard's
document in the :data:`~config.shards` collection of the ``config``
database. To return all shards with a specific tag, use a sequence of
operations that resemble the following, which will return only those
shards tagged with ``NYC``:
.. code-block:: javascript
use config
db.shards.find({ tags: "NYC" })
You can find tag ranges for all :term:`namespaces <namespace>` in the
:data:`~config.tags` collection of the ``config`` database. The output
of :method:`sh.status()` displays all tag ranges. To return all shard
key ranges tagged with ``NYC``, use the following sequence of
operations:
.. code-block:: javascript
use config
db.tags.find({ tags: "NYC" })