Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
db.collection.replaceOne()
Definição
db.collection.replaceOne(filter, replacement, options)
Importante
Método mongosh
Esta página documenta um método
mongosh
. Esta não é a documentação para comandos de banco de dados ou drivers específicos de idioma, como Node.js.Para o comando do banco de dados, consulte o comando
update
.Para drivers de API do MongoDB, consulte a documentação do driver MongoDB específica do idioma.
Para a documentação de shell legada do
mongo
, consulte a documentação para a versão correspondente do MongoDB Server:Substitui um único documento dentro da coleção com base no filtro.
Retorna: Um documento contendo: Um valor booleano
acknowledged
comotrue
se a operação for executada com referência de escritarefer oufalse
se a referência de escrita estiver desativadamatchedCount
contendo o número de documentos correspondentesmodifiedCount
contendo o número de documentos modificadosupsertedId
contendo o_id
para o documento atualizado
Compatibilidade
Você pode utilizar o db.collection.replaceOne()
para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão código-disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
O método replaceOne()
tem o seguinte formulário:
db.collection.replaceOne( <filter>, <replacement>, { upsert: <boolean>, writeConcern: <document>, collation: <document>, hint: <document|string> // Available starting in 4.2.1 } )
O método replaceOne()
utiliza os seguintes parâmetros:
Parâmetro | Tipo | Descrição | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
documento | Os critérios de seleção para a atualização. Os mesmos seletores de query que no método Especifique um documento vazio | |||||||||||
replacement | documento | O documento de substituição. Não é possível conter operadores de atualização. | ||||||||||
upsert | boleano | Opcional. Quando
O MongoDB adicionará o campo Para evitar várias alterações, certifique-se de que os campos Padrão é | ||||||||||
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:
Ao especificar agrupamento, o campo Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão (consulte Se nenhum agrupamento for especificado para a collection 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. | ||||||||||
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 ocorrerá erros. Para um exemplo, consulte Especificar |
Comportamento
replaceOne()
substitui o primeiro documento correspondente na collection 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, você deverá incluir a chave de shard completa no 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 partilhadas
A partir do MongoDB 4.2, db.collection.replaceOne()
tenta direcionar um único fragmento, primeiro usando o filtro de query. Se a operação não puder direcionar um único fragmento pelo filtro de consulta, 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 Shard no Documento de Substituição
O documento de substituição não precisa incluir a chave de fragmento.
Aviso
Documento em collection fragmentadas podem não ter os campo da chave de fragmento. Tenha cuidado para não remover acidentalmente a chave de fragmento ao alterar o valor da chave de fragmento de um documento.
upsert
em uma coleção fragmentada
A partir do MongoDB 4.2, uma operação db.collection.replaceOne()
que inclui upsert: true
em uma collection fragmentada deve incluir a chave de shard completa no filter
.
No entanto, os documento em uma collection fragmentada podem não ter os campo do fragmento. Para direcionar um documento que não tenha a chave de shard, você pode usar a null
equality match 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
A partir do MongoDB 4,2, você pode atualizar o valor da chave do fragmento de um documento, a menos que o campo da chave do fragmento seja o campo imutável _id
. No MongoDB 4.2 e anterior, o valor de campo chave de fragmento de um documento é imutável.
Aviso
Documento em collection fragmentadas podem não ter os campo da chave de fragmento. Tenha cuidado para não remover acidentalmente a chave de fragmento ao alterar o valor da chave de fragmento de um documento.
Para modificar o valor chave do 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 que pode ser tentada novamente.
Você deve incluir um filtro de igualdade na chave de shard completa.
Chave de Fragmento Ausente
Os documentos em uma collection fragmentada podem não ter os campos de chave de shard. Para usar o db.collection.replaceOne()
para definir a chave de shard ausente do documento, você deve executar em um mongos
. Não emita a operação diretamente no shard.
Além disso, os seguintes requisitos também se aplicam:
Tarefa | Requisitos |
---|---|
Para definir como null |
|
Para definir um valor diferente de null |
|
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 collection e índices dentro de uma transação distribuída se a transação não for uma transação de escrita cross-shard.
db.collection.replaceOne()
com upsert: true
pode ser executado em uma coleção existente ou uma coleção não existente. Se for executada em uma coleção inexistente, a operação cria a coleção.
Dica
Veja também:
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 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 escrita 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 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
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
Novidades na versão 4.2.1.
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 ocorrerá 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 } } ] )