Menu Docs

CollMod

collMod

collMod torna possível adicionar opções a uma collection ou modificar definições de visualização.

Dica

Em mongosh, este comando também pode ser executado por meio dos métodos assistentes hideIndex() unhideIndex().

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.

Observação

A visualização modificada por collMod não se refere a visualizações materializadas. Para uma discussão sobre visualizações materializadas sob demanda, consulte $merge em vez disso.

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

Observação

Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, 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

O comando tem a seguinte sintaxe:

db.runCommand(
{
collMod: <collection or view>,
<option1>: <value1>,
<option2>: <value2>,
...
}
)

Para o <collection or view>, especifique o nome de uma collection ou visualização no banco de dados atual.

Para alterar as opções de índice, especifique o padrão de chave ou o nome das opções de índice existentes que você deseja alterar:

db.runCommand( {
collMod: <collection>,
index: {
keyPattern: <index_spec> | name: <index_name>,
expireAfterSeconds: <number>, // Set the TTL expiration threshold
hidden: <boolean>, // Change index visibility in the query planner
prepareUnique: <boolean>, // Reject new duplicate index entries
unique: <boolean> // Convert an index to a unique index
},
dryRun: <boolean>
} )

Se o índice não existir, os erros de comando com a mensagem "cannot find index <name|keyPattern> for ns <db.collection>".

index

A opção index pode alterar as seguintes propriedades de um índice existente:

Propriedade do Índice
Descrição

expireAfterSeconds

O número de segundos que determina o limite de expiração de uma collection TTL.

Se o comando for bem-sucedido, o comando retornará um documento que contém:

  • expireAfterSeconds_new, o novo valor para expireAfterSeconds

  • expireAfterSeconds_old, o valor antigo de expireAfterSeconds, se o índice tivesse um valor para expireAfterSeconds antes.

A modificação da opção de índice expireAfterSeconds redefine o $indexStats para o índice.

Se você usa índices TTL criados antes do MongoDB 5.0 ou se deseja sincronizar dados criados no MongDB 5.0 com um pré-5.0 instalação, consulte Índices configurados usando NaN para evitar problemas de configuração incorreta.

O valor expireAfterSeconds do índice TTL deve estar dentro de 0 e 2147483647 inclusive.

hidden

Um booleano que determina se o índice é oculto ou não do planejador de query.

Se o valor hidden for alterado, o comando retornará um documento contendo os valores antigo e novo da propriedade alterada: hidden_old e hidden_new.

No entanto, se o valor de hidden não tiver mudado (ou seja, ocultando um índice já oculto ou ocultando um índice já oculto), o comando emite os campos hidden_old e hidden_new da saída.

Para ocultar um índice, você deve ter featureCompatibilityVersion configurado para 4.4 ou superior.

Modificar a opção de índice hidden redefine o $indexStats do índice se o valor for alterado.

prepareUnique

Um booleano que determina se o índice aceitará novas entradas duplicadas.

Novas entradas duplicadas falham com erros de DuplicateKey quando prepareUnique é true. O índice resultante pode ser convertido em um índice único. Para converter o índice, utilize collMod com a opção unique.

Se um índice existente for atualizado para que prepareUnique seja true, o índice não será verificado quanto a entradas de índice duplicadas pré-existentes.

Novidades na versão 6.0.

unique

Um booleano que determina se o índice é ou não único.

Um valor de false não é compatível.

Quando unique é true, collMod verifica o índice keyPattern em busca de duplicatas e o converte em um índice único se não houver entradas de índice duplicadas.

Se forem detectadas duplicatas durante a verificação inicial, collMod retornará CannotConvertIndexToUnique e uma lista de documentos conflitantes. Para converter um índice com entradas duplicadas em um índice único, corrija quaisquer conflitos relatados e execute novamente collMod.

Para encerrar uma conversão, defina prepareUnique como false.

Para ver um exemplo de como converter um índice não único em um índice único, consulte Converter um índice existente em um índice único.

Novidades na versão 6.0.

dryRun

Valor padrão: false

Usado apenas quando index.unique é true.

Antes de converter um índice não único em um índice único, você pode executar o comando collMod com dryRun: true. Se você fizer isso, o MongoDB verificará a coleção em busca de chaves duplicadas e retornará quaisquer violações.

Usar dryRun: true para confirmar que você pode converter um índice em exclusivo sem erros.

validator

validator permite aos usuários especificar regras ou expressões de validação para uma collection.

A opção validator requer um documento que especifica as regras ou expressões de validação. Você pode especificar as expressões usando os mesmos operadores que os operadores de consulta, com exceção de $near, $nearSphere, $text e $where.

Observação

  • A validação ocorre durante atualizações e inserções. Os documentos existentes não passam por verificações de validação até a modificação.

  • Você não pode especificar um validador para collections nos bancos de dados admin, local e config.

  • Você não pode especificar um validador para collections system.* .

validationLevel

O validationLevel determina quão rigorosamente o MongoDB aplica as regras de validação aos documentos existentes durante uma atualização.

"off"
Nenhuma validação para inserções ou atualizações.
"strict"
Padrão Aplique regras de validação a todas as inserções e todas as atualizações.
"moderate"
Aplique regras de validação a inserções e atualizações em documentos válidos existentes. Não aplique regras a atualizações em documentos inválidos existentes.

Para ver um exemplo que utiliza o validationLevel, consulte Especificar nível de validação para documentos existentes.

validationAction

A opção validationAction determina se error em documentos inválidos ou apenas warn sobre as violações, mas permite documentos inválidos.

Importante

A validação de documentos só se aplica aos documentos como determinado pelo validationLevel.

Para ver um exemplo que usa validationAction, consulte Escolher como manipular documentos inválidos.

Observação

A visualização modificada por este comando não se refere a visualizações materializadas. Para discussão sobre visualizações materializadas sob demanda, consulte $merge .

viewOn

A coleção de origem subjacente ou visualização. A definição de exibição é determinada aplicando o pipeline especificado a essa fonte.

Obrigatório ao modificar uma visualização em uma MongoDB deployment que está sendo executada com controle de acesso.

pipeline

O aggregation pipeline que define a visualização.

Observação

Uma definição de visualização pipeline não pode incluir o estágio $out ou $merge. Essa restrição também se aplica a pipelines incorporados, como pipelines usados em estágios $lookup ou $facet.

Obrigatório ao modificar uma visualização em uma MongoDB deployment que está sendo executada com controle de acesso.

A definição da visualização é pública; ou seja, as operações db.getCollectionInfos() e explain na exibição incluirão o pipeline que define a visualização. Dessa forma, evite se referir diretamente a campos e valores confidenciais nas definições de visualização.

db.runCommand( {
collMod: "myView",
viewOn: "activities",
pipeline: [
{ $match: { status: "Q" } },
{ $project: { user: 1, date: 1, description: 1} } ]
} )
expireAfterSeconds

Observação

Isso é diferente de usar a opção index com a propriedade expireAfterSeconds para alterar o tempo de expiração de uma coleção TTL.

Para ativar a remoção automática de documentos ou modificar o intervalo de expiração atual de uma coleção de séries temporais, altere o valor expireAfterSeconds:

db.runCommand( {
collMod: <collection>,
expireAfterSeconds: <number> | "off"
} )

Defina expireAfterSeconds como "off" para desativar a remoção automática ou um número decimal não negativo (>=0) para especificar o número de segundos após os quais os documentos expiram.

granularity

Para modificar a granularidade de uma coleção de séries temporais, você pode aumentar timeseries.granularity de uma unidade de tempo mais curta para uma mais longa:

db.runCommand( {
collMod: "weather24h",
timeseries: { granularity: "seconds" | "minutes" | "hours" }
} )

Para atualizar os campos de bucketing personalizados bucketRoundingSeconds e bucketMaxSpanSeconds em vez de granularity, inclua ambos os campos personalizados no comando collMod e defina-os com o mesmo valor:

db.runCommand( {
collMod: "weather24h",
timeseries: {
bucketRoundingSeconds: 86400,
bucketMaxSpanSeconds: 86400
}
} )

Você não pode diminuir o intervalo de granularidade ou os valores de agrupamento personalizados.

Importante

Não é possível fazer downgrade abaixo do MongoDB 6.3 se qualquer coleção de séries temporais especificar explicitamente os campos de bucketing personalizados bucketMaxSpanSeconds e bucketRoundingSeconds. Se possível, converta para o granularity correspondente. Se não puder, você deverá descartar a collection antes de fazer o downgrade.

Para converter uma collection de compartimento personalizado em um valor granularity, bucketMaxSpanSeconds e bucketRoundingSeconds devem ser menores ou iguais ao equivalente a granularity:

granularity
bucketRoundingSeconds limite (inclusive)
bucketMaxSpanSeconds limite (inclusive)

seconds

60

3600

minutes

3600

86400

hours

86400

2592000

Novidades na versão 6.0.

A partir do MongoDB 6.0, você pode redimensionar uma capped collection. Para alterar o tamanho máximo de uma capped collection em bytes, use a opção cappedSize . Para alterar o número máximo de documentos em uma capped collection existente, use a opção cappedMax.

Observação

Você não pode usar esses comandos para redimensionar o oplog. Use replSetResizeOplog em vez disso.

cappedSize

Especifique um novo tamanho máximo, em bytes, para uma capped collection. cappedSize deve ser maior que 0 e menor que 1e+15 (1 PB).

cappedMax

Especifica um novo número máximo de documentos em uma capped collection. Definir cappedMax menor ou igual a 0 não implica nenhum limite.

Por exemplo, o comando a seguir define o tamanho máximo de uma capped collection para 100000 bytes e define o número máximo de documentos na collection para 500:

db.runCommand( {
collMod: <collection>,
cappedSize: 100000,
cappedMax: 500
} )

Novidades na versão 6.0.

changeStreamPreAndPostImages

A partir do MongoDB 6.0, você pode usar eventos change stream para produzir a versão de um documento antes e depois das alterações (pré e pós-imagens do documento):

  • A pré-imagem é o documento antes de ser substituído, atualizado ou excluído. Não há pré-imagem para um documento inserido.

  • A pós-imagem é o documento após ter sido inserido, substituído ou atualizado. Não há pós-imagem para um documento excluído.

  • Habilite changeStreamPreAndPostImages para uma coleção utilizando db.createCollection(), create ou collMod.

Para usar o collMod para habilitar a alteração de pré e pós-imagens de fluxo para uma collection, use o campo changeStreamPreAndPostImages:

db.runCommand( {
collMod: <collection>,
changeStreamPreAndPostImages: { enabled: <boolean> }
} )

Para habilitar a alteração de pré e pós-imagens de fluxo para uma collection, defina changeStreamPreAndPostImages como true. Por exemplo:

db.runCommand( {
collMod: "orders",
changeStreamPreAndPostImages: { enabled: true }
} )

Para desativar a alteração do change stream de uma collection, defina changeStreamPreAndPostImages como false. Por exemplo:

db.runCommand( {
collMod: "orders",
changeStreamPreAndPostImages: { enabled: false }
} )

As imagens pré e pós não estarão disponíveis para um change stream se as imagens forem:

  • Não habilitadas na coleção no momento de uma operação de atualização ou exclusão de documento.

  • Removido após o tempo de retenção pré e pós-imagem definido em expireAfterSeconds.

    • O exemplo a seguir define expireAfterSeconds para 100 segundos em um cluster inteiro:

      use admin
      db.runCommand( {
      setClusterParameter:
      { changeStreamOptions: {
      preAndPostImages: { expireAfterSeconds: 100 }
      } }
      } )
    • O exemplo a seguir retorna as configurações atuais do changeStreamOptions, incluindo expireAfterSeconds:

      db.adminCommand( { getClusterParameter: "changeStreamOptions" } )
    • Definir expireAfterSeconds para off usa a política de retenção: pré-imagens e pós-imagens são retidas até os eventos de change streams serem removidos do oplog.

    • Se um change stream for removido do oplog, as imagens pré e pós correspondentes também serão excluídas, independentemente do tempo de retenção pré e pós-imagem expireAfterSeconds .

Considerações adicionais:

  • Habilitar pré e pós-imagens consome espaço de armazenamento e adiciona tempo de processamento. Ative as imagens anteriores e posteriores somente se precisar delas.

  • Limite o tamanho do evento de transmissão da alteração para menos de 16 megabytes. Para limitar o tamanho do evento, você pode:

    • Limite o tamanho do documento a 8 megabytes. Você pode solicitar imagens pré e pós simultaneamente na saída do change stream se outros campos de evento de change stream, como updateDescription não forem grandes.

    • Solicite apenas pós-imagens na saída de fluxo de alteração para documentos de até 16 megabytes se outros campos de evento de fluxo de alteração como updateDescription não forem grandes.

    • Solicite somente pré-imagens na saída do change stream para documentos de até 16 megabytes se:

      • as atualizações do documento afetam apenas uma pequena fração da estrutura ou conteúdo do documento, e

      • não causa um evento de alteração replace . Um evento replace sempre inclui o pós-imagem.

  • Para solicitar uma pré-imagem, defina fullDocumentBeforeChange como required ou whenAvailable em db.collection.watch(). Para solicitar uma pós-imagem, defina fullDocument usando o mesmo método.

  • As pré-imagens são gravadas na coleção config.system.preimages.

    • A coleção config.system.preimages pode ficar grande. Para limitar o tamanho da coleção, você pode definir expireAfterSeconds tempo para as pré-imagens, conforme mostrado anteriormente.

    • As pré-imagens são removidas de forma assíncrona por um processo de plano de fundo.

Importante

Funcionalidade incompatível com versões anteriores

A partir do MongoDB 6.0, se você estiver usando imagens pré e pós-documento para change streams, deverá desabilitar changeStreamPreAndPostImages para cada collMod usando o comando antes de poder fazer o downgrade para uma versão anterior do MongoDB.

Dica

Veja também:

comment

Opcional. Você pode anexar um comentário a este comando. O comentário deve ser um campo de nível superior e pode ser qualquer tipo JSON válido. O comentário que você especifica aparece ao lado dos registros deste comando nos seguintes locais:

w

Opcional. Um documento que expressa a write concern do comando collMod.

Omitir para usar a write concern.

Se a implantação impuser autenticação/autorização, você deverá ter o seguinte privilégio para executar o comando collMod:

Tarefa
Privilégios necessários

Modificar uma non-capped collection

collMod no banco de dados

Modificar uma visualização

collMod no banco de dados e:

  • nenhum find na visualização para modificar, ou

  • ambos find na visualização a ser modificada e find na collection/visualização de origem.

A função embutida dbAdmin fornece os privilégios exigidos.

O comando collMod obtém uma trava de coleção na coleção especificada durante a operação.

O exemplo seguinte atualiza a propriedade expireAfterSeconds de um índice TTL { lastAccess: 1 } existente em uma collection denominada user_log. A propriedade expireAfterSeconds atual do índice está definida para 1800 segundos (ou 30 minutos) e o exemplo altera o valor para 3600 segundos (ou 60 minutos).

db.runCommand({
collMod: "user_log",
index: {
keyPattern: { lastAccess: 1 },
expireAfterSeconds: 3600
}
})

Se a operação for bem-sucedida, a operação retornará um documento que inclui o valor antigo e o novo para a propriedade alterada:

{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }

Observação

Para ocultar um índice, você deve ter featureCompatibilityVersion configurado para 5.0 ou superior.

O exemplo a seguir oculta um índice existente na collection orders. Especificamente, a operação oculta o índice com a especificação { shippedDate: 1 } do planejador de query.

db.runCommand( {
collMod: "orders",
index: {
keyPattern: { shippedDate: 1 },
hidden: true
}
} )

Se a operação for bem-sucedida, a operação retornará um documento que inclui o valor antigo e o novo para a propriedade alterada:

{ "hidden_old" : false, "hidden_new" : true, "ok" : 1 }

Observação

Se a operação for bem-sucedida, mas o valor hidden não tiver sido alterado (especificamente, ocultando um índice já oculto ou exibindo um índice já não oculto), o comando omitirá os campos hidden_old e hidden_new da saída.

Para ocultar um índice de texto, você deve especificar o índice por name e não por keyPattern.