insert (comando de banco de dados)

Definição

insert

Insere um ou mais documentos em uma coleção e retorna um documento de status. Os métodos de inserção do driver MongoDB usam esse comando internamente.

Dica

Em mongosh, este comando também pode ser executado por meio dos métodos de assistente 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.

Compatibilidade

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

• 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 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:

Comportamento

Exemplos

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

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

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

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

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

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

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

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

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 descrevendo erros relacionados à preocupação de gravação.

Alterado na 7.0.6 versão: (também disponível em 6.0.14 e 5.0.30): Quando é insert mongos executado em , erros de preocupação de gravação são sempre relatados, mesmo quando ocorrem um ou mais erros de escrita. Em versões anteriores, a ocorrência de erros de gravação poderia fazer com que insert não relatasse erros de preocupação de gravação .

Os documentos writeConcernError contêm os seguintes campos:

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 write concern foi especificada no aplicativo.
customDefault	A write concern originou-se de um valor padrão personalizado definido. Consulte setDefaultRWConcern.
getLastErrorDefaults	A write concern originada do campo settings.getLastErrorDefaults do conjunto de réplicas.
implicitDefault	A write concern originou-se do servidor na ausência de todas as outras especificações de write concern.

A seguir, um exemplo de resultado para uma inserção bem-sucedida de um único documento:

{ ok: 1, n: 1 }

O seguinte mostra um exemplo de saída quando um documento é inserido com sucesso e um segundo documento falha:

{
   "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 }"
      }
   ]
}