Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB

sh.updateZoneKeyRange()

Nesta página

Definição

Compatibilidade
Comportamento
Exemplos

Definição

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

Associa uma faixa de valores de chave de shard a uma zona.

A partir do MongoDB 4.0.2, você pode executar o comando de banco de dados do updateZoneKeyRange e seus auxiliares sh.updateZoneKeyRange() e sh.addTagRange() em uma coleção não compartilhada ou uma coleção não existente.

Importante

Método mongosh

Esta página documenta um método mongosh . Esta não é a documentação para comandos de banco de dados ou drivers específicos de idioma, como Node.js.

Para o comando do banco de dados, consulte o comando updateZoneKeyRange.

Para drivers de API do MongoDB, consulte a documentação do driver MongoDB específica do idioma.

Para a documentação de shell legada do mongo, consulte a documentação para a versão correspondente do MongoDB Server:

mongo shell v4.4

sh.updateZoneKeyRange() recebe os seguintes argumentos:

Parâmetro	Tipo	Descrição
`namespace`	string	O namespace da collection fragmentada associado ao `zone`. A coleção deve ser fragmentada para que a operação seja bem-sucedida.
`minimum`	documento	O limite inferior inclusivo do intervalo de valores de chave de fragmento . Especifique cada campo da chave de fragmento na forma de `<fieldname> : <value>`. O valor deve ser do mesmo tipo ou tipos de BSON que a chave de shard. Observação Para usar a fragmentação hashed, o valor do campo precisa ser do tipo `NumberLong`.
`maximum`	documento	O limite superior exclusivo do intervalo de valores da chave de fragmento . Especifique cada campo da chave de fragmento na forma de `<fieldname> : <value>`. O valor deve ser do mesmo tipo ou tipos de BSON que a chave de shard. Observação Para usar a fragmentação hashed, o valor do campo precisa ser do tipo `NumberLong`.
`zone`	string	O nome da zona a ser associada ao intervalo de valores da chave de shard limitados por `minimum` e `maximum`.

Emita sh.updateZoneKeyRange() somente quando conectado a uma instância mongos .

Compatibilidade

Este método está disponível em sistemas hospedados nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

Observação

Este comando não é suportado em instâncias sem servidor. Para obter mais informações, consulte Comandos não suportados.

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão código-disponível, de uso gratuito e autogerenciada do MongoDB

Comportamento

Você não pode criar uma faixa de valores de chave de shard cujos limites inferior e superior se sobreponham a uma faixa existente para a collection fragmentada. Por exemplo, dado um intervalo existente de 1 a 10, você não pode criar um novo intervalo de 5 a 20, pois o novo intervalo se sobreporia ao intervalo existente.

Uma zona pode ter vários intervalos de dados associados a ela, mas um intervalo pode, no máximo, ser associado a uma única zona.

Consulte a página do manual de zonas para obter mais informações sobre zonas em clusters fragmentados.

Distribuição inicial de chunks para collections vazias ou inexistentes

Se você estiver considerando realizar a fragmentação de zonas em uma collection vazia ou inexistente, use sh.updateZoneKeyRange() para criar as zonas e os intervalos de zonas antes de fragmentar a collection (desde 4,0,2). A partir da versão 4.0.3, a criação de zonas e intervalos de zonas em collections vazias ou inexistentes permite que o MongoDB otimize o processo inicial de criação e distribuição de chunks ao fragmentar a collection. Esse processo otimizado permite uma configuração mais rápida da fragmentação por zonas com menos sobrecarga do balanceador do que a criação de zonas após a fragmentação. O balanceador executa todo o gerenciamento de blocos após a criação e distribuição otimizadas do bloco inicial.

Para obter um exemplo de definição de zonas e faixas de zonas para a distribuição inicial de chunks, consulte Pre-definir zonas e faixas de zonas para uma collection vazia ou não existente.

Distribuição inicial de chunks com chaves de shard com hash compostas

O MongoDB oferece suporte para as collection de fragmentação em índices compostos com hash. O MongoDB pode executar criação e distribuição inicial otimizada de parte ao fragmentar a collection vazia ou inexistente em uma chave de fragmento com hash.

Para obter um exemplo mais completo de definição de zonas e faixas de zonas para a distribuição inicial de chunks em uma chave de shard com hash composto, consulte Predefinir zonas e faixas de zonas para uma collection vazia ou não existente.

Dica

Veja também:

sh.balancerCollectionStatus()

Balancer

Depois de associar uma faixa a uma zona, o balancer deve primeiro executar para migrar quaisquer chunks cujas faixas sejam cobertas pela zona para shards dentro dessa zona. Até a conclusão do balanceamento, alguns chunks podem residir no shard errado, dadas as zonas configuradas para o cluster fragmentado. Consulte Balanceador para obter mais informações.

Consulte a página do manual do balanceador de cluster fragmentado para obter mais informações sobre como as migrações funcionam em um cluster fragmentado.

Limites

As faixas de zona estão sempre inclusas no limite inferior e exclusivas do limite superior.

Coleções descartadas

A eliminação de uma coleção exclui seus intervalos de zonas/tags associados.

Nas versões anteriores, o MongoDB não remove as associações de tags para uma collection descartada e, se posteriormente você criar uma nova collection com o mesmo nome, as associações de tags antigas serão aplicadas à nova collection.

Segurança

Para clusters fragmentados em execução com autenticação, você deve autenticar como:

um usuário cujos privilégios incluem as ações especificadas em várias coleções no banco de dados config :
- find na collection config.shards
- find e update na collection config.tags ;
ou, alternativamente,
um usuário cujos privilégios incluem enableSharding no recurso de cluster (disponível a partir da versão 4.2.2, 4.0.14, 3.6.16).

As roles embutidas clusterAdmin ou clusterManager sh.updateZoneKeyRange() as permissões apropriadas para emitir . Consulte a página de documentação do Controle de acesso baseado em funções para obter mais informações.

Exemplos

Dada uma collection fragmentada exampledb.collection com uma chave de shard de { a : 1 }, a operação a seguir cria uma faixa com um limite inferior de 1 e um limite superior de 10 na zona alpha :

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

A seguinte operação remove o intervalo criado anteriormente passando null para o campo zone .

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

Os min e max devem corresponder exatamente aos limites do intervalo alvo. A operação a seguir tenta remover o intervalo criado anteriormente, mas especifica { a : 0 } como o limite min :

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

Embora a faixa de { a : 0 } e { a : 10 } abranja a faixa existente, não é uma correspondência exata e, portanto, updateZoneKeyRange não remove nada.

Chave de shard composta

Dada uma collection fragmentada exampledb.collection com uma chave de shard de { a : 1, b : 1 }, a operação a seguir cria uma faixa que cobre o limite inferior de { a: 1, b : 1 } e um limite superior de { a : 10, b : 10} , e a associa à zona alpha :

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

Predefinir zonas e faixas de zona para uma collection vazia ou inexistente

A partir da versão 4.2, a criação de zonas e faixas de zonas em collections vazias ou inexistentes permite que o MongoDB otimize o processo inicial de criação e distribuição de chunks ao fragmentar a collection. Esse processo otimizado permite uma configuração mais rápida da fragmentação por zonas com menos sobrecarga do balanceador do que a criação de zonas após a fragmentação. O balanceador executa todo o gerenciamento de blocos após a criação e distribuição otimizadas do bloco inicial. Consulte Distribuição inicial de chunks com chaves de shard com hash composto para obter mais informações.

As seções abaixo contêm exemplos para três tipos diferentes de chave de shard.

Considere os exemplos a seguir, que exploram a predefinição de zonas ou faixas de zonas para três tipos diferentes de chave de shard:

Chaves de shard únicas ou compostas
Chave de shard hashed composta com prefixo hashed
Chave de shard hashed composta com campo hashed sem prefixo

Chaves de shard únicas ou compostas

Observação

Este exemplo se aplica apenas a chaves de shard de campo único ou compostas sem um campo com hash.

Por exemplo, { "zip" : 1 } ou { "zip" : 1, "account" : 1}

Criar as zonas

Use sh.addShardToZone() para criar as zonas:

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

Criar os intervalos de zona

Utilize sh.updateZoneKeyRange() para criar os intervalos para a coleção contacts vazia no banco de dados exampledb :

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

Fragmentar a collection

Observação

Se a collection não existir, a operação de fragmentação criará a collection.

Se a collection estiver vazia e não existir nenhum índice compatível com a chave de shard, a operação de fragmentação criará o índice.

Use sh.shardCollection() para fragmentar a coleção contacts:

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

Revise os chunks criados e a distribuição

Para visualizar os blocos criados e distribuição, execute a operação sh.status() :

sh.status()

O método retorna:

--- 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 }

Para a collection, a operação de fragmentação criou 5 chunks (dois chunks que correspondem às faixas de zonas e os outros três para cobrir todos os outros valores) em shardA e shardB.

Chave de shard hashed composta com prefixo hashed

Observação

Esse exemplo se aplica apenas a chaves de shard com hash compostas em que o campo com hash é o prefixo da chave de shard (ou seja, o primeiro campo da chave de shard é com hash).

Por exemplo, { "_id" : "hashed", "facility" : 1 }

O MongoDB oferece suporte a collections de fragmentação em índices com hash compostos. Ao fragmentar uma chave de shard com hash composto, o MongoDB pode executar a criação e a distribuição inicial otimizadas de chunks na collection vazia ou inexistente somente se as faixas de zonas definidas atenderem a requisitos adicionais.

Considere uma coleção vazia examples.metrics que armazenará análises de uma das duas instalações de produção. A chave de shard planejada é { "_id" : "hashed", "facility" : 1}, onde o campo hashed é o prefixo da chave de shard .

Criar as zonas

A chave de shard planejada é { "_id" : "hashed", "facility" : 1 }. Como o campo hashed é o prefixo (ou seja, o primeiro campo na chave de shard), crie uma única zona usando sh.addShardToZone():

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

Criar os intervalos de zona

A distribuição inicial de chunks em uma chave de shard composta com hash requer um único intervalo de zona com MinKey para todos os campos de limite inferior e MaxKey para todos os campos de limite superior.

Use sh.updateZoneKeyRange() para criar um único intervalo:

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

Fragmentar a collection

Observação

Se a collection não existir, a operação de fragmentação criará a collection.

Se a collection estiver vazia e não existir nenhum índice compatível com a chave de shard, a operação de fragmentação criará o índice.

Use sh.shardCollection() com presplitHashedZones: true para fragmentar a collection e executar a criação e a distribuição inicial do chunk:

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

Revise os chunks criados e a distribuição

Para visualizar os blocos criados e distribuição, execute a operação sh.status() :

sh.status()

A saída se assemelha ao seguinte (conteúdo omitido para legibilidade):

--- 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 } }

A operação de fragmentação gerou 4 chunks no total. Dois chunks correspondem aos limites inferior e superior absolutos. Uma zona foi criada em shardA e shardB corresponde a FacilityAlpha. A zona foi subdividida em 2 blocos usando o campo hashed.

Chave de shard hashed composta com campo hashed sem prefixo

Observação

Esse exemplo se aplica apenas a chaves de shard com hash compostas em que o campo com hash não é o prefixo da chave de shard (ou seja, o primeiro campo da chave de shard não é com hash).

Por exemplo, { "facility" : 1, "_id" : "hashed" }

Considere uma coleção vazia examples.metrics que armazenará análises de uma das duas instalações de produção. A chave de shard planejada é { "facility" : 1, "_id" : "hashed" }, onde o campo hashed não é o prefixo da chave de shard.

O campo facility armazena o nome da instalação: "FacilityAlpha" ou "FacilityBaker". A collection requer zona ranges no facility para ajudar a isolar os dados de cada instalação em fragmentos específicos.
O campo _id compensa a baixa cardinalidade do campo facility . O hash compensa a natureza monotonicamente crescente do campo _id .

Criar as zonas

Utilize o comando sh.addShardToZone() para criar as zonas.

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

Criar os intervalos de zona

A chave de shard planejada é {"facility" : 1, "_id" : "hashed"}. O campo facility tem dois valores possíveis: FacilityAlpha e FacilityBaker.

A distribuição inicial de chunks em uma chave de shard composta com hash onde o campo com hash não é o prefixo requer uma faixa de zona para cada combinação de valores de campo de prefixo distintos (ou seja, todos os campos que precedem o campo com hash). Como facility tem dois valores de prefixo distintos, a collection exige exatamente dois intervalos de zona que cubram esses valores.

O intervalo do limite inferior especifica MinKey para todos os campos sem prefixo.
O intervalo do limite superior tem pelo menos um campo de prefixo que difere do seu equivalente do limite inferior.

Utilize sh.updateZoneKeyRange() para criar o intervalo para "facility": "FacilityAlpha":

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

Como os limites superiores da faixa de zonas são exclusivos, esse intervalo cobre apenas documentos com o valor de prefixo da chave de shard distinta "facilty" : "FacilityAlpha" e todos os valores possíveis de _id.

Utilize sh.updateZoneKeyRange() para criar o intervalo para "facility": "FacilityBaker":

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

Embora o limite superior desse intervalo possa técnicamente capturar outros valores de facility, a lógica inicial de distribuição de chunks depende do pressuposto de que não existe nenhum outro valor distinto de facility . Como a collection contém apenas documentos em que facility é FacilityAlpha ou FacilityBaker, esse intervalo abrange apenas documentos com o valor de prefixo de chave de shard distinto "facility" : "FacilityBaker" e todos os valores possíveis de _id.

Fragmentar a collection

Observação

Se a collection não existir, a operação de fragmentação criará a collection.

Se a collection estiver vazia e não existir nenhum índice compatível com a chave de shard, a operação de fragmentação criará o índice.

Use sh.shardCollection() com presplitHashedZones: true para fragmentar a collection e executar a criação e a distribuição inicial do chunk:

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

Revise os chunks criados e a distribuição

Para visualizar os blocos criados e distribuição, execute a operação sh.status() :

sh.status()

A saída se assemelha ao seguinte (conteúdo omitido para legibilidade):

--- 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 } }

A operação de fragmentação gerou 6 chunks no total. Dois chunks correspondem aos limites inferior e superior absolutos. Duas zonas foram criadas, uma em shardA e outra em shardB, correspondentes a FacilityAlpha e FacilityBaker. Cada uma dessas zonas foi subdividida em 2 blocos usando o campo hashed.

Dica

Veja também:

← sh.waitForPingChange()

Construtores e métodos de objetos →