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>,
     numInitialChunks: <integer>,
     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 distância `"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.
`numInitialChunks`	inteiro	Especifica o número inicial de chunks para criar em todos os shards no cluster ao compartilhar uma collection vazia com uma hashed shard key. Em seguida, o MongoDB cria e equilibra os chunks no cluster. `numInitialChunks` deve resultar em menos de `8192` por shard. Se a collection não estiver vazia ou a chave de shard não contiver um campo hashed, a operação retornará um erro. If sharding with presplitHashedZones: true, MongoDB attempts to evenly distribute the specified number of chunks across the zones in the cluster. If sharding with presplitHashedZones: false or omitted and no zones and zone ranges are defined for the empty collection, MongoDB attempts to evenly distributed the specified number of chunks across the shards in the cluster. If sharding with presplitHashedZones: false or omitted and zones and zone ranges have been defined for the empty collection, `numInitChunks` has no effect.
`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`.
`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:

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.

Consulte Predefinir zonas e faixas de zona para uma collection vazia ou não existente para ver um exemplo.Se estiver fragmentando uma collection usando uma hashed shard key de faixa ou campo único, a opção numInitialChunks não terá efeito se zonas e faixas de zonas tiverem sido definidas para a collection vazia.

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.

The numInitialChunks option has no effect if zones and zone ranges have been defined for the empty collection and presplitHashedZones is false.

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.

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.

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 and its helper sh.shardCollection().

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

Dica

Voltar

setAllowMigrations

estado de fragmentação