Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.
Menu Docs
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh
Página inicial do Docs
/
Desenvolvimento
/
Métodos de mongosh

sh.shardCollection() (método mongosh)

Definição

sh.shardCollection(namespace, key, unique, options)

Fragmenta uma coleta usando key como chave de fragmento. A chave de fragmento determina como o MongoDB distribui os documentos da coleta entre os fragmentos.

Observação

Alterado na versão 6.0.

A partir do MongoDB 6.0, a fragmentação de uma coleta não exige que você execute primeiro o método sh.enableSharding() para configurar o banco de dados.

Importante

Método mongosh

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

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

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

sh.shardCollection() recebe os seguintes argumentos:

Parâmetro
Tipo
Descrição

namespace

string

O namespace da collection para fragmentar no formato "<database>.<collection>".

key

documento

O documento que especifica o campo ou campos a serem usados como a chave de shard.

{ <field1>: <1|"hashed">, ... }

Defina o valor do campo como:

a chave de fragmento deve ser suportada por um índice. A menos que a coleta esteja vazia, o índice deve existir antes do comando shardCollection. Se a coleta estiver vazia, o MongoDB criará o índice antes de fragmentar a coleta se o índice que pode suportar a chave de fragmentação ainda não existir.

Consulte também Índices de chaves de shard

unique

booleano

Opcional. Especifique true para garantir que o índice subjacente imponha uma restrição única. O padrão é false.

Você não pode especificar true ao usar hashed shard keys.

For Legacy mongo Shell, you must explicitly specify the value for unique if you specify the options document. mongosh doesn't require unique when you specify the options document.

options

documento

Opcional. Um documento contendo campos opcionais, incluindo collation.

O argumento options suporta as seguintes opções:

Parâmetro
Tipo
Descrição

collation

documento

Opcional. Se a coleta especificada para shardCollection tiver um agrupamento padrão, você deverá incluir um documento de agrupamento com``{ locale : "simple" }``, ou o comando shardCollection falhará. Pelo menos um dos índices cujos campos suportam o padrão de chave de fragmento deve ter o agrupamento simples.

booleano

Opcional. Especifique true para executar a criação e distribuição inicial de chunks para uma collection vazia ou inexistente com base nas zonas e faixas de zonas definidas para a collection. Apenas para fragmentação hashed .

shardCollection() com presplitHashedZones: true retorna um erro se alguma das seguintes afirmações for verdadeira:

documento

Opcional. Especifique esta opção para criar uma collection de séries temporais fragmentada.

Para fragmentar uma collection de séries temporais existente, omita este parâmetro.

Quando a collection especificada para shardCollection é uma collection de séries temporais e a opção timeseries não é especificada, o MongoDB usa os valores que definem a collection de séries temporais existente para preencher o campo timeseries.

For detailed syntax, see Time Series Options.

Opções de séries temporais

Novidades na versão 5.1.

To create a new time series collection that is sharded, specify the timeseries option to sh.shardCollection().

A opção de série temporal utiliza os seguintes campos:

Campo
Tipo
Descrição

timeField

string

Obrigatório. O nome do campo que contém a data em cada documento da série temporal. Os documentos em uma collection de séries temporais devem ter uma data BSON válida como o valor do timeField.

metaField

string

Opcional. O nome do campo que contém metadados em cada documento de série temporal. Os metadados no campo especificado devem ser dados utilizados para rotular uma série exclusiva de documentos. Os metadados raramente devem mudar. O nome do campo especificado não pode ser _id ou o mesmo que o timeseries.timeField. O campo pode ser de qualquer tipo de dados.

Embora o campo metaField seja opcional, o uso de metadados pode melhorar a otimização da query. Por exemplo, o MongoDB cria automaticamente um índice composto nos campos metaField e timeField para novas collections. Se você não fornecer um valor para este campo, os dados serão agrupados exclusivamente com base no tempo.

granularity

string

Opcional. Os valores possíveis são:

  • "seconds"

  • "minutes"

  • "hours"

Por padrão, o MongoDB define granularity como "seconds" para ingestão de alta frequência.

Defina manualmente o parâmetro granularity para melhorar o desempenho, otimizando a forma como os dados da collection de séries temporais são armazenados internamente. Para selecionar um valor para granularity, escolha a correspondência mais próxima do período entre as medições de entrada consecutivas.

Se você especificar timeseries.metaField, considere o período entre as medições de entrada consecutivas que têm o mesmo valor único para o campo metaField. As medições muitas vezes têm o mesmo valor exclusivo para o campo metaField se forem da mesma origem.

Se você não especificar timeseries.metaField, considere o período entre todas as medições inseridas na collection.

Se configurar o parâmetro granularity, você não poderá configurar os parâmetros bucketMaxSpanSeconds e bucketRoundingSeconds.

Compatibilidade

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

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

Importante

This command is not supported in M0 and Flex clusters. For more information, see Unsupported Commands.

  • 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

Considerações

Chaves de fragmentação

Embora você possa alterar sua chave de shard posteriormente, é importante considerar cuidadosamente sua escolha de chave de shard para evitar problemas de escalabilidade e desempenho.

Chaves de shard em collections de séries temporais

Ao fragmentar coleções de série temporal, você só pode especificar os seguintes campos na chave de fragmento:

  • O metaField

  • Subcampos de metaField

  • O timeField

Você pode especificar combinações desses campos na chave do fragmento. Nenhum outro campo, incluindo _id, é permitido no padrão da chave de fragmento.

Quando você especifica a chave de fragmento:

Dica

Evite especificar apenas o timeField como a chave de fragmento. Como o timeField aumenta monotonicamente, isso pode fazer com que todas as gravações apareçam em um único bloco dentro do cluster. Idealmente, os dados são distribuídos uniformemente entre os blocos.

Para saber como escolher melhor uma chave de fragmento, consulte:

Dica

Hashed shard keys

As hashed shard keys com índice hashed usam um índice hashed composto como a chave de shard.

Use o formato field: "hashed" para especificar um campo de hashed shard key.

Observação

Se as migrações de chunks estiverem em andamento durante a criação de uma collection de hashed shard keys, a distribuição inicial de chunks poderá ser desigual até que o balanceador equilibre automaticamente a collection.

Dica

Fragmentação em hash

Fragmentação de zonas e distribuição inicial de chunks

The shard collection operation (i.e. shardCollection command and the sh.shardCollection() helper) can perform initial chunk creation and distribution for an empty or a non-existing collection if zones and zone ranges have been defined for the collection. Initial chunk distribution allows for a faster setup of zoned sharding. After the initial distribution, the balancer manages the chunk distribution going forward per usual.

To shard a collection using a compound hashed index, see Initial Chunk Distribution with Compound Hashed Indexes.

Distribuição inicial de chunks com índices compostos com hash

MongoDB oferece suporte à fragmentação de coleção em índices compostos com hash. Ao fragmentar uma coleção vazia ou inexistente usando uma chave de fragmento composta com hash, aplicam-se requisitos adicionais para que o MongoDB execute a criação e a distribuição inicial da parte.

Consulte Predefinir zonas e faixas de zona para uma collection vazia ou não existente para ver um exemplo.

Dica

Blocos Iniciais

Exclusividade

Se especificar unique: true:

  • If the collection is empty, sh.shardCollection() creates the unique index on the shard key if such an index does not already exist.

  • If the collection is not empty, you must create the index first before using sh.shardCollection().

  • If the collection has an index that supports the shard key but that index is not unique, sh.shardCollection() returns an error.

Embora possa existir um índice composto exclusivo onde a chave de fragmentação é um prefixo, se você utilizar o parâmetro unique, a collection deverá ter um índice exclusivo que esteja na chave de fragmentação.

If you omit unique or specify unique: false, sh.shardCollection() doesn't change the collection's existing indexes. If a unique index on the shard key already exists, that index remains unique and the sharded cluster continues to enforce the uniqueness constraint on the shard key values across shards.

Consulte também Collection fragmentada e índices hashed.

Agrupamentos

If the collection has a default collation, the sh.shardCollection() command must include a collation parameter with the value { locale: "simple" }. For non-empty collections with a default collation, you must have at least one index with the simple collation whose fields support the shard key pattern.

Você não precisa especificar a opção collation para collections sem agrupamento. Se você especificar a opção de agrupamento para uma coleção sem agrupamento, ela não terá efeito.

Escreva preocupação

mongos uses "majority" for the write concern of the shardCollection command, its helper sh.shardCollection(), and the sh.shardAndDistributeCollection() method.

Refragmente para balancear

When you run the sh.shardCollection() method, the balancer begins distributing the collection data to other shards in the cluster. A single shard can only participate in one chunk migration at a time. When MongoDB succeeds in copying a range of data from one shard to another, the range on the donor shard is marked for removal by the range deleter. This process is slow and resource intensive.

A partir do MongoDB 8.0, se a sua implantação atender aos requisitos de recursos, é recomendado que você utilize o método sh.shardAndDistributeCollection() para fazer o fragmento da coleção. Este método envolve os comandos shardCollection e reshardCollection para criar fragmentos na coleção e recriá-los imediatamente na mesma chave. Isso faz com que o MongoDB reequilibrar os dados entre os fragmentos sem esperar no balanceador.

Para obter mais informações, consulte Refragmentar com a mesma chave de fragmento.

Exemplos

Uso simples

Com uma coleção denominada people em um banco de dados denominada records, o seguinte comando fragmenta a coleção pelo campo zipcode:

sh.shardCollection("records.people", { zipcode: 1 } )

Uso com opções

The phonebook database has a collection contacts with no default collation. The following example uses sh.shardCollection() to shard the phonebook.contacts with:

sh.shardCollection(
  "phonebook.contacts",
  { last_name: "hashed" },
  false,
  {
    collation: { locale: "simple" }
  }
)

Dica

Voltar
sh.shardAndDistributeCollection
Próximo
sh.shardDrainingStatus
Avalie esta página

Nesta página