bulkWrite

Nesta página

Definição

Sintaxe
Campos de comando
Saída
Comportamento
Exemplos
Saiba mais

Definição

bulkWrite

Novidades na versão 8.0.

A partir do MongoDB 8.0, você pode usar o novo comando bulkWrite para executar muitas operações de inserção, atualização e exclusão em várias collections em uma única solicitação. O método db.collection.bulkWrite() existente só permite modificar uma collection em uma solicitação.

Para especificar cada coleção no comando bulkWrite , utilize um namespace (banco de dados de dados e nome da coleção).

Sintaxe

O comando tem esta sintaxe:

db.adminCommand( {
   bulkWrite: 1,
   // Include the insert, update, and delete operations
   // in the ops array
   ops: [
      {
         insert: <integer>,  // Namespace ID index for insert operation.
                             // Must match a namespace ID index in
                             // ns specified later in the nsInfo array.
         document: <document>
      },
      {
         update: <integer>,  // Namespace ID index for update operation
         filter: <document>,
         updateMods: <document>,
         arrayFilters: [ <filterDocument0>, <filterDocument1>, ...  ],
         multi: <bolean>,
         hint: <document>,
         constants: <document>,
         collation: <document>
      },
      {
         delete: <integer>,  // Namespace ID index for delete operation
         filter: <document>,
         multi: <boolean>,
         hint: <document>,
         collation: <document>
      },
      ...
      // Additional insert, update, and delete operations in any order
      ...
   ],
   // Include the namespaces with collections to modify
   // in the nsInfo array. You can add multiple namespaces here.
   nsInfo: [
      {
         ns: <string>,  // Namespace (database and collection name) to modify.
                        // Each operation namespace ID index
                        // specified in the earlier ops array must
                        // match a namespace ID index here.
         collectionUUID: <string>,
         encryptionInformation: <document>
      },
      ...
      // Additional namespaces
      ...
   ],
   // Additional fields
   ordered: <boolean>,
   bypassDocumentValidation: <boolean>,
   comment: <string>,
   let: <document>,
   errorsOnly: <boolean>,
   cursor: { batchSize: <integer> },
   writeConcern: <string>
} )

Na sintaxe do comando, você pode especificar vários:

Inserir, atualizar e excluir operações em qualquer ordem na array ops .
Namespaces para as operações na array nsInfo . Para corresponder a operação ao namespace, use o mesmo índice de ID do namespace . Os índices começam em 0. Você pode usar coleções fragmentadas .

Campos de comando

O comando utiliza os seguintes campos:

Campo	Tipo	necessidade	Descrição
`insert`	inteiro	Obrigatório	Índice de ID do namespace para uma operação de inserção, que deve corresponder a um índice de ID do namespace no campo `ns` da array `nsInfo` . Os índices começam em `0`.
`document`	documento	Obrigatório	Documento para inserir na coleção.
`update`	inteiro	Obrigatório	Índice de ID do namespace para uma operação de atualização, que deve corresponder a um índice de ID do namespace no campo `ns` da array `nsInfo` . Os índices começam em `0`.
`filter`	documento	Opcional	Seletor de query para limitar os documentos para a operação de atualização ou exclusão.
`updateMods`	documento	Opcional	Atualizar a operação a ser executada na coleção. Você pode especificar um destes: Um documento com expressões de operador de atualização . Um pipeline de agregação no formato `[ <stage1>, <stage2>, ... ]` com estágios para as atualizações.
`arrayFilters`	array de documentos	Opcional	Array de documentos de filtro que especificam os documentos a serem modificados para uma operação de atualização em um campo de array . Para obter detalhes, consulte Operações de atualização de array com `arrayFilters`.
`multi`	booleano	Opcional	Se o campo `multi` for `true`, a operação de atualização ou exclusão atualizará ou excluirá todos os documentos que correspondam ao documento `filter`. Se `false`, a operação atualiza ou exclui o primeiro documento que corresponde ao documento `filter`. Para obter detalhes sobre transações com vários documentos, consulte Transações. O padrão é `false`.
`hint`	documento	Opcional	Índice a ser usado para o documento `filter`. Se o índice não existir, a operação de atualização retornará um erro.
`constants`	documento	Opcional	Constantes para uma atualização personalizada do pipeline de agregação .
`collation`	documento	Opcional	Agrupamento para uma operação de atualização ou exclusão.
`delete`	inteiro	Obrigatório	Índice de ID do namespace para uma operação de exclusão, que deve corresponder a um índice de ID do namespace no campo `ns` da array `nsInfo` . Os índices começam em `0`.
`ns`	string	Obrigatório	Namespace (banco de dados de dados e coleção) para as operações. Defina o índice do ID do namespace para cada operação em `ops` como o índice da array do namespace correspondente em `ns`. Os índices começam em `0`.
`collectionUUID`	string	Opcional	Valor hexadecimal UUID que especifica a collection para as operações.
`encryptionInformation`	documento	Opcional	Esquema de informações de criptografia e tokens para a operação. Para obter detalhes, consulte Esquemas de criptografia.
`ordered`	booleano	Opcional	Se `true`, execute operações ordenadas. Caso contrário, execute operações não ordenadas. Operações ordenadas são executadas em série. Se ocorrer um erro, todas as operações restantes serão canceladas. Operações não ordenadas são executadas em paralelo. Se ocorrer um erro, todas as instruções restantes serão executadas. As operações podem ser reordenadas pelo servidor para aumentar o desempenho. Portanto, seus aplicativos não devem depender da ordem de execução da operação. O padrão é `true`.
`bypassDocumentValidation`	booleano	Opcional	Se `true`, a operação ignora as regras de validação do documento. Se `false`, os documentos devem ser válidos. O padrão é `false`.
`comment`	string	Opcional	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).
`let`	documento	Opcional	Documento com uma lista de constantes para referenciar na operação. Para obter exemplos do `let` , consulte Usar variáveis na opção `let` ou campo `c` e Usar variáveis no `let`.
`errorsOnly`	booleano	Opcional	Se `true`, a operação retornará apenas erros e omitirá outras saídas. O padrão é `false`.
`cursor batchSize`	inteiro	Opcional	Tamanho do lote do cursor para os resultados retornados do comando `bulkWrite` . Para obter detalhes, consulte `cursor.batchSize()`.
`writeConcern`	string	Opcional	Write concern para a operação. Omita o uso do padrão do servidor .

Saída

O comando retorna um documento com estes campos:

Campo	Tipo	Descrição
`cursor`	documento	Cursor com os resultados do comando.
`cursor.id`	inteiro	Identificador do cursor.
`cursor.firstBatch`	array de documentos	Resultados das operações.
`cursor.firstBatch.ok`	inteiro	`1` indica que a operação foi bem-sucedida. Caso contrário, `0`.
`cursor.firstBatch.idx`	inteiro	Número de índice da operação, que corresponde à operação na array `ops` . A primeira operação tem um valor `idx` de `0`.
`cursor.firstBatch.code`	inteiro	Número de código para um erro.
`cursor.firstBatch.errmsg`	string	Descrição de um erro.
`cursor.firstBatch.keyPattern`	string	Especificação da chave de índice do documento para um erro.
`cursor.firstBatch.keyValue`	string	Valor da chave do índice do documento para um erro.
`cursor.firstBatch.n`	inteiro	Número total de documentos afetados por uma operação.
`cursor.firstBatch.nModified`	inteiro	Número de documentos modificados por uma operação de atualização.
`nErrors`	inteiro	Número de erros para o comando `bulkWrite` .
`nInserted`	inteiro	Número de documentos inseridos.
`nMatched`	inteiro	Número de documentos correspondentes.
`nModified`	inteiro	Número de documentos modificados.
`nUpserted`	inteiro	Número de documentos atualizados.
`nDeleted`	inteiro	Número de documentos excluídos.
`ok`	inteiro	`1` indica que o comando `bulkWrite` foi bem-sucedido. Caso contrário, `0`.

Observação

Os campos de saída podem variar dependendo das operações que você executa no comando bulkWrite .

Comportamento

Esta seção descreve o comportamento do comando bulkWrite .

Campo de vários documentos e gravações repetíveis

Se o campo multi for true, a operação de atualização ou exclusão atualizará ou excluirá todos os documentos que correspondam ao documento filter. Se false, a operação atualiza ou exclui o primeiro documento que corresponde ao documento filter. Para obter detalhes sobre transações com vários documentos, consulte Transações.

Para habilitar gravações repetíveis, consulte gravações repetíveis.

Você pode usar bulkWrite operações de inserção com retryable writes e o campo multi definido como true.

Você pode utilizar as operações de atualização e exclusão do bulkWrite com o campo do multi configurado para true. Mas você não pode usar as operações de atualização ou exclusão com multi definido como true e com gravações repetidas.

Desempenho da operação

Se você reescrever comandos de inserção, atualização e exclusão existentes como um comando bulkWrite e definir errorsOnly como true, o comando bulkWrite terá desempenho semelhante aos comandos existentes. Se você definir errorsOnly como false, o desempenho será pior.

Além disso, se você tiver uma sequência de comandos como esta:

insert
update
delete

Se você substituir esses comandos pelo seguinte fragmento de exemplo , o comando com o seguinte fragmento será mais rápido, independentemente das outras opções:

{
   bulkWrite: 1,
   ops: [
      insert,
      update,
      delete
   ]
}

A maior parte da melhoria de desempenho se deve à latência da rede, que varia dependendo da sua implementação, mas o exemplo é sempre mais rápido.

Exemplos

Esta seção contém exemplos de comando bulkWrite .

Exemplo de escrita em massa de namespace único

O seguinte exemplo do bulkWrite modifica um único namespace:

Criar a collection de exemplo das pizzas

Executar:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

Modifique a coleção de exemplo de pizzas

Execute o seguinte comando bulkWrite para executar operações de inserção, atualização e exclusão na collection pizzas :

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // Specify the namespace ID index immediately after
      // the insert, update, and delete text.
      // For example, "insert: 0" specifies the 0 namespace ID index,
      // which is the "test.pizzas" namespace in nsInfo at the end
      // of the example.
      // Insert a pizza.
      { insert: 0, document: { _id: 4, type: "sausage",
        size: "small", price: 12 } },
      // Update the price for medium pizzas.
      { update: 0, filter: { size: "medium" },
        updateMods: { $set: { price: 15 } } },
      // Delete the pizza with an _id of 2.
      { delete: 0, filter: { _id: 2 } }
   ],
   // The nsInfo array contains the namespace to apply the
   // previous operations to.
   nsInfo: [
      { ns: "test.pizzas" }  // Namespace ID index is 0.
   ]
} )

A coleção pizzas está no banco de banco de dados test padrão , então o namespace ns é "test.pizzas". O índice do ID do namespace é 0, definido no primeiro campo das operações de inserção, atualização e exclusão na array ops .

Examine a saída

O seguinte exemplo de saída bulkWrite , com vários campos ok: 1 e nErrors: 0, indica que todas as operações foram bem-sucedidas:

{
   cursor: {
      id: Long('0'),
      firstBatch: [
         { ok: 1, idx: 0, n: 1 },
         { ok: 1, idx: 1, n: 1, nModified: 1 },
         { ok: 1, idx: 2, n: 1 }
       ],
       ns: 'admin.$cmd.bulkWrite'
   },
   nErrors: 0,
   nInserted: 1,
   nMatched: 1,
   nModified: 1,
   nUpserted: 0,
   nDeleted: 1,
   ok: 1
}

Para obter detalhes sobre os campos de saída, consulte a seção Saída anterior.

Exemplo de gravação em massa de vários namespaces

Você pode especificar múltiplos namespaces em um comando bulkWrite .

O seguinte exemplo do bulkWrite contém operações de inserção, atualização e exclusão para dois namespaces:

Criar a collection de exemplo das pizzas

Se você já tiver a coleção pizzas em seu banco de banco de dados do test , utilize o método db.collection.drop() para soltá-la primeiro e então executar:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

Criar a coleção de exemplo de pedidos de pizza

Executar:

db.pizzaOrders.insertMany( [
   { _id: 0, type: "pepperoni", number: 5,
     orderDate: new Date( "2023-01-15T12:00:00Z" ) },
   { _id: 1, type: "cheese", number: 15,
     orderDate: new Date( "2023-01-23T11:12:32Z" ) },
   { _id: 2, type: "vegan", number: 20,
     orderDate: new Date( "2023-03-20T10:01:12Z" ) }
] )

Modifique as collections de exemplo

Execute o seguinte comando bulkWrite para executar operações de inserção, atualização e exclusão nas coleções de exemplo :

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // Specify the namespace ID indexes immediately after
      // the insert, update, and delete. For example, "insert: 0"
      // specifies the 0 namespace ID index, which is the "test.pizzas"
      // namespace. And, "insert: 1" specifies "test.pizzaOrders".
      // Insert pizzas.
      // Namespace ID is 0 for "test.pizzas", which
      // is specified as "insert: 0".
      { insert: 0, document: { _id: 5, type: "sausage",
        size: "small", price: 12 } },
      { insert: 0, document: { _id: 6, type: "vegan cheese",
        size: "large", price: 25 } },
      // Update the price for cheese pizzas.
      { update: 0, filter: { type: "cheese" },
        updateMods: { $set: { price: 15 } } },
      // Delete pizzas with a price less than 7.
      { delete: 0, filter: { price: { $lt: 7 } } },
      // Insert pizza orders.
      // Namespace ID is 1 for "test.pizzaOrders".
      { insert: 1, document: { _id: 3, type: "sausage", number: 7,
        orderDate: new Date( "2023-04-15T12:02:15Z" ) } },
      { insert: 1, document: { _id: 4, type: "vegan", number: 16,
        orderDate: new Date( "2023-05-12T11:03:11Z" ) } },
      // Update the number of pizza orders for cheese pizzas.
      { update: 1, filter: { type: "cheese" },
        updateMods: { $set: { number: 50 } } },
      // Delete the pizza order with an _id of 2.
      { delete: 1, filter: { _id: 2 } },
      // Delete pizza orders placed before March 15, 2023.
      { delete: 1, filter: { orderDate:
        { $lte: ISODate( "2023-03-15T00:00:00Z" ) } } }
   ],
   // Namespaces
   nsInfo: [
      { ns: "test.pizzas" }, // Namespace ID index is 0.
      { ns: "test.pizzaOrders" }  // Namespace ID index is 1.
   ]
} )

Examine a saída

O seguinte exemplo de resultado bulkWrite indica que as operações foram bem-sucedidas:

{
   cursor: {
      id: Long('0'),
      firstBatch: [
         { ok: 1, idx: 0, n: 1 },
         { ok: 1, idx: 1, n: 1 },
         { ok: 1, idx: 2, n: 1, nModified: 1 },
         { ok: 1, idx: 3, n: 1 },
         { ok: 1, idx: 4, n: 1 },
         { ok: 1, idx: 5, n: 1 },
         { ok: 1, idx: 6, n: 1, nModified: 1 },
         { ok: 1, idx: 7, n: 1 },
         { ok: 1, idx: 8, n: 1 }
      ],
      ns: 'admin.$cmd.bulkWrite'
   },
   nErrors: 0,
   nInserted: 4,
   nMatched: 2,
   nModified: 2,
   nUpserted: 0,
   nDeleted: 3,
   ok: 1
}

Exemplo de gravação em massa de operações com erros

O exemplo bulkWrite a seguir contém operações com erros e operações que não alteram nenhum documento:

Criar a collection de exemplo das pizzas

Se você já tiver a coleção pizzas em seu banco de banco de dados do test , utilize o método db.collection.drop() para soltá-la primeiro e então executar:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

Tentativa de modificar a collection de exemplo de pizzas

Execute o seguinte comando bulkWrite para executar operações de inserção, atualização e exclusão na collection pizzas :

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // The namespace ID indexes are specified immediately after
      // the insert, update, and delete text.
      // For example, "insert: 0" specifies the 0 namespace ID index,
      // which is the "test.pizzas" namespace in nsInfo.
      // Attempt to add a duplicate document with an
      // _id of 1, which already exists and causes an error.
      { insert: 0, document: { _id: 1, type: "tomato",
        size: "small", price: 12 } },
      // Attempt to add another duplicate document.
      { insert: 0, document: { _id: 2, type: "pepper",
        size: "small", price: 12 } },
      // Attempt to change the price for extra large pizzas,
      // which don't exist. This doesn't cause an error but
      // doesn't update any documents.
      { update: 0, filter: { size: "extra large" },
        updateMods: { $set: { price: 15 } } },
      // Attempt to remove a document that doesn't exist.
      // This doesn't cause an error but doesn't delete any documents.
      { delete: 0, filter: { _id: 8 } }
   ],
   // The nsInfo array contains the namespace to apply the
   // previous operations to.
   nsInfo: [
      { ns: "test.pizzas" }  // Namespace ID index is 0.
   ],
   // Set the ordered field to false to run the remaining operations
   // after an operation returns an error.
   ordered: false
} )

Examine a saída

O seguinte exemplo de resultado bulkWrite mostra os erros:

{
   cursor: {
      id: Long("0"),
      firstBatch: [
         {
            ok: 0,
            idx: 0,
            code: 11000,
            errmsg: 'E11000 duplicate key error collection:
            test.pizzas index: _id_ dup key: { _id: 1 }',
            keyPattern: { _id: 1 },
            keyValue: { _id: 1 },
            n: 0
         },
         {
            ok: 0,
            idx: 1,
            code: 11000,
            errmsg: 'E11000 duplicate key error collection:
            test.pizzas index: _id_ dup key: { _id: 2 }',
            keyPattern: { _id: 1 },
            keyValue: { _id: 2 },
            n: 0
         },
         { ok: 1, idx: 2, n: 0, nModified: 0 },
         { ok: 1, idx: 3, n: 0 }
      ],
      ns: 'admin.$cmd.bulkWrite'
   },
   nErrors: 2,
   nInserted: 0,
   nMatched: 0,
   nModified: 0,
   nUpserted: 0,
   nDeleted: 0,
   ok: 1
}

Para obter detalhes sobre os campos de saída, incluindo os códigos e mensagens de erro, consulte a seção Saída anterior.

Exemplo de gravação em massa com errorsOnly ativado

O exemplo de bulkWrite a seguir define errorsOnly como true para mostrar apenas a saída de erro:

Criar a collection de exemplo das pizzas

Se você já tiver a coleção pizzas em seu banco de banco de dados do test , utilize o método db.collection.drop() para soltá-la primeiro e então executar:

db.pizzas.insertMany( [
   { _id: 0, type: "pepperoni", size: "small", price: 4 },
   { _id: 1, type: "cheese", size: "medium", price: 7 },
   { _id: 2, type: "vegan", size: "large", price: 8 }
] )

Tentativa de modificar a collection de exemplo de pizzas

Execute o seguinte comando bulkWrite para executar operações de inserção, atualização e exclusão na collection pizzas com errorsOnly configurado para true:

db.adminCommand( {
   bulkWrite: 1,
   // The ops array contains the insert, update, and delete
   // operations.
   ops: [
      // The namespace ID indexes are specified immediately after
      // the insert, update, and delete text.
      // For example, "insert: 0" specifies the 0 namespace ID index,
      // which is the "test.pizzas" namespace in nsInfo.
      // Attempt to add a duplicate document with an
      // _id of 1, which already exists and causes an error.
      { insert: 0, document: { _id: 1, type: "tomato",
        size: "small", price: 12 } },
      // Attempt to add another duplicate document.
      { insert: 0, document: { _id: 2, type: "pepper",
        size: "small", price: 12 } },
      // Attempt to change the price for extra large pizzas,
      // which don't exist. This doesn't cause an error but
      // doesn't update any documents.
      { update: 0, filter: { size: "extra large" },
        updateMods: { $set: { price: 15 } } },
      // Attempt to remove a document that doesn't exist.
      // This doesn't cause an error but doesn't delete any documents.
      { delete: 0, filter: { _id: 8 } }
   ],
   // The nsInfo array contains the namespace to apply the
   // previous operations to.
   nsInfo: [
      { ns: "test.pizzas" }  // Namespace ID index is 0.
   ],
   // Set the ordered field to false to run the remaining operations
   // after an operation returns an error.
   ordered: false,
   // Set the errorsOnly field to true to only output the errors.
   errorsOnly: true
} )

Examine a saída

O seguinte exemplo de resultado bulkWrite mostra os erros:

{
   cursor: {
      id: Long("0"),
      firstBatch: [
         {
            ok: 0,
            idx: 0,
            code: 11000,
            errmsg: 'E11000 duplicate key error collection:
            test.pizzas index: _id_ dup key: { _id: 1 }',
            keyPattern: { _id: 1 },
            keyValue: { _id: 1 },
            n: 0
         },
         {
            ok: 0,
            idx: 1,
            code: 11000,
            errmsg: 'E11000 duplicate key error collection:
            test.pizzas index: _id_ dup key: { _id: 2 }',
            keyPattern: { _id: 1 },
            keyValue: { _id: 2 },
            n: 0
         },
      ],
      ns: 'admin.$cmd.bulkWrite'
   },
   nErrors: 2,
   nInserted: 0,
   nMatched: 0,
   nModified: 0,
   nUpserted: 0,
   nDeleted: 0,
   ok: 1
}

Saiba mais

Voltar

autoCompact

cloneCollectionAsCapped