sh.updateZoneKeyRange()

項目一覧

定義
互換性
動作
例

定義

sh.updateZoneKeyRange(namespace, minimum, maximum, zone)

Associates a range of shard key values with a ゾーン.

You can run updateZoneKeyRange database command and its helpers sh.updateZoneKeyRange() and sh.addTagRange() on an unsharded collection or a non-existing collection.

重要

mongosh メソッド

このページでは、mongosh メソッドについて記載しています。ただし、データベースコマンドや Node.js などの言語固有のドライバーのドキュメントには該当しません。

データベースコマンドについては、updateZoneKeyRange コマンドを参照してください。

MongoDB API ドライバーについては、各言語の MongoDB ドライバードキュメントを参照してください。

sh.updateZoneKeyRange()は次の引数を取ります。

Parameter	タイプ	説明
`namespace`	string	The namespace of the sharded collection associate with the `zone`. The collection must be sharded for the operation to succeed.
`minimum`	ドキュメント	シャードキー値の範囲の包括的下限。シャードキーの各フィールドを`<fieldname> : <value>`の形式で指定します。値は、シャードキーと同じ BSON type である必要があります。 To use hashed sharding, the field value needs to be of type `NumberLong`.
`maximum`	ドキュメント	シャードキー値の範囲の排他的上限。シャードキーの各フィールドを`<fieldname> : <value>`の形式で指定します。値は、シャードキーと同じ BSON type である必要があります。 To use hashed sharding, the field value needs to be of type `NumberLong`.
`zone`	string	The name of the zone to associate with the range of shard key values bounded by `minimum` and `maximum`.

sh.updateZoneKeyRange()インスタンスに接続されている場合にのみmongos を発行します。

互換性

このメソッドは、次の環境でホストされている配置で使用できます。

MongoDB Atlas はクラウドでの MongoDB 配置のためのフルマネージドサービスです

重要

このコマンドは、M0 、M2 、M5 、および Flex クラスターではサポートされていません。詳細については、「サポートされていないコマンド」を参照してください。

MongoDB Enterprise: サブスクリプションベースの自己管理型 MongoDB バージョン
MongoDB Community: ソースが利用可能で、無料で使用できる自己管理型の MongoDB のバージョン

動作

シャーディングされたコレクションの既存の範囲と下限と上限が重複するシャードキー値の範囲は作成できません。たとえば、 1から10の既存の範囲がある場合、 5から20の新しい範囲は作成できません。新しい範囲は既存の範囲と重複するためです。

ゾーンには複数のデータ範囲を関連付けることができますが、範囲は最大で 1 つのゾーンに関連付けることができます。

シャーディングされたクラスター内のゾーンの詳細については、ゾーンのマニュアルページを参照してください。

空のコレクションまたは存在しないコレクションの初期チャンク分散

空のコレクションまたは存在しないコレクションでゾーンシャーディング sh.updateZoneKeyRange() を実行することを検討している場合は、コレクションをシャーディングする前に、を使用してゾーンとゾーン範囲を作成します（ 以降4.0.2 ）。Starting in version 4.0.3, 空のコレクションまたは存在しないコレクションにゾーンとゾーン範囲を作成することで、MongoDB はコレクションをシャーディングするときに初期チャンクの作成と分散プロセスを最適化できます。この最適化されたプロセスにより、シャーディング後にゾーンを作成するよりもバランサーのオーバーヘッドが少なく、ゾーンシャーディングの迅速なセットアップがサポートされます。バランサーは、最適化された最初のチャンク作成と分散後に、すべてのチャンク管理を実行します。

For an example of defining zones and zone ranges for initial chunk distribution, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

複合ハッシュされたシャードキーを使用した初期チャンク分散

MongoDB は、ハッシュされた複合インデックスでのコレクションのシャーディングをサポートしています。 MongoDB は、空のコレクションまたは存在しないコレクションを複合ハッシュされたシャードキーでシャーディングするときに、最適化された初期チャンクの作成と分散を実行できます。

ハッシュされたフィールドがシャードキーのプレフィックス（つまり、シャードキーの最初のフィールド）である場合、MongoDB が初期チャンクの作成と分散を実行するには、次のすべてが当てはまる必要があります。

コレクションには単一のゾーン範囲があり、すべての下限フィールドにはMinKey 、すべての上限フィールドにはMaxKeyが含まれます。
sh.shardCollection()はpresplitHashedZones: trueオプションを指定します。

ハッシュされたフィールドがシャードキーのプレフィックスではない場合（つまり、シャードキーにハッシュされていない先頭フィールドが 1 つ以上ある場合）、MongoDB が初期チャンクの作成と分散を実行するには、次のすべてが当てはまる必要があります。

コレクションには、個別のプレフィックスフィールド値の組み合わせごとに 1 つのゾーン範囲があります（つまりハッシュされたフィールドに先行するすべてのフィールド）。
各ゾーン範囲の下限について、ハッシュされたフィールドとそれ以降のすべてのフィールドにMinKeyを指定します。
各ゾーン範囲について、少なくとも 1 つの上限プレフィックスフィールドがその下限のカウンターと異なる必要があります。
sh.shardCollection()はpresplitHashedZones: trueオプションを指定します。

For a more complete example of defining zones and zone ranges for initial chunk distribution on a compound hashed shard key, see Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection.

Tip

以下も参照してください。

sh.balancerCollectionStatus()

バランサー

After associating a range to a zone, the バランサー must first run in order to migrate any chunks whose ranges are covered by the zone to shards inside of that zone. Until balancing completes, some chunks may reside on the wrong shard given the configured zones for the sharded cluster. See バランサー for more information.

See the sharded cluster balancer manual page for more information on how migrations work in a sharded cluster.

限界

ゾーン範囲は、常に下限を含み、上限を含まない範囲です。

削除されたコレクション

コレクションを削除すると、それに関連付けられたゾーンやタグの範囲も削除されます。

以前のバージョンでは、MongoDB は削除されたコレクションのタグ関連付けを削除せず、後で同じ名前で新しいコレクションを作成すると、古いタグの関連付けが新しいコレクションに適用されます。

セキュリティ

認証を使用して実行されているシャーディングされたクラスターの場合は、次のいずれかとして認証する必要があります。

configデータベース内のさまざまなコレクションに対して指定されたアクションを含む特権を持つユーザー:
- findconfig.shardsコレクションの
- find と update on the config.tags collection;
または、あるいは、
クラスターリソースで enableSharding を含む権限を持つユーザー。

clusterAdminまたはclusterManagerの組み込みロールには、 sh.updateZoneKeyRange()を発行するための適切な権限があります。詳細については、ロールベースのアクセス制御に関するドキュメントページを参照してください。

例

シャーディングされたコレクションexampledb.collectionとシャードキーが{ a : 1 }の場合、次の操作を実行すると、 alphaゾーンに下限が1で上限が10の範囲が作成されます。

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   "alpha"
)

次の操作では、 nullをzoneフィールドに渡すことで、以前に作成した範囲が削除されます。

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1 },
   { a : 10 },
   null
)

minとmaxは、ターゲット範囲の境界と完全に一致する必要があります。次の操作は、以前に作成した範囲を削除しようとしますが、 minの限界として{ a : 0 }を指定します。

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 0 },
   { a : 10 },
   null
)

While the range of { a : 0 } and { a : 10 } encompasses the existing range, it is not an exact match and therefore updateZoneKeyRange does not remove anything.

複合シャードキー

Given a sharded collection exampledb.collection with a shard key of { a : 1, b : 1 }, the following operation creates a range covering the lower bound of { a: 1, b : 1 } and an upper bound of { a : 10, b : 10} and associates it with the alpha zone:

sh.updateZoneKeyRange(
   "exampledb.collection",
   { a : 1, b : 1 },
   { a : 10, b : 10 },
   "alpha"
)

Pre-Define Zones and Zone Ranges for an Empty or Non-Existing Collection

If you create zones and zone ranges on empty or non-existing collections, MongoDB may 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 バランサー performs all chunk management after the optimized initial chunk creation and distribution. For more information, see 複合ハッシュされたシャードキーを使用した初期チャンク分散 for more information.

The sections below contain examples for three different shard key types.

Consider the following examples, which explore pre-defining zones or zone ranges for three different shard key types:

Single or Compound Shard Keys
Compound Hashed Shard Key with Hashed Prefix
Compound Hashed Shard Key with Non-Prefix Hashed Field

Single or Compound Shard Keys

注意

This example only applies to single-field or compound shard keys 次のない: a hashed field.

たとえば、 { "zip" : 1 } or { "zip" : 1, "account" : 1}

Create the Zones

使用 sh.addShardToZone() to create the zones:

sh.addShardToZone("shardA", "DC1")
sh.addShardToZone("shardB", "DC2")

Create the Zone Ranges

使用 sh.updateZoneKeyRange() to create the ranges for the empty contacts collection in the exampledb database:

sh.updateZoneKeyRange(
    "exampledb.contacts",
    { zip: 10001 },
    { zip: 10090 },
    "DC1"
);
sh.updateZoneKeyRange(
    "exampledb.contacts",
    { zip: 90001 },
    { zip: 96054 },
    "DC2"
);

Shard the Collection

注意

If the collection does not exist, the sharding operation creates the collection.

If the collection is empty and no index exists to support the shard key, the sharding operation creates the index.

使用 sh.shardCollection() to shard the collection contacts:

sh.shardCollection("exampledb.contacts",  { zip: 1 } );

Review the Created Chunks and Distribution

To see the created chunks and distribution, run the sh.status() operation:

sh.status()

このメソッドは以下を返します。

--- Sharding Status ---
  sharding version: {
    "_id" : 1,
    "minCompatibleVersion" : 5,
    "currentVersion" : 6,
    "clusterId" : ObjectId("5b80c06d35a961fd0ae1986d")
  }
  shards:
        {  "_id" : "shardA",  "host" : "shardA/mongodb0.example.net:27018,mongodb1.example.net:27018,mongodb2.example.net:27018",  "state" : 1,  "tags" : [ "DC1" ] }
        {  "_id" : "shardB",  "host" : "shardB/mongodb3.example.net:27018,mongodb4.example.net:27018,mongodb5.example.net:27018",  "state" : 1,  "tags" : [ "DC2" ] }
  active mongoses:
        "4.2.0" : 2
  autosplit:
        Currently enabled: yes
  balancer:
        Currently enabled:  yes
        Currently running:  no
        Failed balancer rounds in last 5 attempts:  0
        Migration Results for the last 24 hours:
                No recent migrations
  databases:
        { "_id" : "config", "primary" : "config" }
        { "_id" : "exampledb", "primary" : "shardA", "version" : { "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"), "lastMod" : 1 } }
                exampledb.contacts
                        shard key: { "zip" : 1 }
                        unique: false
                        balancing: true
                        chunks:
                                shardA   3
                                shardB   2
                        { "zip" : { "$minKey" : 1 } } -->> { "zip" : 10001 } on : shardA Timestamp(1, 0)
                        { "zip" : 10001 } -->> { "zip" : 10090 } on : shardA Timestamp(1, 1)
                        { "zip" : 10090 } -->> { "zip" : 90001 } on : shardB Timestamp(1, 2)
                        { "zip" : 90001 } -->> { "zip" : 96054 } on : shardB Timestamp(1, 3)
                        { "zip" : 96054 } -->> { "zip" : { "$maxKey" : 1 } } on : shardA Timestamp(1, 4)
                          tag: DC1  { "zip" : 10001 } -->> { "zip" : 10090 }
                          tag: DC2  { "zip" : 90001 } -->> { "zip" : 96054 }

For the collection, sharding operation created 5 chunks (two chunks that correspond to the zone ranges and the other three to cover all other values) across shardA and shardB.

Compound Hashed Shard Key with Hashed Prefix

注意

This example only applies to compound hashed shard keys where the hashed field is the prefix of the shard key (i.e. the first field in the shard key is hashed).

たとえば、 { "_id" : "hashed", "facility" : 1 }

MongoDB supports sharding collections on compound hashed indexes. When sharding on a compound hashed shard key, MongoDB can perform optimized initial chunk creation and distribution on the empty or non-existing collection only if the defined zone ranges meet additional requirements.

Consider an empty collection examples.metrics which will store analytics from one of two manufacturing facilities. The planned shard key is { "_id" : "hashed", "facility" : 1}, where the hashed field is the shard key prefix.

Create the Zones

The planned shard key is { "_id" : "hashed", "facility" : 1 }. Since the hashed field is the prefix (i.e. the first field in the shard key), create a single zone using sh.addShardToZone():

sh.addShardToZone("shardA", "FacilityAlpha")
sh.addShardToZone("shardB", "FacilityAlpha")

Create the Zone Ranges

Initial chunk distribution on a compound hashed shard key with a hashed prefix requires a single zone range with MinKey for all lower-bound fields and MaxKey for all upper-bound fields.

使用 sh.updateZoneKeyRange() to create a single range:

sh.updateZoneKeyRange(
   "examples.metrics",
   { "_id" : MinKey, "facility" : MinKey },
   { "_id" : MaxKey, "facility" : MaxKey },
   "FacilityAlpha"
);

Shard the Collection

注意

If the collection does not exist, the sharding operation creates the collection.

If the collection is empty and no index exists to support the shard key, the sharding operation creates the index.

使用 sh.shardCollection() with presplitHashedZones: true to shard the collection and perform initial chunk creation and distribution:

sh.shardCollection(
  "examples.metrics",
  { "_id" : "hashed", "facility" : 1 },
  false,
  { presplitHashedZones: true }
)

Review the Created Chunks and Distribution

To see the created chunks and distribution, run the sh.status() operation:

sh.status()

The output resembles the following (content omitted for readability):

--- Sharding Status ---
databases:
  { "_id" : "config", "primary" : "config" }
  { "_id" : "examples", "primary" : "shardA", "version" : { "uuid" : UUID("245f8abf-a363-48b0-8208-2a5b577bbb4e"), "lastMod" : 1 } }
    examples.metrics
      shard key: { "_id" : "hashed", "facility" : 1 }
      unique: false
      balancing: true
      chunks:
        shardA  2
        shardB  2
      { "_id" : { "$minKey" : 1 }, "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong("-4611686018427387902"), "facility" : { "$minKey" : 1 } } on : shardA Timestamp(1, 0)
      { "_id" : NumberLong("-4611686018427387902"), "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong(0), "facility" : { "$minKey" : 1 } } on : shardA Timestamp(1, 1)
      { "_id" : NumberLong(0), "facility" : { "$minKey" : 1 } } -->> { "_id" : NumberLong("4611686018427387902"), "facility" : { "$minKey" : 1 } } on : shardB Timestamp(1, 2)
      { "_id" : NumberLong("4611686018427387902"), "facility" : { "$minKey" : 1 } } -->> { "_id" : { "$maxKey" : 1 }, "facility" : { "$maxKey" : 1 } } on : shardB Timestamp(1, 3)
        tag: FacilityAlpha  { "_id" : { "$minKey" : 1 }, "facility" : { "$minKey" : 1 } } -->> { "_id" : { "$maxKey" : 1 }, "facility" : { "$maxKey" : 1 } }

The sharding operation produced 4 chunks in total. Two chunks correspond to the absolute lower and upper bounds. One zone was created on shardA and shardB corresponding to FacilityAlpha. The zone was subdivided into 2 chunks using the hashed field.

Compound Hashed Shard Key with Non-Prefix Hashed Field

注意

This example only applies to compound hashed shard keys where the hashed field is ではない the prefix of the shard key (i.e. the first field in the shard key is not hashed).

たとえば、 { "facility" : 1, "_id" : "hashed" }

Consider an empty collection examples.metrics which will store analytics from one of two manufacturing facilities. The planned shard key is { "facility" : 1, "_id" : "hashed" }, where the hashed field is ではない the shard key prefix.

The facility field stores the name of the facility: "FacilityAlpha" or "FacilityBaker". The collection requires zone ranges on facility to help isolate data for each facility to specific shards.
The _id field compensates for the low-cardinality of the facility field. Hashing compensates for the monotonically-increasing nature of the _id field.

Create the Zones

Use the sh.addShardToZone() command to create the zones.

sh.addShardToZone("shardA", "FacilityAlpha")
sh.addShardToZone("shardB", "FacilityBaker")

Create the Zone Ranges

The planned shard key is {"facility" : 1, "_id" : "hashed"}. The facility field has two possible values: FacilityAlpha and FacilityBaker.

Initial chunk distribution on a compound hashed shard key where the hashed field is ではない the prefix requires one zone range for each combination of distinct prefix field values (i.e. all fields preceding the hashed field). Since facility has two distinct prefix values, the collection requires exactly two zone ranges that cover those values.

The lower bound range specifies MinKey for all non-prefix fields.
The upper-bound range has at least one prefix field that differs from its lower-bound counterpart.

使用 sh.updateZoneKeyRange() to create the range for "facility": "FacilityAlpha":

sh.updateZoneKeyRange(
   "examples.metrics",
   { "facility": "FacilityAlpha", "_id" : MinKey },
   { "facility": "FacilityBaker", "_id" : MinKey },
   "FacilityAlpha"
);

Since zone range upper bounds are exclusive, this range only covers documents with the distinct shard key prefix value "facilty" : "FacilityAlpha" and all possible values of _id.

使用 sh.updateZoneKeyRange() to create the range for "facility": "FacilityBaker":

sh.updateZoneKeyRange(
   "examples.metrics",
   { "facility": "FacilityBaker", "_id" : MinKey },
   { "facility": MaxKey, "_id" : MinKey },
   "FacilityBaker"
);

While the upper bound of this range can technically capture other values of facility, the initial chunk distribution logic relies on the assumption that no other distinct values for facility exist. Since the collection only contains documents where facility is FacilityAlpha or FacilityBaker, this range only covers documents with the distinct shard key prefix value "facility" : "FacilityBaker" and all possible values of _id.

Shard the Collection

注意

If the collection does not exist, the sharding operation creates the collection.

If the collection is empty and no index exists to support the shard key, the sharding operation creates the index.

使用 sh.shardCollection() with presplitHashedZones: true to shard the collection and perform initial chunk creation and distribution:

sh.shardCollection(
  "examples.metrics",
  { "facility" : 1, "_id" : "hashed"},
  false,
  { presplitHashedZones: true }
)

Review the Created Chunks and Distribution

To see the created chunks and distribution, run the sh.status() operation:

sh.status()

The output resembles the following (content omitted for readability):

--- Sharding Status ---
  databases:
    { "_id" : "config", "primary" : "config" }
    { "_id" : "examples", "primary" : "shardA", "version" : { "uuid" : UUID("6c351bcf-acd2-4fd9-82d8-9f6bd7321558"), "lastMod" : 1 } }
      examples.metrics
        shard key: { "facility" : 1, "_id" : "hashed" }
        unique: false
        balancing: true
        chunks:
          shardA  3
          shardB  3
        { "facility" : { "$minKey" : 1 }, "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } on : shard1 Timestamp(1, 0)
        { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityAlpha", "_id" : NumberLong(0) } on : shard1 Timestamp(1, 1)
        { "facility" : "FacilityAlpha", "_id" : NumberLong(0) } -->> { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } on : shard1 Timestamp(1, 2)
        { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityBaker", "_id" : NumberLong(0) } on : shard2 Timestamp(1, 3)
        { "facility" : "FacilityBaker", "_id" : NumberLong(0) } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } } on : shard2 Timestamp(1, 4)
        { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$maxKey" : 1 } } on : shard2 Timestamp(1, 5)
          tag: FacilityAlpha  { "facility" : "FacilityAlpha", "_id" : { "$minKey" : 1 } } -->> { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } }
          tag: FacilityBaker  { "facility" : "FacilityBaker", "_id" : { "$minKey" : 1 } } -->> { "facility" : { "$maxKey" : 1 }, "_id" : { "$minKey" : 1 } }

The sharding operation produced 6 chunks in total. Two chunks correspond to the absolute lower and upper bounds. Two zones were created, one on shardA and one on shardB, corresponding to FacilityAlpha and FacilityBaker. Each of these zones has been further subdivided into 2 chunks using the hashed field.

Tip

以下も参照してください。

戻る

sh.unshardCollection

sh.waitForBalancer