sharedCollection

Nesta página

Definição

Compatibilidade
Sintaxe
Campos de comando
Considerações
Exemplo

Definição

shardCollection: Fragmenta uma collection para distribuir seus documentos entre shards. O comando shardCollection deve ser executado no banco de dados admin .
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.
Dica
Em mongosh, esse comando também pode ser executado por meio do método auxiliar sh.shardCollection().
Os métodos auxiliares são práticos para os usuários mongosh, mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a praticidade não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.

Compatibilidade

Esse comando 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 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 com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

Para executar shardCollection, utilize o método db.runCommand( { <command> } ).

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

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. A chave de fragmento deve ser suportada por um índice. A menos que a coleção esteja vazia, o índice deve existir antes do comando `shardCollection`. Se a coleção estiver vazia, o MongoDB criará o índice antes de fragmentar a coleção 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	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. Se fragmentar com presplitHashedZones: true, o MongoDB tentará distribuir uniformemente o número especificado de partes pelas zonas do cluster. Se fragmentar com presplitHashedZones: false ou omitido e não houver zona e faixa de zona para a coleção vazia, o MongoDB tentará distribuir uniformemente o número especificado de partes através dos fragmentos no cluster. Se fragmentar com presplitHashedZones: false ou omitido e houver zonas e faixas de zona definidas para a coleção vazia, `numInitialChunks` não terá efeito.
`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. As faixas de zona definidas não atendem aos requisitos.
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`. Para obter uma sintaxe detalhada, consulte Opções de séries temporais. Novidades na versão 5.1.

Opções de séries temporais

Novidades na versão 5.1.

Para criar uma nova coleção de séries temporais que seja fragmentada, especifique a opção série temporal como shardCollection.

A opção de série temporal usa 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`. A partir do MongoDB 8.0, o uso de `timeField` como uma chave de fragmento em uma coleção de séries temporais será descontinuado.
`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

Veja também:

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:

A partir do MongoDB 8.0, o uso de timeField como uma chave de fragmento em uma coleção de séries temporais será descontinuado.

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

Veja também:

Fragmentação em hash

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

A operação de coleção de fragmentos (ou seja, o comando shardCollection e o auxiliar sh.shardCollection()) podem executar a criação e a distribuição inicial de partes para uma coleção vazia ou inexistente se as zonas e os intervalos de zonas tiverem sido definidos para a coleção. A distribuição inicial de partes permite uma configuração mais rápida do zoneamento de fragmentação. Após a distribuição inicial, o balanceador passa a gerenciar a distribuição de partes como de costume.

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 coleção usando um índice com hash 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.

A opção numInitialChunks não tem efeito se zonas e faixas de zonas tiverem sido definidas para a coleção vazia, e preSplitHashedZones for false.

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

Dica

Veja também:

Exclusividade

Se especificar unique: true:

Se a coleção estiver vazia, shardCollection criará o índice único na chave de fragmento se esse índice ainda não existir.
Se a coleção não estiver vazia, você deverá criar o índice antes de utilizar 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

Se a coleção tiver um agrupamento padrão, o comando shardCollection precisa incluir um parâmetro collation com o valor { locale: "simple" }. Para coleções não vazias com um agrupamento padrão, você deve ter pelo menos um índice com o agrupamento simples cujos campos ofereçam suporte ao padrão da chave de fragmento.

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 usa "majority" para o preocupação de gravação do comando shardCollection , seu assistente sh.shardCollection() e o método sh.shardAndDistributeCollection() .

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

Veja também:

Voltar

setAllowMigrations

estado de fragmentação