sh.updateZoneKeyRange()

Nesta página

Definição

Compatibilidade
Comportamento
Exemplos

Definição

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

Associa uma faixa de valores da chave de shard a umazona .

Você pode executar o comando de banco de dados 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 nem drivers específicos de linguagem, 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 do MongoDB específica da linguagem.

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

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

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

Importante

Este comando não é suportado em clusters M0, M2 e M5 . 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 com 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 as faixas 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 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.

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 a collections de fragmentação em índices com hash compostos. O MongoDB pode executar a criação e a distribuição otimizadas do chunk inicial ao fragmentar a collection vazia ou inexistente em uma chave shard com hash composto.

Se o campo com hash for o prefixo da chave de fragmento (ou seja, o primeiro campo na chave de fragmento), todos os itens a seguir deverão ser verdadeiros para que o MongoDB execute a criação e a distribuição inicial do chunk:

A collection tem um único intervalo de zona com MinKey para todos os campos de limite inferior e MaxKey para todos os campos de limite superior.
sh.shardCollection() especifica a opção presplitHashedZones: true .

Se o campo hashed não for o prefixo da chave de shard (ou seja, a chave de shard tem um ou mais campos principais não hasheados), todos os itens a seguir deverão ser verdadeiros para que o MongoDB execute a criação e a distribuição inicial do chunk:

A coleção tem uma faixa de zona para cada combinação de valores de campo de prefixo distintos (ou seja, todos os campos que precedem o campo hashed).
Para o limite inferior de cada faixa de zona , especifique MinKey para o campo hashed e todos os campos subsequentes.
Para cada faixa de zona, pelo menos um campo de prefixo de limite superior deve diferir de sua contraparte de limite inferior.
sh.shardCollection() especifica a opção presplitHashedZones: true .

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 do cluster .

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

Se você criar zonas e faixas de zonas em collections vazias ou inexistentes, o MongoDB poderá otimizar 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 mais informações, consulte Distribuição inicial de chunks com chaves de shard com hash compostas 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 blocos em uma chave de fragmento hashed composta onde o campo hashed não é o prefixo requer um intervalo de zona para cada combinação de valores de campo de prefixo distintos (ou seja, todos os campos que precedem o campo hashed). 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:

Voltar

sh.unshardCollection

sh.waitForBalancer