MongoDB\Database::createCollection()

Definición

MongoDB\Database::createCollection()

Crea explícitamente una colección.

function createCollection(
    string $collectionName,
    array $options = []
): array|object

MongoDB crea colecciones de forma implícita cuando se hace referencia por primera vez a la colección en un comando, como al insertar un documento en una nueva colección. También puedes crear explícitamente una colección con opciones específicas usando el MongoDB\Database::createCollection() método, o utilizando db.createCollection() en la shell de MongoDB.

La creación explícita de colecciones te permite crear colecciones limitadas, especificar criterios de validación de documentos o configurar tu motor de almacenamiento u opciones de indexación.

Parámetros

$collectionName : string

El nombre de la colección que se va a crear.

$options : arreglo

Un arreglo que especifica las opciones deseadas.

Nota

No todas las opciones están disponibles en todas las versiones de MongoDB. Consulta la referencia del comando create en el manual de MongoDB para consideraciones de compatibilidad.

Nombre	Tipo	Descripción
autoIndexId	booleano	Especifica false para desactivar la creación automática de un índice en el campo _id. IMPORTANTE: En sets de réplicas, no establezca autoIndexId en false. Deprecado desde la versión 1.4: Esta opción se depreciada desde MongoDB 3.2. A partir de MongoDB 4.0, esta opción no puede ser false al crear una colección replicada (es decir, una colección fuera de la base de datos local en cualquier modo mongod).
límite máximo	booleano	Para crear una colección con tamaño fijo, especifica true. Si especificas true, también debes establecer un tamaño máximo en la opción size.
changeStreamPreAndPostImages	Documento	Se utiliza para configurar el soporte para preimágenes y postimágenes en flujos de cambios. Consulta la documentación del comando create para obtener más información. Esta opción está disponible desde MongoDB 6.0 y causará una excepción en el momento de la ejecución si se especifica para una versión anterior del servidor. Novedades en la versión 1.13.
clusteredIndex	Documento	Una especificación de índice agrupado. Consulta Collections agrupadas o la documentación del comando crear para más información. Esta opción está disponible desde MongoDB 5.3 y dará lugar a una excepción en tiempo de ejecución si se especifica para una versión de servidor anterior. Novedades en la versión 1.13.
intercalación	arreglo|objeto	Intercalación permite a los usuarios especificar reglas específicas del lenguaje para la comparación de cadenas, tales como reglas para mayúsculas y tildes. Al especificar la intercalación, el campo locale es obligatorio; todos los demás campos de intercalación son opcionales. Para obtener descripciones de los campos, consulte Documento de intercalación.
comment	mixto	Permite a los usuarios especificar un comentario arbitrario para ayudar a rastrear la operación a través del perfilador de bases de datos, la salida actualOp() y registros. Esta opción está disponible desde MongoDB 4.4 y, si se especifica para una versión de servidor anterior, dará lugar a una excepción en tiempo de ejecución. Novedades en la versión 1.13.
encryptedFields	Documento	Un documento que describe campos cifrados para queryable encryption. Si se omite, se consultará la opción encryptedFieldsMap dentro de la opción del controlador autoEncryption. Consulta Cifrado de campo y consultabilidad en el manual de MongoDB para obtener más información. Esta opción está disponible desde MongoDB 7.0 y dará lugar a una excepción en el momento de la ejecución si se especifica para una versión anterior del servidor. Novedades en la versión 1.13.
expireAfterSeconds	entero	Se utiliza para borrar automáticamente documentos en colecciones de series de tiempo. Consulte la documentación del comando create para más información. Esta opción está disponible desde MongoDB 5.0 y se producirá una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor. Nuevo en la versión 1.9.
flags	entero	Disponible para el motor de almacenamiento MMAPv1 solo para establecer las banderas usePowerOf2Sizes y noPadding. La librería proporciona constantes que puedes combinar con un operador OR bit a bit para establecer los valores de los indicadores: MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES: 1 MongoDB\Operation\CreateCollection::NO_PADDING: 2 Se establece por defecto en 1. MongoDB 3.0 y posteriores ignoran la bandera usePowerOf2Sizes. Consulta collMod y db.createCollection() para obtener más información. Obsoleto: Esta opción es obsoleta y se eliminará en la v2.0 Lanzamiento de la librería PHP. Para obtener más información sobre la actualización del motor de almacenamiento MMAPv1 a WiredTiger, consulta la guía Cambiar un autónomo autogestionado a WiredTiger en el manual del servidor.
indexOptionDefaults	arreglo|objeto	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> } Las configuraciones del motor de almacenamiento especificadas al crear índices se validan y se registran en el oplog durante la replicación para admitir sets de réplicas con miembros que usan diferentes motores de almacenamiento.
máximo	entero	El número máximo de documentos permitidos en la colección con tamaño fijo. La opción size tiene prioridad sobre este límite. Si una colección con tamaño fijo alcanza el límite size antes de llegar al número máximo de documentos, MongoDB remueve los documentos antiguos. Si prefieres utilizar el límite max, asegúrate de que el límite size, que es necesario para una colección con tamaño fijo, sea suficiente para contener el número máximo de documentos.
maxTimeMS	entero	El límite de tiempo acumulado en milisegundos para las operaciones de procesamiento en el cursor. MongoDB aborta la operación en el siguiente punto de interrupción..
pipeline	arreglo	Un arreglo que consiste en las etapas del pipeline de agregación, que se aplicarán a la colección o vista especificada por viewOn. Consulta la documentación del comando create para obtener más información. Novedades en la versión 1.13.
sesión	MongoDB\Driver\Session	Sesión de cliente para asociar con la operación. Nueva en la versión 1.3.
Tamaño	entero	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 elimina los documentos más antiguos para hacer espacio para los nuevos documentos. La opción size es requerida para colecciones limitadas y se ignora para otras colecciones.
storageEngine	arreglo|objeto	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> } Las configuraciones del motor de almacenamiento especificadas al crear las colecciones se validan y registran en el oplog durante la replicación para admitir sets de réplicas con nodos que utilicen diferentes motores de almacenamiento.
Series temporales	arreglo|objeto	Un objeto que contiene opciones para crear colecciones de series de tiempo. Consulta la documentación del comando create para conocer las opciones admitidas. Esta opción está disponible desde MongoDB 5.0 y se producirá una excepción en tiempo de ejecución si se especifica para una versión anterior del servidor. Nuevo en la versión 1.9.
typeMap	arreglo	El mapa de tipos que se debe aplicar a los cursores, lo que determina cómo se convierten los documentos BSON en valores PHP. Por defecto, se utiliza el mapa de tipos de la base de datos. Esto se utilizará para el documento de resultado del comando retornado.
validationAction	string	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. validationAction Descripción "error" Por defecto. Los documentos deben pasar la validación antes de que ocurra el guardado. De lo contrario, la operación de escritura falla. "warn" No es necesario que los documentos pasen la validación. Si el documento no pasa la validación, la operación de guardar registra el fallo de validación.
validationLevel	string	Determina con qué rigor MongoDB aplica las reglas de validación a los documentos existentes durante una actualización. validationLevel Descripció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.
validator	arreglo|objeto	Permite a los usuarios especificar reglas de validación o expresiones para la colección. Para obtener más información, consulte validación de documento en el manual de MongoDB. La opción validator toma un arreglo que especifica las reglas o expresiones de validación. Puedes especificar las expresiones utilizando los mismos operadores que los operadores del query de MongoDB, con la excepción de $near, $nearSphere, $text y $where. 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.*.
ver En	string	El nombre de la colección de origen o vista a partir de la cual crear la vista. El nombre no es el namespace completo de la colección o vista (es decir, no incluye el nombre de la base de datos). Las vistas deben crearse en las mismas bases de datos que la colección o vista fuente. Novedades en la versión 1.13.
writeConcern	MongoDB\Driver\WriteConcern	nivel de confirmación de escritura (write concern) a utilizar para la operación. Se utiliza por defecto el nivel de confirmación de escritura (write concern) de la base de datos.

Return Values

Un arreglo u objeto con el documento de resultado del comando crear.

Errores/Excepciones

MongoDB\Exception\UnsupportedException si se usan opciones que no sean compatibles con el servidor seleccionado (p. ej. collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException por errores relacionados con el análisis de parámetros u opciones.

MongoDB\Driver\Exception\RuntimeException para otros errores a nivel de extensión (por ejemplo, " errores de conexión).

Ejemplo

El siguiente ejemplo crea una colección users en la base de datos test con criterios de validación de documentos:

<?php
$db = (new MongoDB\Client)->test;
$result = $db->createCollection('users', [
    'validator' => [
        'username' => ['$type' => 'string'],
        'email' => ['$regex' => '@mongodb\.com$'],
    ],
]);
var_dump($result);

La vista de salida se ilustraría como sigue:

object(MongoDB\Model\BSONDocument)#11 (1) {
  ["storage":"ArrayObject":private]=>
  array(1) {
    ["ok"]=>
    float(1)
  }
}

Ver también

• referencia del comando crear en el manual de MongoDB

• db.createCollection()

• Colecciones de series de tiempo