db.collection.replaceOne()

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplos

O MongoDB 5.0 é o fim da vida útil a partir de de 2024 outubro. Esta versão da documentação não é mais suportada. Para atualizar sua 5.0 implantação do, consulte o MongoDB 6.0 procedimentos de atualização.

MongoDB com drivers

Esta página documenta um método. Para ver o método equivalente em um driver MongoDB , consulte a página correspondente para sua linguagem de mongosh programação:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Mongoid Rust Scala

Definição

db.collection.replaceOne(filter, replacement, options)

Substitui um único documento dentro da coleção com base no filtro.

Retorna:	Um documento contendo: Um booleano `acknowledged` como `true` se a operação foi executada com preocupação de gravação ou se a preocupação de gravação `false` foi desativada `matchedCount` contendo o número de documentos correspondentes `modifiedCount` contendo o número de documentos modificados `upsertedId` contendo o `_id` para o documento atualizado

Compatibilidade

Esse método 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

Sintaxe

O método replaceOne() tem o seguinte formato:

db.collection.replaceOne(
   <filter>,
   <replacement>,
   {
      upsert: <boolean>,
      writeConcern: <document>,
      collation: <document>,
      hint: <document|string>
   }
)

O método replaceOne() utiliza os seguintes parâmetros:

Parâmetro

Tipo

Descrição

filtro, filtro

documento

Os critérios de seleção para a atualização. Os mesmos seletores de consulta que no método find() estão disponíveis.

Especifique um documento vazio { } para substituir o primeiro documento retornado na coleção.

replacement

documento

O documento de substituição.

Não é possível conter operadores de atualização.

upsert

booleano

Opcional. Quando,true replaceOne() ou:

Insere o documento a partir do parâmetro replacement se nenhum documento corresponder ao filter.
Substitui o documento que corresponde a filter pelo documento replacement.

O MongoDB adicionará o campo _id ao documento de substituição se ele não for especificado nos documentos filter ou replacement . Se _id estiver presente em ambos, os valores deverão ser iguais.

Para evitar várias alterações, certifique-se de que os campos query sejam indexados exclusivamente.

Padrão é false.

writeConcern

documento

Opcional. Um documento que expressa o write concern. Omitir para usar o write concern 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.

collation

documento

Opcional.

Especifica o agrupamento a ser usado para a operaçã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 o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte db.createCollection()), a operação usará o agrupamento especificado para a coleçã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.

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.

Novidade na versão 3.4.

dica

documento

Opcional. Um documento ou string que especifica o índice a ser usado para dar suporte ao filtro.

A opção pode usar um documento de especificação de índice ou a string do nome do índice.

Se você especificar um índice que não existe, a operação emitirá erros.

Para um exemplo, consulte Especificar hint para replaceOne.

Comportamento

replaceOne() substitui o primeiro documento correspondente na coleção que corresponde a filter, usando o documento replacement.

`upsert`

Se upsert: true e nenhum documento corresponder a filter, db.collection.replaceOne() cria um novo documento com base no documento replacement .

Se você especificar upsert: true em uma coleção fragmentada, deverá incluir a chave de fragmento completa em filter. Para comportamento adicional do db.collection.replaceOne() em uma coleção fragmentada, consulte Coleções fragmentadas.

Consulte Substituir por Upsert.

Capped collections

Se uma operação de substituição alterar o tamanho do documento, a operação falhará.

Coleções de Time Series

Não é possível usar o método replaceOne() em uma coleção de séries temporais.

Coleções fragmentadas

db.collection.replaceOne() tenta direcionar um único fragmento. Utilizar o filtro de query é o primeiro passo. Se a operação não puder direcionar um único fragmento pelo filtro de query, ela tentará direcionar pelo documento de substituição.

Em versões anteriores, a operação tenta direcionar usando o documento de substituição.

Requisitos da Chave de Fragmento no Documento de Substituição

O documento de substituição não precisa incluir a chave de fragmento.

Aviso

Os documentos em coleções fragmentadas podem não ter os campos chave de fragmentado. Tome cuidado para evitar remover acidentalmente a chave de fragmento ao alterar o valor dela em um documento.

`upsert` em uma coleção fragmentada

Uma operação de db.collection.replaceOne() que inclui upsert: true em uma coleção fragmentada deve incluir a chave de fragmento completa em filter.

No entanto, os documentos em uma coleção fragmentada podem estar faltando os campos de chave de fragmento. Para direcionar um documento que não possui a chave de fragmento, você pode usar a null correspondência de igualdade em conjunto com outra condição de filtro (como no campo _id ). Por exemplo:

{ _id: <value>, <shardkeyfield>: null } // _id of the document missing shard key

Modificação da chave de fragmento

Você pode atualizar o valor da chave de fragmento de um documento, a menos que o campo de chave de fragmento seja o campo de _id imutável.

Aviso

Os documentos em coleções fragmentadas podem não ter os campos chave de fragmentado. Tome cuidado para evitar remover acidentalmente a chave de fragmento ao alterar o valor dela em um documento.

Para modificar o valor da chave de fragmento existente com db.collection.replaceOne():

Você deve executar em um mongos. Não emita a operação diretamente no fragmento.
Você deve executar em uma transação ou como uma gravação repetível.
Você deve incluir um filtro de igualdade na chave de fragmento completa.

Chave de fragmento ausente

Os documentos em coleções fragmentadas podem não ter os campos de chave de fragmento. Para usar db.collection.replaceOne() a fim de definir a chave de fragmento ausente do documento, é necessário executar em um mongos. Não emita a operação diretamente no fragmento.

Além disso, os seguintes requisitos também se aplicam:

Tarefa	Requisitos
Para definir como `null`	Exige filtro de equivalência na chave de fragmento completa se `upsert: true` for especificado.
Para definir um valor diferente de `null`	Deve ser executado dentro de uma transação ou como uma gravação repetível. Requer filtro de equivalência na chave de fragmento completa se: `upsert: true`, ou o novo valor chave de fragmento pertence a um fragmento diferente.

Dica

Como um valor de chave ausente é retornado como parte de uma correspondência de igualdade nula, para evitar a atualização de uma chave de valor nulo, inclua condições de consulta (como no campo _id) conforme apropriado.

Veja também:

Transações

db.collection.replaceOne() 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.

Inserção nas Transações

Você pode criar coleção e índices dentro de uma transação distribuída se a transação não for uma transação de gravação cross-fragmento.

db.collection.replaceOne() com upsert: true pode ser executado em uma coleção existente ou em uma coleção inexistente. Se for executada em uma coleção inexistente, a operação cria a coleção.

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.

Exemplos

Substituir

A coleção restaurant contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

A operação a seguir substitui um único documento em que name: "Central Perk Cafe":

try {
   db.restaurant.replaceOne(
      { "name" : "Central Perk Cafe" },
      { "name" : "Central Pork Cafe", "Borough" : "Manhattan" }
   );
} catch (e){
   print(e);
}

A operação retorna:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Se nenhuma correspondência for encontrada, a operação retornará:

{ "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

A configuração upsert: true inseriria o documento se nenhuma correspondência fosse encontrada. Consulte Substituir por Upsert

Substitua por Upsert

A coleção restaurant contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan",  "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

A seguinte operação tenta substituir o documento por name : "Pizza Rat's Pizzaria", por upsert : true:

try {
   db.restaurant.replaceOne(
      { "name" : "Pizza Rat's Pizzaria" },
      { "_id": 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 },
      { upsert: true }
   );
} catch (e){
   print(e);
}

Desde upsert : true o documento é inserido com base no documento replacement . A operação retorna:

{
   "acknowledged" : true,
   "matchedCount" : 0,
   "modifiedCount" : 0,
   "upsertedId" : 4
}

A coleção agora contém os seguintes documentos:

{ "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
{ "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
{ "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 },
{ "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 8 }

Substitua por write concern

Dado um conjunto de réplicas de três membros, a operação a seguir especifica um w de majority e wtimeout de 100

try {
   db.restaurant.replaceOne(
       { "name" : "Pizza Rat's Pizzaria" },
       { "name" : "Pizza Rat's Pub", "Borough" : "Manhattan", "violations" : 3 },
       { w: "majority", wtimeout: 100 }
   );
} catch (e) {
   print(e);
}

Se a confirmação demorar mais que o limite wtimeout, a seguinte exceção será lançada:

WriteConcernError({
   "code" : 64,
   "errmsg" : "waiting for replication timed out",
   "errInfo" : {
     "wtimeout" : true,
     "writeConcern" : {
       "w" : "majority",
       "wtimeout" : 100,
       "provenance" : "getLastErrorDefaults"
     }
   }
})

A tabela a seguir explica os possíveis valores de errInfo.writeConcern.provenance:

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.

Especifique o agrupamento

Novidade na versão 3.4.

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.

Uma coleção myColl possui os seguintes documentos:

{ _id: 1, category: "café", status: "A" }
{ _id: 2, category: "cafe", status: "a" }
{ _id: 3, category: "cafE", status: "a" }

A seguinte operação inclui a opção coleção:

db.myColl.replaceOne(
   { category: "cafe", status: "a" },
   { category: "cafÉ", status: "Replaced" },
   { collation: { locale: "fr", strength: 1 } }
);

Especificar `hint` para `replaceOne`

Criar uma coleção members de amostra com os seguintes documentos:

db.members.insertMany([
   { "_id" : 1, "member" : "abc123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" },
   { "_id" : 3, "member" : "lmn123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 4, "member" : "pqr123", "status" : "D", "points" : 20,  "misc1" : "Deactivated", "misc2" : null },
   { "_id" : 5, "member" : "ijk123", "status" : "P", "points" :  0,  "misc1" : null, "misc2" : null },
   { "_id" : 6, "member" : "cde123", "status" : "A", "points" : 86,  "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment" }
])

Crie os seguintes índices na coleção:

db.members.createIndex( { status: 1 } )
db.members.createIndex( { points: 1 } )

A seguinte operação de atualização sugere explicitamente o uso do índice { status: 1 }:

Observação

Se você especificar um índice que não existe, a operação emitirá erros.

db.members.replaceOne(
   { "points": { $lte: 20 }, "status": "P" },
   { "misc1": "using index on status", status: "P", member: "replacement", points: "20"},
   { hint: { status: 1 } }
)

A operação retorna o seguinte:

{ "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

Para visualizar os índices usados, é possível usar o pipeline $indexStats :

db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] )

Voltar

db.collection.renameCollection

db.collection.stats

Definição

Compatibilidade

Observação

Sintaxe

Comportamento

upsert

Capped collections

Coleções de Time Series

Coleções fragmentadas

Requisitos da Chave de Fragmento no Documento de Substituição

Aviso

upsert em uma coleção fragmentada

Modificação da chave de fragmento

Aviso

Chave de fragmento ausente

Dica

Transações

Importante

Inserção nas Transações

Dica

Veja também:

Write concerns e transações

Exemplos

Substituir

Substitua por Upsert

Substitua por write concern

Especifique o agrupamento

Especificar hint para replaceOne

Observação

`upsert`

`upsert` em uma coleção fragmentada

Especificar `hint` para `replaceOne`