db.createCollection()
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, você usa
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 dadoscreate
.
Compatibilidade
Você pode utilizar o db.createCollection()
para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem
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:
|
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 | ||||||||||
timeseries.granularity | string | Opcional, não use se estiver configurando Defina 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 documento em uma coleção de time-series 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
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. | ||||||||||
validator | documento | Opcional. Permite aos usuários especificar regras ou expressões de validação para a coleção. A opção 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.
| ||||||||||
validationAction | string | Opcional. Determina se ImportanteA validação de documentos só se aplica aos documentos como determinado pelo | ||||||||||
indexOptionDefaults | documento | Opcional. Permite que os usuários especifiquem uma configuração padrão para índices ao criar uma coleção. A opção
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:
Ao especificar agrupamento, o campo Se você especificar uma ordenação no nível da collection:
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, |
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 |
|
Criar uma coleção com limite |
|
Criar uma visualização |
No entanto, se o usuário tiver |
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á.
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()
.
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é" }
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" } } } )