MongoDB\Database::createCollection()

定义

MongoDB\Database::createCollection()

显式创建collection。

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

当您首次在命令中引用集合时，例如将文档插入到新集合中时，MongoDB 会隐式创建集合。 您还可以使用MongoDB\Database::createCollection() 方法或在 中使用 db.createCollection() 来显式创建具有特定选项的集合。MongoDBshell

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

参数

$collectionName ： 细绳

要创建的collection的名称。

$options : array

指定所需选项的数组。

注意

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

名称	类型	说明
autoIndexId	布尔	指定false可禁用在_id字段上自动创建索引的功能。 重要提示：对于副本集，请勿设立autoIndexId 设置为false 。 自 1.4 版起已弃用： 自 MongoDB 3.2 起已弃用此选项。 从 MongoDB 4.0 开始，在创建复制集合（即任何 mongod 模式下位于local数据库之外的集合）时，此选项不能为false 。
固定大小	布尔	要创建固定大小集合，请指定true 。 如果指定true ，则还必须在size选项中设置最大大小。
changeStreamPreAndPostImages	文档	用于配置对 变更流 中的前映像和后映像的支持。 有关更多信息，请参阅创建命令文档。 此选项从 MongoDB 6.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13 版本中的新增功能。
聚集索引	文档	集群索引规范。 有关更多信息，请参阅集群化集合或创建命令文档。 此选项从 MongoDB 5.3 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13 版本中的新增功能。
排序规则	数组|对象	排序规则允许用户为string比较指定特定于语言的规则，例如字母大小写和重音符号规则。 指定排序规则时， locale字段为必填字段；所有其他排序规则字段都是可选的。 有关字段的说明，请参阅排序规则文档。
comment	混合	使用户可以指定任意注释来帮助通过数据库分析器、currentOp 输出和日志来跟踪操作。 自 MongoDB 4.4 起此选项可用，如果为旧服务器版本指定，则会在执行时导致异常。 1.13 版本中的新增功能。
加密字段	文档	描述可查询加密的Queryable Encryption字段的文档。 如果省略，则会查阅autoEncryption驱动程序选项中的encryptedFieldsMap选项。 有关更多信息，请参阅 MongoDB 手册中的字段加密和可查询性。 此选项从 MongoDB 7.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13 版本中的新增功能。
expireAfterSeconds	整型	用于自动删除时间序列集合中的文档。 有关更多信息，请参阅创建命令文档。 此选项从 MongoDB 5.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.9 版本中的新功能。
flags	整型	仅适用于 MMAPv1 storage engine，用于设置usePowerOf2Sizes和noPadding标志。 该库提供了常量，您可以将这些常量与 按位 OR 运算符 结合使用 设置标志值： MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES: 1 MongoDB\Operation\CreateCollection::NO_PADDING: 2 默认值为 1。 MongoDB 3.0及更高版本忽略usePowerOf2Sizes标志。 有关更多信息，请参阅collMod和db.createCollection() 。
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 手册中的文档验证。 validator选项采用一个指定验证规则或表达式的数组。 您可以使用与 MongoDB查询操作符相同的操作符指定表达式，但$near 、 $nearSphere 、 $text和$where除外。 更新和插入期间进行验证。现有文档在修改之前不会进行验证检查。 不能为 admin、local 和 config 数据库中的集合指定验证器。 无法为 system.* 集合指定验证器。
viewOn	字符串	要从中创建视图的源集合或视图的名称。 该名称不是collection或视图的完整命名空间（即不包括数据库名称）。视图必须在与源collection或视图相同的数据库中创建。 1.13 版本中的新增功能。
writeConcern	MongoDB\Driver\WriteConcern	写入用于操作的关注。 默认为数据库的写关注。

Return Values

包含创建命令的结果文档的数组或对象。

错误/异常

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

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

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

例子

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

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

而输出将类似如下所示：

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

另请参阅

• MongoDB 手册中的create命令引用

• db.createCollection()

• 时间序列集合