Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

criar

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamento
  • Controle de acesso
  • Exemplos
create

Cria explicitamente uma collection ou visualização.

Observação

A visualização criada por esse comando não se refere a visualizações materializadas. Para uma discussão sobre visualizações materializadas sob demanda, consulte $merge em vez disso.

Esse comando 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

O comando create tem a seguinte sintaxe:

Observação

O MongoDB 6.3 adiciona os parâmetros bucketMaxSpanSeconds e bucketRoundingSeconds. Para fazer o downgrade para uma versão inferior à 6.3, você deve eliminar todas as collections com esses parâmetros ou modificá-las para usar granularity correspondente, se possível. Para saber mais, consulte collMod.

{
create: <collection or view name>,
capped: <true|false>,
timeseries: {
timeField: <string>,
metaField: <string>,
granularity: <string>
},
expireAfterSeconds: <number>,
autoIndexId: <true|false>,
size: <max_size>,
max: <max_documents>,
storageEngine: <document>,
validator: <document>,
validationLevel: <string>,
validationAction: <string>,
indexOptionDefaults: <document>,
viewOn: <source>,
pipeline: <pipeline>,
collation: <document>,
writeConcern: <document>,
comment: <any>
}

O comando create tem os seguintes campos:

Campo
Tipo
Descrição
create
string
O nome da nova coleção ou visualização. Consulte Como nomear restrições.
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. Os valores possíveis são "seconds" (padrão), "minutes" e "hours". Defina a granularidade para o valor que for a correspondência mais próxima do período entre as medições de entrada consecutivas. Definir o parâmetro granularity com precisão melhora o desempenho otimizando a forma como os dados da time-series collection são armazenados internamente.
expireAfterSeconds
número
Opcional. Ative a exclusão automática de documentos em uma coleção de séries temporais especificando o número de segundos após os quais os documentos expiram. O MongoDB exclui documentos expirados automaticamente.
autoIndexId
booleano

Opcional. Especifique false para desabilitar a criação automática de um índice no campo _id .

Importante

A partir do MongoDB 4.0, você não pode definir a opção autoIndexId como false ao criar collection em reconhecimento de data center diferentes do reconhecimento de data center local .

Descontinuado desde a versão 3.2.

size
inteiro
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
inteiro
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 mais informações, consulte Especificar opções do mecanismo de armazenamento.

validator
documento

Opcional. Permite que os usuários especifiquem regras ou expressões de validação para a collection. Para obter mais informações, consulte Validação de esquema.

Novo na versão 3.2.

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.

  • 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.* .

validationLevel
string

Opcional. Determina quão rigorosamente o MongoDB aplica as regras de validação aos documentos existentes durante uma atualização.

Novo na versão 3.2.

"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.

A validação de documentos só se aplica aos documentos como determinado pelo validationLevel.

"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 falhará.
"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.
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.

Novo na versão 3.2.

viewOn
string

O nome da collection de origem ou visualização a partir da qual criar a visualização. O nome não é o namespace completo da collection ou view; ou seja, não inclui o nome do database e implica o mesmo database da view a ser criada. Você deve criar visualizações no mesmo banco de dados que a collection de origem.

Consulte também db.createView().

Novidade na versão 3.4.

pipeline
array

Uma array que consiste no (s) aggregation pipeline stage(s). create cria a exibição aplicando o pipeline especificado à collection ou exibição viewOn.

A definição de visualização pipeline não pode incluir o estágio $out ou $merge . Se a definição de visualização incluir o pipeline aninhado (por exemplo, a definição de visualização incluir o estágio $lookup ou $facet ), essa restrição também se aplicará aos pipelines aninhados.

A definição da visualização é pública; ou seja, as operações db.getCollectionInfos() e explain na exibição incluirão o pipeline que define a visualização. Dessa forma, evite se referir diretamente a campos e valores confidenciais nas definições de visualização.

Consulte também db.createView().

collation

Especifica o agrupamento padrão para a collection ou visualizaçã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 um modo de exibição, se nenhum agrupamento for especificado, o agrupamento padrão do modo de exibição será o agrupamento de comparação binário "simples". Para uma visualização em uma collection, a visualização não herda as configurações de agrupamento da collection. Para uma visualização em outra exibição, a visualização a ser criada deve especificar as mesmas configurações de agrupamento.

Depois de criar a collection ou a visualização, você não poderá atualizar seu agrupamento padrão.

Para obter um exemplo que especifica o agrupamento padrão durante a criação de uma coleção, consulte Especificar agrupamento.

Novidade na versão 3.4.

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, mongos converte a preocupação de gravação do comando create e seu auxiliar db.createCollection() em "majority".

comment
any

Opcional. Um comentário fornecido pelo usuário para anexar a este comando. Depois de definido, esse comentário aparece junto com os registros desse comando nos seguintes locais:

Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc).

Novidades na versão 4.4.

O método db.createCollection() e o método db.createView() envolvem o comando create .

Alterado na versão 4.2.

create 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 create libere o bloqueio. create 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 create 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.

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 create 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á.

Dica

Veja também:

Alterado na versão 5.0.

Ao utilizar stable API V1, você não pode especificar os seguintes campos em um comando create :

  • autoIndexId

  • capped

  • indexOptionDefaults

  • max

  • size

  • storageEngine

Se a implantação impuser autenticação/autorização, create 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

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.

Para criar uma capped collection. limitada a 64 kilobytes, emita o comando no seguinte formulário:

db.runCommand( { create: "collection", capped: true, size: 64 * 1024 } )

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

Observação

Neste exemplo expireAfterSeconds é especificado como 86400, o que significa que os documentos expiram 86400 segundos após o valor timestamp. Consulte Configurar Remoção Automática para Coleções de Séries Temporais (TTL).

Observação

A visualização criada por esse comando não se refere a visualizações materializadas. Para discussão de visualizações materializadas on-demand, consulte $merge em vez disso.

Alterado na versão 4.2.

A definição de visualização pipeline não pode incluir o estágio $out ou $merge . Se a definição de visualização incluir o pipeline aninhado (por exemplo, a definição de visualização incluir o estágio $lookup ou $facet ), essa restrição também se aplicará aos pipelines aninhados.

Para criar uma visualização utilizando o comando create , utilize a seguinte sintaxe:

db.runCommand( { create: <view>, viewOn: <source>, pipeline: <pipeline> } )

ou se estiver especificando um agrupamento:

db.runCommand( { create: <view>, viewOn: <source>, pipeline: <pipeline>, collation: <collation> } )

Por exemplo, criar uma coleção survey com os seguintes documentos:

db.survey.insertMany(
[
{ _id: 1, empNumber: "abc123", feedback: { management: 3, environment: 3 }, department: "A" },
{ _id: 2, empNumber: "xyz987", feedback: { management: 2, environment: 3 }, department: "B" },
{ _id: 3, empNumber: "ijk555", feedback: { management: 3, environment: 4 }, department: "A" }
]
)

A seguinte operação cria uma visualização do managementRatings com os campos _id, feedback.management e department:

db.runCommand ( {
create: "managementFeedback",
viewOn: "survey",
pipeline: [ { $project: { "management": "$feedback.management", department: 1 } } ]
} )

Importante

A definição da visualização é pública; ou seja, as operações db.getCollectionInfos() e explain na exibição incluirão o pipeline que define a visualização. Dessa forma, evite se referir diretamente a campos e valores confidenciais nas definições de visualização.

Dica

Veja também:

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.runCommand ( {
create: "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é" }

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

db.runCommand( {
create: "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. Consulte a documentação do WiredTiger sobre opções de nível de coleção para obter opções específicas a respeito do campo wiredTiger.

Voltar

convertToCapped