inserir

Nesta página

Definição

Sintaxe
Campos de comando
Comportamento
Exemplos
Saída

Definição

insert

O comando insert insere um ou mais documentos e retorna um documento contendo o status de todas as inserções. Os métodos de inserção fornecidos pelos drivers do MongoDB usam esse comando internamente.

Dica

No mongosh, este comando também pode ser executado através dos métodos de ajuda do db.collection.insertOne() e db.collection.insertMany() .

Os métodos auxiliares são práticos para os usuários mongosh, mas podem não retornar o mesmo nível de informações que os comandos do banco de dados. Nos casos em que a praticidade não for necessária ou os campos de retorno adicionais forem necessários, use o comando de banco de dados.

Retorna:	Um documento que contém o status da operação. Consulte Saída para detalhes.

Sintaxe

O comando tem a seguinte sintaxe:

db.runCommand(
   {
      insert: <collection>,
      documents: [ <document>, <document>, <document>, ... ],
      ordered: <boolean>,
      maxTimeMS: <integer>,
      writeConcern: { <write concern> },
      bypassDocumentValidation: <boolean>,
      comment: <any>
   }
)

Campos de comando

O comando utiliza os seguintes campos:

Campo	Tipo	Descrição
`insert`	string	O nome da coleção de destino.
`documents`	array	Uma matriz de um ou mais documentos para inserir na coleção designada.
`ordered`	booleano	Opcional. Se `true`, quando a inserção de um documento falhar, retorne sem inserir nenhum documento restante listado na matriz `inserts`. Se `false`, quando a inserção de um documento falhar, continue inserindo os documentos restantes. O padrão é `true`.
`maxTimeMS`	número inteiro não negativo	Opcional. Especifica um limite de tempo em milissegundos. Se você não especificar um valor para `maxTimeMS`, as operações não atingirão o tempo limite. Um valor `0` especifica explicitamente o comportamento ilimitado padrão. O MongoDB encerra as operações que excedem o limite de tempo alocado usando o mesmo mecanismo de `db.killOp()`. O MongoDB só encerra uma operação em um de seus pontos de interrupção designados.
`writeConcern`	documento	Opcional. Um documento que expressa a preocupação de gravação do comando `insert`. Omitir para usar a preocupação de gravação padrão. Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.
`bypassDocumentValidation`	booleano	Opcional. Permite que o `insert` ignore a validação do documento durante a operação. Isso permite inserir documentos que não atendam aos requisitos de validação.
`comment`	qualquer	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: mensagens de log do mongod, no campo `attr.command.cursor.comment`. Saída do perfil do banco de dados, no campo `command.comment`. Saída de `currentOp`, no campo `command.comment`. Um comentário pode ser qualquer tipo BSON válido (string, inteiro, objeto, array etc).

Comportamento

Limite de tamanho

O tamanho total de todos os documents elementos da matriz deve ser menor ou igual ao tamanho máximo do documento BSON.

O número total de documentos na array documents deve ser menor ou igual ao tamanho máximo do volume.

Validação do documento

O comando insert traz suporte para a opção bypassDocumentValidation, que permite ignorar a validação do documento ao inserir ou atualizar documentos em uma coleção com regras de validação.

Transações

insert pode ser usado dentro de transações distribuídas.

Importante

Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.

Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.

Criação de collections em transações

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.

Se você especificar uma inserção em uma collection não existente em uma transação, o MongoDB criará a collection implicitamente.

Dica

Veja também:

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

Write concerns e transações

Não defina explicitamente a preocupação de gravação para a operação se for executada em uma transação. Para usar write concern com transações, consulte Transações e write concern.

Inserir Imprecisões

Mesmo que você encontre um erro de servidor durante uma inserção, alguns documentos podem ter sido inseridos.

Após uma inserção bem-sucedida, o sistema retorna insert.n, o número de documentos inseridos na coleção. Se a operação de inserção for interrompida por uma alteração no estado do conjunto de réplicas, o sistema poderá continuar inserindo documentos. Como resultado, insert.n pode relatar menos documentos do que os realmente inseridos.

Exemplos

Inserir um único documento

Inserir um documento na coleção users:

db.runCommand(
   {
      insert: "users",
      documents: [ { _id: 1, user: "abc123", status: "A" } ]
   }
)

O documento que retornou mostra que o comando inseriu com sucesso um documento. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 1 }

Inserção em massa

Insira três documentos na coleção users:

db.runCommand(
   {
      insert: "users",
      documents: [
         { _id: 2, user: "ijk123", status: "A" },
         { _id: 3, user: "xyz123", status: "P" },
         { _id: 4, user: "mop123", status: "P" }
      ],
      ordered: false,
      writeConcern: { w: "majority", wtimeout: 5000 }
   }
)

O documento que retornou mostra que o comando inseriu os três documentos com sucesso. Consulte Saída para detalhes.

{ "ok" : 1, "n" : 3 }

Usando Inserir com `bypassDocumentValidation`

Se as ações de validação do esquema forem definidas como error, as inserções em uma coleção retornarão erros para documentos que violam as regras de validação do esquema. Para inserir documentos que violariam estas regras, defina bypassDocumentValidation: true.

Crie a coleção user com uma regra de validação nos campos status.

A regra de validação valida que o status deve ser "Desconhecido" ou "Incompleto":

db.createCollection("users", {
   validator:
      {
         status: {
            $in: [ "Unknown", "Incomplete" ]
         }
      }
})

Tente inserir um documento que viole a regra de validação:

db.runCommand({
      insert: "users",
      documents: [ {user: "123", status: "Active" } ]
})

A inserção retorna uma mensagem de erro de gravação:

{
   n: 0,
   writeErrors: [
      {
         index: 0,
         code: 121,
         errInfo: {
            failingDocumentId: ObjectId('6197a7f2d84e85d1cc90d270'),
            details: {
               operatorName: '$in',
               specifiedAs: { status: { '$in': [Array] } },
               reason: 'no matching value found in array',
               consideredValue: 'Active'
            }
         },
         errmsg: 'Document failed validation'
      }
   ],
   ok: 1
}

Defina bypassDocumentValidation : true e execute novamente a inserção:

db.runCommand({
   insert: "users",
   documents: [ {user: "123", status: "Active" } ],
   bypassDocumentValidation: true
})

A operação é bem-sucedida.

Para verificar se há documentos que violam regras de validação de esquema, use o comando validate.

Saída

O documento devolvido contém um subconjunto dos seguintes campos:

insert.ok: O status do comando.

insert.n: O número de documentos inseridos.

insert.writeErrors

Uma array de documentos que contém informações sobre qualquer erro encontrado durante a operação de inserção. A array writeErrors contém um documento de erro para cada inserção com erro.

Cada documento de erro contém os seguintes campos:

insert.writeErrors.index: Um número inteiro que identifica o documento na array documents, que utiliza um índice baseado em zero.

insert.writeErrors.code: Um valor inteiro identificando o erro.

insert.writeErrors.errmsg: Uma descrição do erro.

insert.writeConcernError

Documento que descreve o erro relacionado ao write concern e contém o campo:

insert.writeConcernError.code: Um valor inteiro que identifica a causa do erro de write concern.

insert.writeConcernError.errmsg: Uma descrição da causa do erro de write concern.

insert.writeConcernError.errInfo.writeConcern

O objeto de write concern usado para a operação correspondente. Para obter informações sobre os campos de objeto de write concern, consulte Especificação de write concern.

O objeto de write concern também pode conter o seguinte campo, indicando a origem da write concern:

insert.writeConcernError.errInfo.writeConcern.provenance

Um valor de string que indica a origem do write concern (conhecido como write concern provenance). A tabela a seguir mostra os valores possíveis para este campo e sua significância:

Proveniência	Descrição
`clientSupplied`	A preocupação de gravação foi especificada no aplicativo.
`customDefault`	A preocupação de gravação originou-se de um valor padrão personalizado definido. Consulte `setDefaultRWConcern`.
`getLastErrorDefaults`	A preocupação de gravação originada do campo `settings.getLastErrorDefaults` do conjunto de réplicas.
`implicitDefault`	A preocupação de gravação originou-se do servidor na ausência de todas as outras especificações de preocupação de gravação.

A seguir está um documento de exemplo retornado para uma insert bem-sucedida de um único documento:

{ ok: 1, n: 1 }

A seguir, um exemplo de documento retornado para um insert de dois documentos que inseriram com êxito um documento, mas encontraram um erro com o outro documento:

{
   "ok" : 1,
   "n" : 1,
   "writeErrors" : [
      {
         "index" : 1,
         "code" : 11000,
         "errmsg" : "insertDocument :: caused by :: 11000 E11000 duplicate key error index: test.users.$_id_  dup key: { : 1.0 }"
      }
   ]
}

Voltar

pegue mais

Redefinir erro

inserir.leafygreen-ui-m0pgrr{-webkit-align-self:center;-ms-flex-item-align:center;align-self:center;padding:0 10px;visibility:hidden;}.leafygreen-ui-a30zj9{color:#889397;vertical-align:middle;margin-top:-2px;}.css-1l4s55v{margin-top:-175px;position:absolute;padding-bottom:2px;}

Definição

Dica

Sintaxe

Campos de comando

Comportamento

Limite de tamanho

Validação do documento

Transações

Importante

Criação de collections em transações

Dica

Veja também:

Write concerns e transações

Inserir Imprecisões

Exemplos

Inserir um único documento

Inserção em massa

Usando Inserir com bypassDocumentValidation

Saída

inserir

Usando Inserir com `bypassDocumentValidation`