MongoDB\Database::createCollection()

定义

MongoDB\Database::createCollection()

显式创建一个集合。

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

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

显式创建集合使您能够创建 固定集合，指定 文档验证标准，或配置存储引擎或索引选项。

参数

$collectionName : string

要创建的集合名称。

$options : array

指定所需选项的数组。

注意

并非所有选项都在MongoDB的所有版本中可用。有关兼容性考虑，请参阅MongoDB手册中的create命令参考。

名称	类型	描述
autoIndexId	布尔值	指定false以禁用在_id字段上自动创建索引。 重要：对于副本集，不要将autoIndexId设置为false。 已弃用自版本1.4: 此选项自MongoDB 3.2版本起已弃用。截至MongoDB 4.0，当创建复制的集合（即任何mongod模式下位于local数据库之外的集合）时，此选项不能为false。
capped	布尔值	要创建一个固定集合，指定true。如果您指定true，则必须在size选项中设置最大大小。
changeStreamPreAndPostImages	文档	用于配置对更改流中前图像和后图像的支持。有关更多信息，请参阅create命令文档。 此选项自MongoDB 6.0版本起可用，如果指定用于旧服务器版本，则在执行时将引发异常。 新功能自版本1.13.
clusteredIndex	文档	聚类索引规范。请参阅聚类集合或create命令文档以获取更多信息。 此选项自MongoDB 5.3版本起可用，如果指定用于旧服务器版本，则在执行时将引发异常。 新功能自版本1.13.
collation	数组|对象	排序规则允许用户指定字符串比较的语言特定规则，例如字母大小写和重音符号的规则。指定排序规则时，locale字段是必需的；所有其他排序规则字段都是可选的。有关字段的描述，请参阅排序规则文档。
comment	混合	允许用户指定任意注释，以帮助通过数据库分析器、当前操作输出和日志。 此选项自MongoDB 4.4版开始可用，如果用于较旧的服务器版本，则在执行时将引发异常。 新功能自版本1.13.
encryptedFields	文档	描述可查询加密中加密字段的文档。如果省略，则将咨询autoEncryption驱动选项内的encryptedFieldsMap选项。有关更多信息，请参阅MongoDB手册中的字段加密和可查询性。 此选项自MongoDB 7.0版开始可用，如果用于较旧的服务器版本，则在执行时将引发异常。 新功能自版本1.13.
expireAfterSeconds	整数	用于自动删除时序集合中的文档。有关更多信息，请参阅create命令文档。 此选项自MongoDB 5.0版开始可用，如果用于较旧的服务器版本，则在执行时将引发异常。 新功能自版本1.9.
flags	整数	仅适用于MMAPv1存储引擎，用于设置usePowerOf2Sizes和noPadding标志。 库提供了一些常量，您可以将它们与位或运算符结合使用来设置标志值 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> } 创建索引时指定的存储引擎配置将在复制期间验证并记录到oplog，以支持使用不同存储引擎的副本集成员。
max	整数	允许在限制集合中存储的最大文档数量。当size选项值大于此限制时，将优先使用该值。如果限制集合在达到最大文档数量之前先达到size限制，MongoDB会删除旧文档。如果您希望使用max限制，请确保size限制（对于限制集合是必需的）足以容纳最大数量的文档。
maxTimeMS	整数	游标上处理操作的累计时间限制（毫秒）。MongoDB将在最早的下一个中断点处终止操作。
pipeline	数组	一个数组，包含要应用于由viewOn指定的集合或视图的聚合管道阶段。有关更多信息，请参阅创建命令文档。 新功能自版本1.13.
session	MongoDB\Driver\Session	与操作关联的客户端会话。 新功能自版本1.3.
size	整数	指定限制集合的最大字节数。一旦限制集合达到其最大大小，MongoDB将删除旧文档以为新文档腾出空间。对于限制集合，必须指定size选项，对于其他集合则忽略该选项。
storageEngine	数组|对象	仅适用于WiredTiger存储引擎。 在创建集合时，允许用户根据集合指定存储引擎的配置。选项storageEngine的值应采用以下形式 { <storage-engine-name>: <options> } 在创建集合时指定的存储引擎配置将在复制过程中验证并记录到操作日志中，以支持使用不同存储引擎的副本集成员。
timeseries	数组|对象	包含创建时间序列集合选项的对象。有关支持的选项，请参阅创建命令文档。 此选项自MongoDB 5.0版开始可用，如果用于较旧的服务器版本，则在执行时将引发异常。 新功能自版本1.9.
typeMap	数组	应用于游标的类型映射，它决定了BSON文档如何转换为PHP值。默认为数据库的类型映射。 这将用于返回的命令结果文档。
validationAction	字符串	确定是否在无效文档上引发错误或只是警告违规情况，但允许插入无效文档。 重要：文档验证仅适用于由validationLevel确定的那些文档。 validationAction 描述 "error" 默认值。在写入发生之前，文档必须通过验证。否则，写入操作失败。 "warn" 文档不需要通过验证。如果文档验证失败，则写入操作将记录验证失败。
validationLevel	字符串	确定MongoDB在更新现有文档时如何严格地应用验证规则。 validationLevel 描述 "关闭" 不进行插入或更新的验证。 "严格" 默认。对所有插入和所有更新应用验证规则。 "适度" 对插入和现有有效文档的更新应用验证规则。不对现有无效文档的更新应用规则。
验证器	数组|对象	允许用户指定验证规则或表达式。有关更多信息，请参阅MongoDB手册中的文档验证。 validator选项接受一个数组，指定验证规则或表达式。您可以使用与MongoDB的查询运算符相同的运算符指定表达式，但除外$near、$nearSphere、$text和$where。 验证发生在更新和插入过程中。现有文档在修改之前不进行验证检查。 您不能为admin、local和config数据库中的集合指定验证器。 您不能为system.*集合指定验证器。
viewOn	字符串	创建视图时要使用的源集合或视图的名称。 该名称不是集合或视图的完整命名空间（即它不包含数据库名称）。视图必须在与源集合或视图相同的数据库中创建。 新功能自版本1.13.
writeConcern	MongoDB\Driver\WriteConcern	用于操作的写入关注点。默认为数据库的写入关注点。

返回值

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

错误/异常

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

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

MongoDB\Driver\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)
  }
}

另请参阅

• create 命令参考 MongoDB 手册

• db.createCollection()

• 时间序列集合