shardCollection (comando de banco de dados)

Definição

shardCollection: Shards a collection to distribute its documents across shards. The shardCollection command must be run against the admin database.
Dica
In mongosh, this command can also be run through the sh.shardCollection() helper method.
Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Compatibilidade

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

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

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

Sintaxe

To run shardCollection, use the db.runCommand( { <command> } ) method.

O comando tem o seguinte formato:

db.adminCommand(
   {
     shardCollection: "<database>.<collection>",
     key: { <field1>: <1|"hashed">, ... },
     unique: <boolean>,
     presplitHashedZones: <boolean>,
     collation: { locale: "simple" },
     timeseries: <object>
   }
 )

Observação

Alterado na versão 6.0.

A partir do MongoDB 6.0, o compartilhamento de uma collection não exige que você execute primeiro o comando enableSharding para configurar o banco de dados.

Campos de comando

O comando utiliza os seguintes campos:

Campo	Tipo	Descrição
`shardCollection`	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 os valores do campo como: `1` para fragmentação baseada em faixa `"hashed"` para especificar uma hashed shard key. shard key must be supported by an index. Unless the collection is empty, the index must exist prior to the `shardCollection` command. If the collection is empty, MongoDB creates the index prior to sharding the collection if the index that can support the shard key does not already exist. Consulte também Índices de chaves de shard
`unique`	booleano	Especifique `true` para garantir que o índice subjacente imponha uma restrição exclusiva. O padrão é `false`. Você não pode especificar `true` ao usar hashed shard keys.
`collation`	documento	Opcional. Se a collection especificada para `shardCollection` tiver um agrupamento padrão, você precisa incluir um documento de agrupamento com `{ locale : "simple" }`, senão o comando `shardCollection` falha. Pelo menos um dos índices cujos campos suportam o padrão de chave de shard deve ter o agrupamento simples.
presplitHashedZones	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: A chave de shard não contém um campo hashed (ou seja, não é um índice hashed de campo único ou um índice hashed composto). A collection não tem zonas ou faixas de zonas definidas. The defined zone range or ranges do not meet the requirements.
Time series	objeto	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. Novidades na versão 5.1.

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

The timeseries option takes the following fields:

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`. AVISO: a partir do MongoDB 8.0, o uso do `timeField` como uma chave de fragmento em uma coleção de séries temporais é preterido.
`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`.

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.

Dica

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:

metaField pode ser um:
- Chave de fragmento com hash
- Chave fragmentada de longo alcance
timeField deve ser:
- Uma chave fragmentada de longo alcance
- No final do padrão de 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:

Aviso

A partir do MongoDB 8.0, as chaves de fragmento que contêm timeField ficaram obsoletas para coleções de séries temporais.

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

Refragmente para balancear

When you run the shardCollection command, 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.

Starting in MongoDB 8.0, se sua implantação atender aos requisitos de recursos, é recomendável usar o comando reshardCollection para executar esse balanceamento inicial de dados refragmentando para a mesma chave. Isso faz com que o MongoDB reequilibrar os dados entre os fragmentos sem esperar no balanceador.

Para utilizar o comando reshardCollection para executar o balanceamento inicial:

Use the shardCollection command to configure the collection as a sharded collection.
Use o reshardCollection para refragmentar na mesma chave de fragmento configurando a opção forceRedistribution para true. O MongoDB então equilibra os dados entre os fragmentos.

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

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.

Para fragmentar uma collection usando um índice hashed composto, consulte Fragmentação por zona e índices hashed compostos.

Fragmentação por zona e índices hashed compostos

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

Exclusividade

Se especificar unique: true:

If the collection is empty, 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 shardCollection.
If the collection has an index that supports the shard key but that index is not unique, 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, 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 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.

Exemplo

A seguinte operação habilita a fragmentação para a collection people no banco de dados de records e utiliza o campo zipcode como a chave de shard:

db.adminCommand( { shardCollection: "records.people", key: { zipcode: 1 } } )

Saiba mais

Voltar

setAllowMigrations

shardDrainingStatus