collMod (comando de base de datos)

Cambiar las propiedades del índice

Para cambiar las opciones de índice, especifica el patrón clave o el nombre de las opciones de índice existentes que se quieran cambiar:

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

Si el índice no existe, el comando da un error con el mensaje "cannot find index <name|keyPattern> for ns <db.collection>".

index

La opción index puede cambiar las siguientes propiedades de un índice existente:

Propiedad del índice	Descripción
expireAfterSeconds	El número de segundos que determina el umbral de caducidad de una colección de TTL. Si es exitoso, el comando devuelve un documento que contiene: expireAfterSeconds_new, el nuevo valor para expireAfterSeconds expireAfterSeconds_old, el valor anterior para expireAfterSeconds, si el índice tenía un valor para expireAfterSeconds antes. Modificar la opción de índice expireAfterSeconds restablece el $indexStats para el índice. Si utilizas índices TTL creados antes de MongoDB 5.0, o si deseas sincronizar datos creados en MongoDB 5.0 con una versión anterior a la instalación 5.0, consulta Índices configurados usando NaN para evitar problemas de configuración errónea. El valor del índice TTL expireAfterSeconds debe estar entre 0 y 2147483647, inclusive.
hidden	Un booleano que determina si el índice está oculto o no para el planificador de queries. Si el valor de hidden cambia, el comando devuelve un documento que contiene tanto los valores antiguos como los nuevos de la propiedad modificada: hidden_old y hidden_new. Sin embargo, si el valor de hidden no ha cambiado (es decir, ocultar un índice ya oculto o desocultar un índice ya no oculto), el comando omite los campos hidden_old y hidden_new de la salida. Para ocultar un índice, se debe tener el valor featureCompatibilityVersion de 4.4 o superior. Al modificar la opción de índice hidden se restablece el $indexStats para el índice si el valor cambia.
prepareUnique	Un booleano que decide si el índice va a aceptar nuevas entradas duplicadas. Las nuevas entradas duplicadas producen errores DuplicateKey cuando prepareUnique es true. El índice resultante se puede convertir en un índice único. Para convertir el índice, se puede utilizar collMod con la opción unique. Si se actualiza un índice existente para que prepareUnique sea true, no se comprueba si hay entradas de índice duplicadas preexistentes. Novedades en la versión 6.0.
unique	Un booleano que determina si el índice es único. No se admite un valor de false. Cuando unique es true, collMod escanea el índice keyPattern en busca de duplicados y, a continuación, lo convierte en un índice único si no hay entradas de índice duplicadas. Si se detectan duplicados durante el análisis inicial, collMod devuelve CannotConvertIndexToUnique y una lista de documentos en conflicto. Para convertir un índice con entradas duplicadas a un índice único, se debe corregir cualquier conflicto reportado y volver a ejecutar collMod. Para finalizar una conversión, se establece prepareUnique como false. Para ver un ejemplo de cómo convertir un índice no único en un índice único, se puede consultar Convertir un índice existente en un índice único. Novedades en la versión 6.0.

dryRun

Valor por defecto: false

Solo se utiliza cuando index.unique es true.

Antes de convertir un índice no único en un índice único, se puede ejecutar el comando collMod con dryRun: true. Si se hace, MongoDB verifica la colección en busca de claves duplicadas y devuelve cualquier violación.

Se puede utilizar dryRun: true para confirmar que se puede convertir un índice para que sea único sin errores.

Validar documentos

validator

validator permite a los usuarios especificar reglas o expresiones de validación para una colección.

La opción validator requiere un documento que especifique las reglas o expresiones de validación. Puedes especificar las expresiones utilizando los mismos operadores que los operadores del query, con la excepción de $near, $nearSphere, $text, y $where.

Nota

• La validación ocurre durante las actualizaciones e inserciones. Los documentos existentes no pasan por comprobaciones de validación hasta que se modifican.

• No se puede especificar un validador para colecciones en las bases de datos admin, local y config.

• No se puede especificar un validador para las colecciones de system.*.

validationLevel

El validationLevel determina con qué rigor MongoDB aplica las reglas de validación a los documentos existentes durante una actualización.

"off"

No hay validación para inserciones o actualizaciones.

"strict"

Por defecto, aplica reglas de validación a todas las inserciones y a todas las actualizaciones.

"moderate"

Aplica reglas de validación a las inserciones y a las actualizaciones en documentos válidos existentes. No apliques reglas a las actualizaciones en documentos inválidos existentes.

Para ver un ejemplo que utiliza validationLevel, consulte Especificar nivel de validación para documentos existentes.

validationAction

La opción validationAction determina si error a los documentos no válidos o simplemente warn sobre las infracciones, pero permite documentos no válidos.

Importante

La validación de documentos solo se aplica a aquellos documentos según lo determinado por el validationLevel.

Para ver un ejemplo que utiliza validationAction, consulte Elija cómo gestionar documentos no válidos.

Modificar vistas

viewOn

La colección o vista subyacente de origen. La definición de la vista se determina aplicando el pipeline especificado a esta fuente.

Necesario si se modifica una vista en una implementación de MongoDB que se ejecuta con control de acceso.

pipeline

La pipeline de agregación que define la vista.

Nota

Una definición de vista pipeline no puede incluir la etapa $out o la $merge. Esta restricción también se aplica a pipelines integradas, como las pipelines usadas en las etapas de $lookup o $facet.

Necesario si se modifica una vista en una implementación de MongoDB que se ejecuta con control de acceso.

La definición de la vista es pública; es decir, las operaciones db.getCollectionInfos() y explain en la vista incluirán el pipeline que define la vista. Por lo tanto, evite referirse directamente a campos y valores sensibles en las definiciones de vistas.

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

Modificar colecciones de series de tiempo

expireAfterSeconds

Nota

Esto es distinto de usar la opción index con la propiedad expireAfterSeconds para cambiar el tiempo de caducidad de una Colección TTL.

Para habilitar la eliminación automática de documentos o modificar el intervalo de caducidad actual de una colección de series de tiempo, se debe cambiar el valor expireAfterSeconds:

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

Se puede establecer expireAfterSeconds en "off" para deshabilitar la eliminación automática, o un número decimal no negativo (>=0) para especificar la cantidad de segundos después de los cuales los documentos caducan.

granularity

Para modificar la granularidad de una colección de series de tiempo, se puede aumentar timeseries.granularity de una unidad de tiempo más corta a una más larga:

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

Para actualizar los campos de bucketing personalizados bucketRoundingSeconds y bucketMaxSpanSeconds en lugar de granularity, se incluyen ambos campos personalizados en el comando collMod y se ponen al mismo valor:

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

No se puede disminuir el intervalo de granularidad ni los valores de agrupación personalizados.

Importante

No se puede degradar por debajo de MongoDB 6.3 si alguna colección de series de tiempo especifica explícitamente los campos de agrupamiento personalizados bucketMaxSpanSeconds y bucketRoundingSeconds. Si es posible, se debe convertir a la granularitycorrespondiente. Si no se puede, se debe descartar la colección antes de degradar.

Para convertir una colección de bucketing personalizado a un valor granularity, tanto bucketMaxSpanSeconds como bucketRoundingSeconds deben ser menores o iguales al equivalente granularity :

granularity	bucketRoundingSeconds límite (incluido)	bucketMaxSpanSeconds límite (incluido)
seconds	60	3600
minutes	3600	86400
hours	86400	2592000

Tip

Establece la granularidad para los datos de series de tiempo

Cambiar el tamaño de una colección con tamaño fijo

A partir de MongoDB 6.0, se puede cambiar el tamaño de una colección con tamaño fijo. Para cambiar el tamaño máximo de una colección con tamaño fijo en bytes, se puede utilizar la opción cappedSize. Para cambiar el número máximo de documentos en una colección con tamaño fijo existente, se puede utilizar la opción cappedMax.

cappedSize

Especifica un nuevo tamaño máximo, en bytes, para una colección con tamaño fijo. cappedSize debe ser mayor que 0 y menor que 1e+15 (1 PB).

cappedMax

Especifica un nuevo número máximo de documentos en una colección con tamaño fijo. Establecer cappedMax menor o igual que 0 implica que no hay límite.

Por ejemplo, el siguiente comando establece el tamaño máximo de una colección con tamaño fijo en 100000 bytes y establece la cantidad máxima de documentos de la colección en 500:

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

Change Streams con imágenes previas y posteriores de los documentos

changeStreamPreAndPostImages

A partir de MongoDB 6.0, puedes utilizar eventos de flujo de cambios para generar la versión de un documento antes y después de los cambios (las imágenes previas y posteriores del documento):

• La imagen previa es el documento antes de reemplazarlo, actualizarlo o borrarlo. No existe una imagen previa para un documento insertado.

• La imagen posterior es el documento tras insertarse, sustituirse o actualizarse. No hay imagen posterior para un documento borrado.

• Se puede activarchangeStreamPreAndPostImages para una colección con db.createCollection(), create o collMod. Por ejemplo, cuando se utiliza el comando collMod:

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

Si se desea utilizar collMod para permitir las imágenes previas y posteriores del flujo de cambios para una colección, se debe utilizar el campo changeStreamPreAndPostImages:

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

Para permitir las imágenes previas y posteriores del flujo de cambios para una colección, se establece changeStreamPreAndPostImages en true. Por ejemplo:

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

Para deshabilitar las imágenes previas y posteriores del flujo de cambios para una colección, se establece changeStreamPreAndPostImages en false. Por ejemplo:

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

Las imágenes previas y posteriores no están disponibles para un evento de flujo de cambios si las imágenes fueron:

• No está habilitado en la colección en el momento de la operación de actualización o eliminación de un documento.

• Eliminado después del tiempo de retención de imágenes previas y posteriores establecido en expireAfterSeconds.

  • El siguiente ejemplo configura expireAfterSeconds en 100 segundos en todo el clúster:

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: {
             preAndPostImages: { expireAfterSeconds: 100 }
          } }
    } )

    Nota

    El comando setClusterParameter no es compatible con los clústeres de MongoDB Atlas. Para obtener información sobre el soporte de Atlas para todos los comandos, consulta Comandos no compatibles en Atlas.

  • El siguiente ejemplo devuelve la configuración actual de changeStreamOptions, incluyendo expireAfterSeconds:

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )

  • Configurar expireAfterSeconds en off utiliza la política de retención por defecto: las imágenes previas y posteriores se conservan hasta que los eventos correspondientes del flujo de cambios se eliminan del oplog.

  • Si se elimina un evento de flujo de cambios del oplog, las imágenes previas y posteriores correspondientes también se eliminan independientemente del tiempo de retención de las imágenes previas y posteriores expireAfterSeconds.

Consideraciones adicionales:

• Habilitar las imágenes previas y posteriores consume espacio de almacenamiento y aumenta el tiempo de procesamiento. Habilita solo las imágenes previas y de publicación si las necesitas.

• Limita el tamaño del evento del flujo de cambios a menos de 16 mebibytes. Para limitar el tamaño del evento, puedes:

  • Limita el tamaño del documento a 8 megabytes. Puedes solicitar imágenes previas y posteriores simultáneamente en la salida del flujo de cambios si otros campos de eventos del flujo de cambios como updateDescription no son grandes.

  • Solicita solo imágenes posteriores en la salida del flujo de cambios para documentos de hasta 16 mebibytes si otros campos de eventos del flujo de cambios como updateDescription no son grandes.

  • Solicita solo imágenes previas en la salida del flujo de cambios para documentos de hasta 16 mebibytes si:

    • las actualizaciones de documento afectan solo a una pequeña fracción de la estructura o el contenido del documento, y

    • no cause un evento de cambio replace. Un evento replace siempre incluye la imagen de publicación.

• Para realizar una solicitud de imagen previa, debes establecer fullDocumentBeforeChange en required o whenAvailable en db.collection.watch(). Para solicitar una imagen posterior, establece fullDocument mediante el mismo método.

• Las imágenes previas se escriben en la colección config.system.preimages.

  • La colección config.system.preimages puede agrandarse. Para limitar el tamaño de la colección, puedes establecer el tiempo a expireAfterSeconds para las imágenes previas como se mostró antes.

  • Las imágenes previas se eliminan de forma asincrónica mediante un proceso en segundo plano.

Adjuntar comentario

comment

Opcional. Se puede adjuntar un comentario a este comando. El comentario debe ser un campo de nivel superior y puede ser cualquier tipo BSON válido. El comentario que se especifique aparece junto con los registros de este comando en las siguientes ubicaciones:

• Mensajes de registro de mongod, en el campo attr.command.cursor.comment.

• Salida del perfilador de base de datos, en el campo command.comment.

• currentOp de salida, en el campo command.comment.

Nivel de confirmación de escritura

w

Opcional. Un documento que expresa el nivel de confirmación de escritura del comando collMod.

Omite usar el nivel de confirmación de escritura por defecto.

Bloqueo de recursos

El comando collMod obtiene un bloqueo de colección sobre la colección especificada mientras dura la operación.

Cambiar el valor de caducidad de los índices

El siguiente ejemplo actualiza la propiedad expireAfterSeconds de un índice TTL existente { lastAccess: 1 } en una colección llamada user_log. La propiedad de expireAfterSeconds actual para el índice se establece en 1800 segundos (o 30 minutos) y el ejemplo cambia el valor a 3600 segundos (o 60 minutos).

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

Si es exitosa, la operación devuelve un documento que incluye el valor anterior y el nuevo de la propiedad modificada:

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

Ocultar un índice del planificador de query

El siguiente ejemplo oculta un índice existente en la colección orders. En concreto, la operación oculta el índice con la especificación { shippedDate: 1 } del planificador de query.

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

Si es exitosa, la operación devuelve un documento que incluye el valor anterior y el nuevo de la propiedad modificada:

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

Para ocultar un índice de texto, se debe especificar el índice por name y no por keyPattern.