MongoDB\Database::createCollection()

定义

MongoDB\Database::createCollection()

显式创建collection。

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

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

指定所需选项的数组。

注意

Not all options are available on all versions of MongoDB. Refer to the create command reference in the MongoDB manual for compatibility considerations.

名称	类型	说明
autoIndexId	布尔	指定false可禁用在_id字段上自动创建索引的功能。 重要提示：对于副本集，请勿将autoIndexId 设立为false 。 自版本 1.4 起已弃用：自 MongoDB 3.2 起，此选项已弃用。从 MongoDB 4.0 开始，在创建副本集集合时（即在任何 mongod 模式下，集合位于 local 数据库之外），此选项无法 false。
固定大小	布尔	要创建固定大小集合，请指定true 。 如果指定true ，则还必须在size选项中设置最大大小。
changeStreamPreAndPostImages	文档	Used to configure support for pre- and post-images in change streams. See the create command documentation for more information. 此选项从 MongoDB 6.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.13版本新增。
聚集索引	文档	A clustered index specification. See Clustered Collections or the create command documentation for more information. 此选项从 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版本新增。
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() 。 Deprecated: This option is deprecated and will be removed in the v2.0 PHP library release. To learn more about upgrading from the MMAPv1 storage engine to Wired Tiger, see the Change a Self-Managed Standalone to WiredTiger guide in the Server manual.
indexOptionDefaults	数组|对象	允许用户在创建集合时指定索引的默认配置。 indexOptionDefaults 选项接受 storageEngine 文档，该文档应采用以下形式： { <storage-engine-name>: <options> } 创建索引时指定的storage engine配置在复制期间进行验证并记录到oplog中，以支持具有使用不同存储引擎的成员的副本集。
Max	整型	固定大小集合中允许的最大文档数。 size选项优先于此限制。 如果固定大小集合在达到最大文档数之前达到size限制，MongoDB 将删除旧文档。 如果您希望使用max限制，请确保collection所需的size限制足以包含最大数量的文档。
maxTimeMS	整型	The cumulative time limit in milliseconds for processing operations on the cursor. MongoDB aborts the operation at the earliest following interrupt point.
管道	阵列	由聚合管道阶段组成的数组，将应用于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中，以支持具有使用不同存储引擎的成员的副本集。
时间序列	数组|对象	An object containing options for creating time series collections. See the create command documentation for supported options. 此选项从 MongoDB 5.0 开始可用，如果为较旧的服务器版本指定，将导致执行时出现异常。 1.9版本新增。
typeMap	阵列	应用游标的类型映射，决定如何将BSON文档转换为PHP值。默认为数据库的类型映射。 这将用于返回的命令结果文档。
validationAction	字符串	确定是对无效文档执行error ，还是仅对违规行为warn ，但允许插入无效文档。 重要提示：文档验证仅适用于由 validationLevel 确定的文档。 validationAction 说明 "error" 默认。 文档必须在写入之前通过验证。 否则，写入操作将失败。 "warn" 文档不必通过验证。如果文档未通过验证，则写入操作将记录验证失败。
validationLevel	字符串	确定 MongoDB 在更新期间将验证规则应用于现有文档的严格程度。 validationLevel 说明 "off" 不对插入或更新进行验证。 "strict" 默认。 将验证规则应用于所有插入和所有更新。 "moderate" 将验证规则应用于现有有效文档的插入和更新。请勿将规则应用于现有无效文档的更新。
验证器	数组|对象	Allows users to specify validation rules or expressions for the collection. For more information, see Document Validation in the MongoDB manual. 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	Write concern to use for the operation. Defaults to the database's write concern.

Return Values

An array or object with the result document of the create command.

错误/异常

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()

• 时间序列集合