MongoDB\Database::createCollection()

Definição

MongoDB\Database::createCollection()

Cria explicitamente uma collection.

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

O MongoDB cria coleções implicitamente quando você faz referência à coleção pela primeira vez em um comando, como ao inserir um documento em uma nova coleção. Você também pode criar explicitamente uma coleção com opções específicas usando o método MongoDB\Database::createCollection() ou usando db.createCollection() no shell do MongoDB.

A criação explícita de collections permite que você crie capped collections, especifique critérios de validação de documentos ou configure seu storage engine ou opções de indexação.

Parâmetros

$collectionName : string

O nome da coleção a ser criada.

$options : array

Uma array especificando as opções desejadas.

Observação

Nem todas as opções estão disponíveis em todas as versões do MongoDB. Consulte a referência de comando de criação no manual do MongoDB para obter considerações de compatibilidade.

Nome	Tipo	Descrição
autoIndexId	booleano	Especifique false para desabilitar a criação automática de um índice no campo _id . Importante Para conjuntos de réplicas, não defina autoIndexId como false. Descontinuado desde a versão 1.4: Esta opção foi descontinuada desde o MongoDB 3.2. A partir do MongoDB 4.0, essa opção não pode ser false ao criar uma coleção replicada (ou seja, uma coleção fora do banco de dados local em qualquer modo mongod).
capped	booleano	Para criar uma collection limitada, especifique true. Se você especificar true , também deve definir um tamanho máximo na opção size .
changeStreamPreAndPostImages	documento	Usado para configurar o suporte para pré e pós-imagens em change streams. Consulte a documentação do comando de criação para obter mais informações. Esta opção está disponível a partir do MongoDB 6.0 e resultará em uma exceção no tempo de execução se especificada para uma versão de servidor mais antiga. Novidade na versão 1.13.
Índices Agrupado	documento	Uma especificação de índice agrupado. Consulte Clustered Collections ou a documentação do comando create para obter mais informações. Esta opção está disponível a partir do MongoDB 5.3 e resultará em uma exceção no tempo de execução se especificada para uma versão de servidor mais antiga. Novidade na versão 1.13.
agrupamento	array|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. Esta opção está disponível desde o MongoDB 4.4 e resultará em uma exceção no momento da execução se for especificada para uma versão mais antiga do servidor. Novidade na versão 1.13.
Campos criptografados	documento	Documento que descreve campos criptografados para Queryable Encryption. Se omitida, a opção encryptedFieldsMap dentro da opção de driver autoEncryption será consultada. Consulte Criptografia de campo e consultabilidade no manual do MongoDB para obter mais informações. Esta opção está disponível a partir do MongoDB 7.0 e resultará em uma exceção no tempo de execução se especificada para uma versão de servidor mais antiga. Novidade na versão 1.13.
expireAfterSeconds	inteiro	Usado para excluir automaticamente documentos em coleções de séries temporais. Consulte a documentação do comando de criação para obter mais informações. Esta opção está disponível a partir do MongoDB 5.0 e resultará em uma exceção no tempo de execução se especificada para uma versão de servidor mais antiga. Novidades na versão 1.9.
flags	inteiro	Disponível apenas para o storage engine MMAPv1 para definir os sinalizadores usePowerOf2Sizes e noPadding . A biblioteca fornece constantes que você pode combinar com um operador bitwise OR para definir os valores do sinalizador: MongoDB\Operation\CreateCollection::USE_POWER_OF_2_SIZES: 1 MongoDB\Operation\CreateCollection::NO_PADDING: 2 Padrão é 1. O MongoDB 3.0 e posterior ignora o sinalizador usePowerOf2Sizes . Consulte collMod e db.createCollection() para obter mais informações.
indexOptionDefaults	array|object	Permite que os usuários especifiquem uma configuração padrão para índices ao criar uma coleção. A opção indexOptionDefaults aceita um documento storageEngine, que deve receber o seguinte formulário: { <storage-engine-name>: <options> } as configurações storage engine especificadas ao criar índices são validadas e registradas no oplog durante a replicação para suportar conjuntos de réplicas com membros que usam mecanismos de armazenamento diferentes.
max	inteiro	The maximum number of documents allowed in the capped collection. A opção size tem precedência sobre este limite. If a capped collection reaches the size limit before it reaches the maximum number of documents, MongoDB removes old documents. Se você preferir usar o limite max , certifique-se de que o limite size , que é necessário para uma collection limitada, seja suficiente para conter o número máximo de documento.
maxTimeMS	inteiro	O limite de tempo cumulativo em milésimos de segundo para operações de processamento no cursor. O MongoDB aborta a operação o mais cedo possível após o ponto de interrupção.
gasoduto	array	Uma array que consiste nos estágios de pipeline de agregação, que serão aplicados à coleção ou visualização especificada por viewOn. Consulte a documentação do comando de criação para obter mais informações. Novidade na versão 1.13.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
Tamanho	inteiro	Especifique um tamanho máximo em bytes para uma collection limitada. Uma vez que uma collection limitada atinge seu tamanho máximo, o MongoDB remove os documento mais antigos para abrir espaço para os novos documento. A opção size é necessária para collection limitada e ignorada para outras collection.
storageEngine	array|object	Disponível apenas para o mecanismo de armazenamento WiredTiger. Permite que os usuários especifiquem a configuração para o mecanismo de armazenamento em uma base por coleção ao criar uma coleção. O valor da opção storageEngine deve ter o seguinte formato: { <storage-engine-name>: <options> } as configurações storage engine especificadas ao criar coleções são validadas e registradas no oplog durante a replicação para suportar conjuntos de réplica com membros que usam mecanismos de armazenamento diferentes.
Time series	array|object	Um objeto que contém opções para criar coleções de séries temporais. Consulte a documentação de criação de comando para ver as opções suportadas. Esta opção está disponível a partir do MongoDB 5.0 e resultará em uma exceção no tempo de execução se especificada para uma versão de servidor mais antiga. Novidades na versão 1.9.
typeMap	array	O mapa de tipos aplicar aos cursores, o que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos do banco de dados. Isso será usado para o documento de resultado do comando retornado.
Ação de validação	string	Determina se error em documentos inválidos ou apenas warn sobre as violações, mas permite que documentos inválidos sejam inseridos. Importante A validação de documentos só se aplica aos documentos como determinado pelo validationLevel. validationAction Descrição "error" Padrão. Os documentos devem passar por validação antes que a gravação ocorra. Caso contrário, a operação de gravação falha. "warn" Os documentos não precisam passar pela validação. Se o documento falhar na validação, a operação de gravação registrará a falha na validação.
nível de validação	string	Determina quão rigorosamente o MongoDB aplica as regras de validação aos documentos existentes durante uma atualização. validationLevel Descrição "off" Nenhuma validação para inserções ou atualizações. "strict" Padrão. Aplique regras de validação a todas as inserções e todas as atualizações. "moderate" Aplique regras de validação a inserções e atualizações em documentos válidos existentes. Não aplique regras a atualizações em documentos inválidos existentes.
validador	array|object	Permite aos usuários especificar regras ou expressões de validação para a coleção. Para obter mais informações, consulte Validação de documentos no manual do MongoDB. A opção validator usa uma array que especifica as regras ou expressões de validação. Você pode especificar as expressões utilizando os mesmos operadores que os operadores de consulta do MongoDB com exceção de $near, $nearSphere, $text e $where. A validação ocorre durante atualizações e inserções. Os documentos existentes não passam por verificações de validação até a modificação. Você não pode especificar um validador para collections nos bancos de dados admin, local e config. Você não pode especificar um validador para collections system.* .
viewOn	string	O nome da coleção de origem ou visualização a partir da qual criar a visualização. O nome não é o namespace completo da collection ou visualização (ou seja, não inclui o nome do reconhecimento de data center). As visualizações devem ser criadas no mesmo reconhecimento de data center que a collection ou visualização de origem. Novidade na versão 1.13.
writeConcern	MongoDB\Driver\WriteConcern	Write concern a ser usada para a operação. O padrão é a preocupação de gravação do banco de dados.

Return Values

Um array ou objeto com o documento de resultado do comando de criação .

Erros/exceções

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Exemplo

O exemplo a seguir cria uma collection users no reconhecimento de data center test com critérios de validação do documento:

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

A saída seria então semelhante a:

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

Veja também

• criar referência de comando no manual do MongoDB

• db.createCollection()

• Coleções de Time Series