insert

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

Em mongosh, este comando também pode ser executado por meio dos métodos assistentes db.collection.insertOne() 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 versão 7.1: Quando insert é executado em mongos, os erros de write concern 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 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 }"
      }
   ]
}