/ /

Métodos mongosh

Databases

Docs Home

Manual de MongoDB

Referencia

Métodos mongosh

Databases

db.createCollection()

Esta versión de la documentación está archivada y ya no recibe soporte. Para actualizar su implementación 5.0, consulte Procedimientos de actualización de MongoDB.6.0

Definición

db.createCollection(name, options)

Crea una nueva colección o vista. Para vistas, véase db.createView() también.

Debido a que MongoDB crea una colección implícitamente cuando la colección se referencia por primera vez en un comando, este método se usa principalmente para crear nuevas colecciones que utilizan opciones específicas. Por ejemplo, se utiliza db.createCollection() para crear una colección con tamaño fijo, o para crear una nueva colección que use validación de documentos.

db.createCollection() es un contenedor alrededor del comando de base de create datos.

Compatibilidad

Este método está disponible en implementaciones alojadas en los siguientes entornos:

MongoDB Atlas: El servicio totalmente gestionado para implementaciones de MongoDB en la nube

Nota

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

MongoDB Enterprise: La versión basada en suscripción y autogestionada de MongoDB
MongoDB Community: La versión de MongoDB con código fuente disponible, de uso gratuito y autogestionada.

Sintaxis

El método db.createCollection() tiene el siguiente formato de prototipo:

db.createCollection( <name>,
    {
      capped: <boolean>,
      timeseries: {                  // Added in MongoDB 5.0
         timeField: <string>,        // required for time series collections
         metaField: <string>,
         granularity: <string>
      },
      expireAfterSeconds: <number>,
      clusteredIndex: <document>,  // Added in MongoDB 5.3
      changeStreamPreAndPostImages: <document>,  // Added in MongoDB 6.0
      size: <number>,
      max: <number>,
      storageEngine: <document>,
      validator: <document>,
      validationLevel: <string>,
      validationAction: <string>,
      indexOptionDefaults: <document>,
      viewOn: <string>,
      pipeline: <pipeline>,
      collation: <document>,
      writeConcern: <document>
    }
  )

El método db.createCollection() tiene los siguientes parámetros:

Parameter	Tipo	Descripción
`name`	string	El nombre de la colección que se va a crear. Consulta Restricciones de nombres.
`options`	Documento	Opcional. Opciones de configuración para crear una: Colección con tamaño fijo Colección con índice clusterizado vista

El documento options contiene los siguientes campos:

Campo

Tipo

Descripción

capped

booleano

Opcional. Para crear una colección con tamaño fijo, especifica true. Si especificas true, también debes establecer un tamaño máximo en el campo size.

timeseries.timeField

string

Requerido al crear una colección de series de tiempo. El nombre del campo que contiene la fecha en cada documento de serie de tiempo. Los documentos en una colección de series de tiempo deben tener una fecha BSON válida como valor para el timeField.

timeseries.metaField

string

Opcional. El nombre del campo que contiene metadatos en cada documento de serie de tiempo. Los metadatos en el campo especificado deben ser datos utilizados para etiquetar una serie única de documentos. Los metadatos deberían cambiar rara vez, o nunca.

El nombre del campo especificado no puede ser _id ni el mismo que el timeseries.timeField. El campo puede ser de cualquier tipo excepto un arreglo.

timeseries.granularity

string

Opcional, no lo utilices si se configura bucketRoundingSeconds y bucketMaxSpanSeconds. Los valores posibles son seconds (por defecto), minutes y hours.

Configura granularity al valor que más se asemeje al intervalo de tiempo entre las marcas de tiempo entrantes consecutivas. Esto mejora el rendimiento al optimizar cómo MongoDB almacena internamente los datos en la colección.

Para obtener más información sobre la granularidad y los intervalos de agrupación, consulta Configurar granularidad para datos de series de tiempo.

expireAfterSeconds

Número

Opcional. Especifica los segundos tras los cuales caducan los documentos de una colección de series temporales. MongoDB elimina automáticamente los documentos caducados.

size

Número

Opcional. Especifica un tamaño máximo en bytes para una colección con tamaño fijo. Una vez que una colección con tamaño fijo alcanza su tamaño máximo, MongoDB remueve los documentos más antiguos para dejar espacio a los nuevos documentos. El campo size es obligatorio para las colecciones con tamaño fijo y se ignora para las demás colecciones.

max

Número

Opcional. El número máximo de documentos permitidos en la colección con tamaño fijo. El límite de size tiene prioridad sobre este límite. Si una colección con tamaño fijo alcanza el límite size antes de alcanzar el número máximo de documentos, MongoDB remueve los documentos antiguos. Si prefieres usar el límite de max, asegúrate de que el límite de size, que es necesario para una colección con tamaño fijo, sea suficiente para contener el número máximo de documentos.

storageEngine

Documento

Opcional. Disponible solo para el motor de almacenamiento WiredTiger.

Permite a los usuarios especificar la configuración para el motor de almacenamiento por colección al crear una colección. El valor de la opción storageEngine debe tomar la siguiente forma:

{ <storage-engine-name>: <options> }

La configuración del motor de almacenamiento especificada al crear colecciones se valida y se registra en el oplog durante la replicación para soportar conjuntos de set de réplicas con miembros que utilizan diferentes motores de almacenamiento.

Para obtener detalles, consulte Especificar opciones del motor de almacenamiento.

validator

Documento

Opcional. Permite a los usuarios especificar reglas o expresiones de validación para la 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.

Para aprender a crear una colección con validación de esquema, consulte Esquema JSON.

validationLevel

string

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

validationAction

string

Opcional. Determina si se debe mostrar error en documentos no válidos o solo warn sobre las infracciones, pero permite que se inserten documentos no válidos.

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

indexOptionDefaults

Documento

Opcional. Permite a los usuarios especificar una configuración por defecto para los índices al crear una colección.

La opción indexOptionDefaults acepta un documento storageEngine, el cual debe tener la siguiente forma:

{ <storage-engine-name>: <options> }

La configuración del motor de almacenamiento especificada al crear índices se valida y se registra en el oplog durante la replicación para admitir sets de réplicas con miembros que utilizan diferentes motores de almacenamiento.

viewOn

string

El nombre de la colección o vista de origen desde la cual crear una vista. Para obtener más detalles, consulta db.createView().

pipeline

arreglo

Un arreglo que consta de las etapas de la canalización de agregación. db.createView() crea una vista aplicando el pipeline especificado a la colección o vista viewOn. Para obtener más detalles, consulta db.createView().

collation

Documento

Especifica la intercalación por defecto para la colección.

La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.

La opción de intercalación tiene la siguiente sintaxis:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

Al especificar la intercalación, el campo locale es obligatorio; todos los demás campos de intercalación son opcionales. Para las descripciones de los campos, consulta Documento de intercalación.

Si especificas una intercalación a nivel de colección:

Los índices de esa colección se crearán con esa intercalación a menos que la operación de creación del índice especifique explícitamente una intercalación diferente.
Las operaciones en esa colección utilizan la intercalación por defecto de la colección, a menos que especifiquen explícitamente una intercalación diferente.
No puedes especificar varias intercalaciones para una operación. Por ejemplo, no puedes especificar diferentes intercalaciones por campo, o si realizas una búsqueda con un ordenamiento, no puedes usar una intercalación para la búsqueda y otra para el ordenamiento.

Si no se especifica ninguna intercalación para la colección o para las operaciones, MongoDB utiliza la comparación binaria simple usada en versiones anteriores para las comparaciones de strings.

Para una colección, solo puedes especificar la intercalación durante la creación de la colección. Una vez establecida, no puedes modificar la intercalación por defecto de la colección.

Para un ejemplo, ver Especificar la intercalación.

writeConcern

Documento

Opcional. Un documento que expresa el nivel de confirmación de escritura para la operación. Omite usar el nivel de confirmación de escritura por defecto.

Cuando se emite en un clúster particionado, mongos convierte el nivel de confirmación de escritura del comando create y su asistente db.createCollection() a "majority".

Control de acceso

Si la implementación aplica autenticación/autorización, db.createCollection() requiere los siguientes privilegios:

Tarea	Privilegios requeridos
Crea una colección no limitada	`createCollection` en la base de datos, o `insert` en la colección a crear
Crear una colección con tamaño fijo	`convertToCapped` para la colección `createCollection` en la base de datos
Crear una vista	`createCollection` en la base de datos. Sin embargo, si el usuario tiene `createCollection` en la base de datos y `find` en la vista que desea crear, el usuario también debe tener los siguientes permisos adicionales: `find` en la colección o vista de origen. `find` en cualquier otra colección o vista referenciada en el `pipeline`, si corresponde.

Un usuario con el rol incorporado readWrite en la base de datos tiene los privilegios necesarios para ejecutar las operaciones enumeradas. O crea un usuario con el rol requerido o concede el rol a un usuario existente.

Comportamiento

Bloqueo de recursos

Cambiado en la versión 4.2.

db.createCollection() obtiene un bloqueo exclusivo en la colección o vista especificada durante la duración de la operación. Todas las operaciones posteriores en la colección deben esperar hasta que db.createCollection() libere el bloqueo. db.createCollection() normalmente mantiene este bloqueo durante un breve período de tiempo.

Crear una vista requiere obtener un bloqueo exclusivo adicional en la colección system.views de la base de datos. Este bloqueo impide la creación o modificación de vistas en la base de datos hasta que el comando se complete.

Antes de MongoDB,4.2 db.createCollection() obtenía un bloqueo exclusivo en la base de datos principal, bloqueando todas las operaciones en la base de datos y todas sus colecciones hasta que se completaba la operación.

Transacciones

Cambiado en la versión 4.4.

Puede crear colecciones e índices dentro de una transacción distribuida si la transacción es No es una transacción de escritura entre fragmentos.

Para usar db.createCollection() en una transacción, la transacción debe usar el nivel de consistencia de lectura "local". Si especificas un nivel de consistencia de lectura distinto de "local", la transacción fallará.

Tip

Crear colecciones e índices en una transacción

Ejemplos

Crea una colección con tamaño fijo

Las colecciones con tamaño fijo tienen un tamaño máximo o un número máximo de documentos que les impiden crecer más allá de los umbrales establecidos. Todas las colecciones con tamaño fijo deben especificar un tamaño máximo y también pueden especificar un número máximo de documentos. MongoDB remueve los documentos más antiguos si una colección alcanza el límite de tamaño máximo antes de alcanzar el número máximo de documentos. Considera el siguiente ejemplo:

db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

Este comando crea una colección llamada log con un tamaño máximo de 5 megabytes y un máximo de 5000 documentos.

Consulta colecciones con tamaño fijo para obtener más información sobre las colecciones con tamaño fijo.

Crear una colección de series de tiempo

Para crear una colección de series de tiempo que capture datos meteorológicos de las últimas 24 horas, ejecuta este comando:

db.createCollection(
    "weather24h",
    {
       timeseries: {
          timeField: "timestamp",
          metaField: "data",
          granularity: "hours"
       },
       expireAfterSeconds: 86400
    }
)

Crear una colección con validación de documentos

Las colecciones con validación comparan cada documento insertado o actualizado con los criterios especificados en la opción validator. Dependiendo del validationLevel y validationAction, MongoDB devuelve una advertencia o se niega a insertar o actualizar el documento si no cumple con los criterios especificados.

El siguiente ejemplo crea una colección contacts con un validador de esquema JSON:

db.createCollection( "contacts", {
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         email: {
            bsonType : "string",
            pattern : "@mongodb\.com$",
            description: "must be a string and match the regular expression pattern"
         },
         status: {
            enum: [ "Unknown", "Incomplete" ],
            description: "can only be one of the enum values"
         }
      }
   } }
} )

Con el validador en su lugar, la siguiente operación de inserción falla la validación:

db.contacts.insertOne( { name: "Amanda", status: "Updated" } )

El método devuelve el error:

Uncaught:
MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("61a8f4847a818411619e952e"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'status',
            description: 'can only be one of the enum values',
            details: [ [Object] ]
          }
        ]
      },
      {
        operatorName: 'required',
        specifiedAs: { required: [ 'phone' ] },
        missingProperties: [ 'phone' ]
      }
    ]
  }
}

Para ver las especificaciones de validación de una colección,db.getCollectionInfos() utilice.

Tip

Especificar la intercalación

Nuevo en la versión 3.4.

La intercalación permite a los usuarios especificar reglas propias del lenguaje para la comparación de strings, como reglas para el uso de mayúsculas y minúsculas y marcas de acento.

Puedes especificar intercalación a nivel de la colección o vista. Por ejemplo, la siguiente operación crea una colección, especificando una intercalación para la colección (Consulta el Documento de intercalación para descripciones de los campos de intercalación):

db.createCollection( "myColl", { collation: { locale: "fr" } } );

Esta intercalación será utilizada por los índices y las operaciones que admiten la intercalación, a menos que especifiquen explícitamente una intercalación diferente. Por ejemplo, inserta los siguientes documentos en myColl:

{ _id: 1, category: "café" }
{ _id: 2, category: "cafe" }
{ _id: 3, category: "cafE" }

La siguiente operación utiliza la intercalación de la colección:

db.myColl.find().sort( { category: 1 } )

La operación devuelve los documentos en el siguiente orden:

{ "_id" : 2, "category" : "cafe" }
{ "_id" : 3, "category" : "cafE" }
{ "_id" : 1, "category" : "café" }

La misma operación en una colección que utiliza intercalación binaria simple (es decir, no se ha establecido una intercalación específica) devuelve documentos en el siguiente orden:

{ "_id" : 3, "category" : "cafE" }
{ "_id" : 2, "category" : "cafe" }
{ "_id" : 1, "category" : "café" }

Tip

Crea una vista con la intercalación por defecto

Especifica las opciones del motor de almacenamiento

Puede especificar opciones de configuración del motor de almacenamiento específicas de la colección al crear una colección db.createCollection() con. Considere la siguiente operación:

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "<option>=<setting>" } } }
)

Esta operación crea una nueva colección denominada users con una string de configuración específica que MongoDB pasará al motor de almacenamiento wiredTiger.

Por ejemplo, para especificar el compresor zlib para bloques de archivos en la colección users, configura la opción block_compressor con el siguiente comando:

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } }
)

Volver

db.commandHelp

db.createView