CollMod

Alterar propriedades do índice

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. Observação Deve ser definido como true. false não é suportado. 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.

Validar documentos

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.

validationLevel	Descriçã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.

Modificar visualizações

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

Modificar coleções de séries temporais

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 parâmetros de bucketing personalizados bucketRoundingSeconds e bucketMaxSpanSeconds em vez de granularity, inclua ambos os parâmetros 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 parâmetros 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

Dica

Veja também:

Definir granularidade para dados de série temporal

Redimensionar uma capped collection

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.

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

Altere fluxos com pré e pós-imagens de documentos

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

Anexar comentário

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:

• mensagens de log do mongod, no campo attr.command.cursor.comment.

• Saída do perfil do banco de dados, no campo command.comment.

• Saída de currentOp, no campo command.comment.

Escreva preocupação

w

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

Omitir para usar a write concern.

Bloqueio de recursos

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

Alterar valor de expiração para índices

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 }

Ocultar um Índice do Planejador de Query

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 }

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