db.createCollection()

Nesta página

Definição
Compatibilidade
Sintaxe
Controle de acesso
Comportamento
Exemplos

Esta versão da documentação foi arquivada e não é mais suportada. Para atualizar seu sistema do 5.0, consulte osprocedimentos de atualização do MongoDB 6.0 .

Definição

db.createCollection(name, options)

Cria uma nova collection ouvisualização . Para visualizações, consulte também db.createView().

Como o MongoDB cria uma coleção implicitamente quando a coleção é referenciada pela primeira vez em um comando, esse método é usado principalmente para criar novas coleções que usam opções específicas. Por exemplo, use db.createCollection() para criar uma capped collection ou para criar uma nova collection que use validação de documentos.

db.createCollection() é um wrapper em torno do comando de banco de dados create.

Compatibilidade

Esse método está disponível em implantações hospedadas nos seguintes ambientes:

MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem

Observação

Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.

MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB

Sintaxe

O método db.createCollection() tem a seguinte forma de protótipo:

db.createCollection( <name>,
    {
      capped: <boolean>,
      timeseries: {                  // Added in MongoDB 5.0
         timeField: <string>,        // required for time series collections
         metaField: <string>,
         granularity: <string>
      },
      expireAfterSeconds: <number>,
      clusteredIndex: <document>,  // Added in MongoDB 5.3
      changeStreamPreAndPostImages: <document>,  // Added in MongoDB 6.0
      size: <number>,
      max: <number>,
      storageEngine: <document>,
      validator: <document>,
      validationLevel: <string>,
      validationAction: <string>,
      indexOptionDefaults: <document>,
      viewOn: <string>,
      pipeline: <pipeline>,
      collation: <document>,
      writeConcern: <document>
    }
  )

O método db.createCollection() tem os seguintes parâmetros:

Parâmetro	Tipo	Descrição
`name`	string	O nome da collection a ser criada. Consulte Como nomear restrições.
`options`	documento	Opcional. Opções de configuração para criar um: Capped Collection Coleção clusterizada Vista

O documento options contém os seguintes campos:

Campo

Tipo

Descrição

capped

booleano

Opcional. Para criar uma coleção limitada, especifique true. Se você especificar true, também deve definir um tamanho máximo no campo size.

timeseries.timeField

string

Obrigatório ao criar uma coleção de série temporal. O nome do campo que contém a data em cada documento da série temporal. Os documentos em uma coleção de série temporal devem ter uma data BSON válida como valor para o timeField.

timeseries.metaField

string

Opcional. O nome do campo que contém metadados em cada documento de série temporal. Os metadados no campo especificado devem ser dados utilizados para rotular uma série exclusiva de documentos. Os metadados devem mudar raramente ou nunca.

O nome do campo especificado não pode ser _id ou o mesmo que o timeseries.timeField. O campo pode ser de qualquer tipo, exceto array.

timeseries.granularity

string

Opcional, não use se estiver configurando bucketRoundingSeconds e bucketMaxSpanSeconds. Os valores possíveis são seconds (padrão), minutes e hours.

Defina granularity para o valor que melhor corresponde ao tempo entre os registros de data/hora de entrada consecutivos. Isso melhora o desempenho otimizando a forma interna de como o MongoDB armazena dados na coleção.

Para obter mais informações sobre granularidade e intervalos de bucket, consulte Definir granularidade para dados de séries temporais.

expireAfterSeconds

número

Opcional. Especifica os segundos após os quais os documentos em uma coleção de séries temporais expiram. O MongoDB exclui documentos expirados automaticamente.

size

número

Opcional. Especifique um tamanho máximo em bytes para uma coleção limitada. Uma vez que uma coleção limitada atinge seu tamanho máximo, o MongoDB remove os documentos mais antigos para abrir espaço para os novos documentos. O campo size é exigido para coleções limitadas e ignorado para outras coleções.

max

número

Opcional. O número máximo de documentos permitidos na coleção limitada. O limite size tem precedência sobre este limite. Se uma coleção limitada atingir o limite size antes de atingir o número máximo de documentos, o MongoDB removerá os documentos antigos. Se você preferir usar o limite max, certifique-se de que o limite size, que é necessário para uma coleção limitada, seja suficiente para conter o número máximo de documentos.

storageEngine

documento

Opcional. Disponível apenas para o WiredTiger Storage Engine.

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> }

A configuração do mecanismo de armazenamento especificada ao criar coleções é validada e registrada no oplog durante a replicação para dar suporte a conjuntos de réplica com mecanismos de armazenamento diferentes.

Para obter detalhes, consulte Especificar opções do mecanismo de armazenamento.

validator

documento

Opcional. Permite aos usuários especificar regras ou expressões de validação para a coleção.

A opção validator requer um documento que especifica as regras ou expressões de validação. Você pode especificar as expressões usando os mesmos operadores que os operadores de consulta, com exceção de $near, $nearSphere, $text e $where.

Para saber como criar uma collection com validação de esquema, consulte JSON schema.

validationLevel

string

Opcional. Determina quão rigorosamente o MongoDB aplica as regras de validação aos documentos existentes durante uma atualizaçã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.

validationAction

string

Opcional. 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 se aplica somente àqueles documentos determinados pelo site validationLevel.

indexOptionDefaults

documento

Opcional. 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> }

A set do mecanismo de armazenamento especificada na criação de índices é validada e registrada no oplog durante a replicação para oferecer suporte a conjuntos de réplicas com membros que usam mecanismos de armazenamento diferentes.

viewOn

string

O nome da coleção de origem ou visualização a partir da qual criar uma visualização. Para detalhes, consulte db.createView().

pipeline

array

Uma array que consiste no(s) estágio(s) do pipeline de agregação. db.createView() cria uma visualização aplicando o pipeline especificado à coleção ou visualização viewOn. Para detalhes, consulte db.createView().

collation

documento

Especifica a coleção padrão para a coleção.

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

A opção de agrupamento tem a seguinte sintaxe:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

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.

Se você especificar uma ordenação no nível da collection:

Os índices dessa coleção serão criados com esse agrupamento, a menos que a operação de criação de índice especifique explicitamente um agrupamento diferente.
As operações nessa coleção usam o padrão da coleção a menos que eles especifiquem explicitamente um agrupamento diferente.
Você não pode especificar vários agrupamentos para uma operação. Por exemplo, você não pode especificar agrupamentos diferentes por campo ou, se estiver realizando uma busca com uma classificação, não poderá usar um agrupamento para a busca e outro para a classificação.

Se nenhum agrupamento for especificado para a coleção ou para as operações, o MongoDB usa a comparação binária simples usada nas versões anteriores para comparações de strings.

Para uma coleção, você só pode especificar a coleção durante a criação da coleção. Depois de definir, você não poderá modificar o agrupamento da coleção.

Para ver um exemplo, consulte Especificar agrupamento.

writeConcern

documento

Opcional. Um documento que expressa a write concern para a operação. Omitir para usar a função de gravação padrão.

Quando emitido em um cluster fragmentado, omongos converte o preocupação de create gravação do comando e seu assistente db.createCollection() "majority"em.

Controle de acesso

Se a implantação impuser autenticação/autorização, db.createCollection() exigirá os seguintes privilégios:

Tarefa	Privilégios necessários
Crie uma coleção sem limite	`createCollection` no banco de dados, ou `insert` na coleção para criar
Criar uma coleção com limite	`convertToCapped` para a coleção `createCollection` no banco de dados
Criar uma visualização	`createCollection` no banco de dados. No entanto, se o usuário tiver `createCollection` no banco de dados e `find` na visualização a ser criada, ele também deverá ter as seguintes permissões adicionais: `find` na collection ou visualização de origem. `find` em quaisquer outras collections ou visualizações referenciadas no `pipeline`, se houver.

Um usuário com o papel embutido do readWrite no banco de dados tem os privilégios exigidos para executar as operações listadas. Crie um usuário com a função necessária ou conceda a função a um usuário existente.

Comportamento

Bloqueio de recursos

Alterado na versão 4.2.

db.createCollection() obtém um bloqueio exclusivo na coleção ou visualização especificada durante a operação. Todas as operações subsequentes na coleção devem aguardar até que db.createCollection() libere o bloqueio. db.createCollection() normalmente mantém essa trava por um curto período de tempo.

Criar uma visualização exige a obtenção de uma trava exclusiva adicional na collection system.views no banco de dados. Essa trava bloqueia a criação ou modificação de visualizações no banco de dados até que o comando seja concluído.

Antes do MongoDB 4.2, o db.createCollection() obtinha um bloqueio exclusivo no banco de dados principal, bloqueando todas as operações no banco de dados e todas as suas coleções até a operação ser concluída.

Transações

Alterado na versão 4.4.

Você pode criar coleção e indexes dentro de uma transaction distribuída se a transaction não for uma transação de escrita de estilhaço cruzado.

Para usar db.createCollection() em uma transação, a transação deve usar preocupação de leitura "local". Se você especificar um nível de preocupação de leitura diferente de "local", a transação falhará.

Veja também:

Crie coleções e índices em uma transação

Exemplos

Criar uma collection com limite

Coleções limitadas têm tamanho máximo ou contagens de documentos que as impedem de crescer além dos limites máximos. Todas as coleções limitadas devem especificar um tamanho máximo e também podem especificar uma contagem máxima de documentos. O MongoDB remove documentos mais antigos se uma coleção atingir o limite de tamanho máximo antes de ela atingir a contagem máxima de documentos. Considere o seguinte exemplo:

db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

Este comando cria uma coleção chamada log com um tamanho máximo de 5 megabytes e um máximo de 5000 documentos.

Consulte Capped Collections para obter mais informações sobre coleções limitadas.

Crie uma coleção de séries temporais

Para criar uma coleção de séries temporais que capture os dados meteorológicos das últimas 24 horas, emita este comando:

db.createCollection(
    "weather24h",
    {
       timeseries: {
          timeField: "timestamp",
          metaField: "data",
          granularity: "hours"
       },
       expireAfterSeconds: 86400
    }
)

Criar uma collection com validação de documentos

As collections com validação comparam cada documento inserido ou atualizado com os critérios especificados na opção validator . Dependendo de validationLevel e validationAction, o MongoDB retorna um aviso ou se recusa a inserir ou atualizar o documento se ele não atender aos critérios especificados.

O exemplo a seguir cria uma coleção contacts com um validador de JSON schema:

db.createCollection( "contacts", {
   validator: { $jsonSchema: {
      bsonType: "object",
      required: [ "phone" ],
      properties: {
         phone: {
            bsonType: "string",
            description: "must be a string and is required"
         },
         email: {
            bsonType : "string",
            pattern : "@mongodb\.com$",
            description: "must be a string and match the regular expression pattern"
         },
         status: {
            enum: [ "Unknown", "Incomplete" ],
            description: "can only be one of the enum values"
         }
      }
   } }
} )

Com o validador no lugar, a seguinte operação de inserção falha na validação:

db.contacts.insertOne( { name: "Amanda", status: "Updated" } )

O método retorna o erro:

Uncaught:
MongoServerError: Document failed validation
Additional information: {
  failingDocumentId: ObjectId("61a8f4847a818411619e952e"),
  details: {
    operatorName: '$jsonSchema',
    schemaRulesNotSatisfied: [
      {
        operatorName: 'properties',
        propertiesNotSatisfied: [
          {
            propertyName: 'status',
            description: 'can only be one of the enum values',
            details: [ [Object] ]
          }
        ]
      },
      {
        operatorName: 'required',
        specifiedAs: { required: [ 'phone' ] },
        missingProperties: [ 'phone' ]
      }
    ]
  }
}

Para visualizar as especificações de validação de uma collection, use db.getCollectionInfos().

Veja também:

Especifique o agrupamento

Novidade na versão 3.4.

A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para letras maiúsculas e marcas de acento.

Você pode especificar agrupamento no nível da collection ou view. Por exemplo, a operação a seguir cria uma coleção, especificando um agrupamento para a coleção (consulte Documento de Agrupamento para obter descrições dos campos de agrupamento):

db.createCollection( "myColl", { collation: { locale: "fr" } } );

Esse agrupamento será usado por índices e operações que suportam o agrupamento, a menos que especifiquem explicitamente um agrupamento diferente. Por exemplo, insira os seguintes documentos em myColl:

{ _id: 1, category: "café" }
{ _id: 2, category: "cafe" }
{ _id: 3, category: "cafE" }

A operação a seguir usa o agrupamento da coleção:

db.myColl.find().sort( { category: 1 } )

A operação retorna documentos na seguinte ordem:

{ "_id" : 2, "category" : "cafe" }
{ "_id" : 3, "category" : "cafE" }
{ "_id" : 1, "category" : "café" }

A mesma operação em uma coleção que usa agrupamento binário simples (ou seja, nenhum conjunto de coleção específico) retorna documentos na seguinte ordem:

{ "_id" : 3, "category" : "cafE" }
{ "_id" : 2, "category" : "cafe" }
{ "_id" : 1, "category" : "café" }

Veja também:

Crie uma visualização com agrupamento padrão

Especifique as opções do mecanismo de armazenamento

Você pode especificar opções de configuração storage engine específicas da coleção ao criar uma coleção com db.createCollection(). Considere a seguinte operação:

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "<option>=<setting>" } } }
)

Esta operação cria uma nova coleção denominada users com uma string de configuração específica que o MongoDB passará para o mecanismo de armazenamento wiredTiger.

Por exemplo, para especificar o compressor zlib para blocos de arquivo na collection users , defina a opção block_compressor com o seguinte comando:

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } }
)

Voltar

db.commandHelp

db.createView