MongoDB\Database::createCollection()

定义

MongoDB\Database::createCollection()

显式创建collection。

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

MongoDB creates collections implicitly when you first reference the collection in a command, such as when inserting a document into a new collection. You may also explicitly create a collection with specific options using the MongoDB\Database::createCollection() method, or using db.createCollection() in the MongoDB shell.

通过显式创建集合，您可以创建固定大小集合、指定文档验证条件或配置storage engine或索引选项。

参数

$collectionName ： 细绳

要创建的collection的名称。

$options : array

指定所需选项的数组。

注意

并非所有选项在所有版本的 MongoDB 上都可用。 有关兼容性注意事项，请参阅 MongoDB 手册中的创建命令参考。

名称	类型	说明
固定大小	布尔	要创建固定大小集合，请指定true 。 如果指定true ，则还必须在size选项中设置最大大小。
changeStreamPreAndPostImages	文档	用于配置对 变更流 中的前映像和后映像的支持。 有关更多信息，请参阅创建命令文档。 此选项从 MongoDB 6.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13版本新增。
聚集索引	文档	集群索引规范。 有关更多信息，请参阅集群化集合或创建命令文档。 此选项从 MongoDB 5.3 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13版本新增。
排序规则	数组|对象	Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。 自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13版本新增。
加密字段	文档	描述可查询加密的Queryable Encryption字段的文档。 如果省略，则会查阅autoEncryption驱动程序选项中的encryptedFieldsMap选项。 有关更多信息，请参阅 MongoDB 手册中的字段加密和可查询性。 此选项从 MongoDB 7.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13版本新增。
expireAfterSeconds	整型	用于自动删除时间序列集合中的文档。 有关更多信息，请参阅创建命令文档。 此选项从 MongoDB 5.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.9版本新增。
indexOptionDefaults	数组|对象	允许用户在创建集合时指定索引的默认配置。 indexOptionDefaults 选项接受 storageEngine 文档，该文档应采用以下形式： { <storage-engine-name>: <options> } 创建索引时指定的storage engine配置在复制期间进行验证并记录到oplog中，以支持具有使用不同存储引擎的成员的副本集。
Max	整型	固定大小集合中允许的最大文档数。 size选项优先于此限制。 如果固定大小集合在达到最大文档数之前达到size限制，MongoDB 将删除旧文档。 如果您希望使用max限制，请确保collection所需的size限制足以包含最大数量的文档。
maxTimeMS	整型	在游标上处理操作的累计时间限制（以毫秒为单位）。MongoDB 最早会在中断点之后中止操作。
管道	阵列	由聚合管道阶段组成的数组，将应用于viewOn指定的集合或视图。 有关更多信息，请参阅创建命令文档。 1.13版本新增。
会话	MongoDB\Driver\Session	与操作相关联的客户端会话。 1.3版本新增。
size	整型	指定固定大小集合的最大大小（以字节为单位）。Once a capped collection reaches its maximum size, MongoDB removes the older documents to make space for the new documents. size选项对于固定大小集合是必需的，对于其他集合则被忽略。
引擎加密	数组|对象	仅适用于 WiredTiger 存储引擎。 允许用户在创建集合时针对每个集合指定存储引擎的配置。storageEngine 选项的值应采用以下形式： { <storage-engine-name>: <options> } 创建集合时指定的storage engine配置在复制期间进行验证并记录到oplog中，以支持具有使用不同存储引擎的成员的副本集。
时间序列	数组|对象	包含用于创建时间序列集合的选项的对象。 有关支持的选项，请参阅创建命令文档。 此选项从 MongoDB 5.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.9版本新增。
typeMap	阵列	应用游标的类型映射，决定如何将BSON文档转换为PHP值。默认为数据库的类型映射。 这将用于返回的命令结果文档。
validationAction	字符串	确定是对无效文档执行error ，还是仅对违规行为warn ，但允许插入无效文档。 重要提示：文档验证仅适用于由 validationLevel 确定的文档。 validationAction 说明 "error" 默认。 文档必须在写入之前通过验证。 否则，写入操作将失败。 "warn" 文档不必通过验证。如果文档未通过验证，则写入操作将记录验证失败。
validationLevel	字符串	确定 MongoDB 在更新期间将验证规则应用于现有文档的严格程度。 validationLevel 说明 "off" 不对插入或更新进行验证。 "strict" 默认。 将验证规则应用于所有插入和所有更新。 "moderate" 将验证规则应用于现有有效文档的插入和更新。请勿将规则应用于现有无效文档的更新。
验证器	数组|对象	允许用户为集合指定验证规则或表达式。 有关更多信息，请参阅 MongoDB 手册中的文档验证。 The validator option takes an array that specifies the validation rules or expressions. You can specify the expressions using the same operators as MongoDB's query operators with the exception of $near, $nearSphere, $text, and $where. 更新和插入期间进行验证。现有文档在修改之前不会进行验证检查。 不能为 admin、local 和 config 数据库中的集合指定验证器。 无法为 system.* 集合指定验证器。
viewOn	字符串	要从中创建视图的源集合或视图的名称。 该名称不是collection或视图的完整命名空间（即不包括数据库名称）。视图必须在与源collection或视图相同的数据库中创建。 1.13版本新增。
writeConcern	MongoDB\Driver\WriteConcern	写入用于操作的关注。 默认为数据库的写关注。

错误/异常

MongoDB\Exception\UnsupportedException，如果所选服务器使用了选项但不支持选项（例如collation、readConcern、writeConcern）。

MongoDB\Exception\InvalidArgumentException 用于与参数或选项解析相关的错误。

MongoDB\ 驱动程序\Exception\RuntimeException 用于扩展级别的其他错误（例如连接错误）。

例子

以下示例使用文档验证条件在test数据库中创建users集合：

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

另请参阅

• MongoDB 手册中的create命令引用

• db.createCollection()

• 时间序列集合