Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
db.collection.findOneAndReplace()
Nesta página
Definição
db.collection.findOneAndReplace( 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:Novo na versão 3.2.
Substitui um único documento com base no filtroespecificado.
Sintaxe
O método findOneAndReplace()
tem o seguinte formulário:
db.collection.findOneAndReplace( <filter>, <replacement>, { writeConcern: <document>, projection: <document>, sort: <document>, maxTimeMS: <number>, upsert: <boolean>, returnDocument: <string>, returnNewDocument: <boolean>, collation: <document> } )
Campos e opções
O método findOneAndReplace()
utiliza os seguintes campos e opções:
Campo | Tipo | Descrição | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
documento | Os critérios de seleção para a atualização. Os mesmos seletores de query que no método Para substituir o primeiro documento retornado na coleção, especifique um documento vazio Se não for especificado, o padrão será um documento vazio. Iniciando no MongoDB 4.2, a operação retorna um erro se o argumento de query não for um documento. | |||||||||||
documento | O documento de substituição. Não é possível conter operadores de atualização. O documento | |||||||||||
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. | ||||||||||
documento | Opcional. Um subconjunto de campos para retornar. Para retornar todos os campos no documento correspondente, omita este campo. Iniciando no MongoDB 4.2, a operação retorna um erro se o campo de projeção não for um documento. | |||||||||||
documento | Opcional. Especifica uma ordem de classificação para os documentos correspondentes pelo filtro. Iniciando no MongoDB 4.2, a operação retorna um erro se o campo de classificação não for um documento. Consulte | |||||||||||
maxTimeMS | número | Opcional. Especifica um limite de tempo em milésimos de segundo no qual a operação deve ser concluída. Retorna um erro se o limite for excedido. | ||||||||||
boleano | Opcional. Quando
O MongoDB adicionará o campo Para evitar várias alterações, certifique-se de que os campos Padrão é | |||||||||||
string | Opcional. A partir de
| |||||||||||
boleano | Opcional. Quando Padrão é | |||||||||||
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. Novidade na versão 3.4. |
Devoluções
Retorna o documento original por padrão. Retorna o documento atualizado se returnDocument estiver definido como after
ou returnNewDocument estiver definido como true
.
Comportamento
Correspondência de documento
db.collection.findOneAndReplace()
substitui o primeiro documento correspondente na collection que corresponde a filter
. O campo sort
pode ser usado para influenciar qual documento será modificado.
Projeção
Importante
Consistência de linguagem
Como parte de tornar a projeção find()
e findAndModify()
consistente com o estágio $project
da agregação,
A projeção
find()
efindAndModify()
pode aceitar expressões de agregação e sintaxe.O MongoDB impõe restrições adicionais em relação às projeções. Consulte Restrições de Projeção para detalhes.
O campo projection
obtém um documento no seguinte formulário:
{ field1: <value>, field2: <value> ... }
Projeção | Descrição |
---|---|
<field>: <1 or true> | Especifica a inclusão de um campo. Se você especificar um número inteiro diferente de zero para o valor de projeção, a operação tratará o valor como true . |
<field>: <0 or false> | Especifica a exclusão de um campo. |
"<field>.$": <1 or true> | Usa o operador de projeção de array Não disponível para visualizações. |
<field>: <array projection> | Usa os operadores de projeção de array ( Não disponível para visualizações. |
<field>: <aggregation expression> | Especifica o valor do campo projetado. Com o uso de expressões de agregação e sintaxe, incluindo o uso de literais e variáveis de agregação, você pode projetar novos campos ou projetar campos existentes com novos valores.
Nas versões 4.2 e anterior, qualquer valor de especificação (com exceção do valor de documento anteriormente não suportado) é tratado como |
Especificação de campo incorporada
Para campos em documentos incorporados, você pode especificar o campo usando:
notação de pontos, por exemplo
"field.nestedfield": <value>
formulário aninhado, por exemplo
{ field: { nestedfield: <value> } }
_id
Projeção de campo
O campo _id
é incluído nos documentos retornados por padrão, a menos que você especifique explicitamente _id: 0
na projeção para suprimir o campo.
Inclusão ou exclusão
Uma projection
não pode conter especificações de inclusão e exclusão, com exceção do campo _id
:
Em projeções que incluem explicitamente campos, o campo
_id
é o único campo que você pode excluir explicitamente.Em projeções que excluem explicitamente campos, o campo
_id
é o único campo que você pode incluir explicitamente; entretanto, o campo_id
é incluído por padrão.
Para obter mais informações sobre "projection", consulte também:
Coleções partilhadas
Para utilizar db.collection.findOneAndReplace()
em uma coleção fragmentada, o filtro de consulta deve incluir uma condição de igualdade na chave de fragmento.
Os documento em uma collection fragmentada podem não ter os campo principais do fragmento. Para direcionar um documento que não tenha a chave de shard, você pode usar a correspondência de igualdade null
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.findOneAndReplace()
:
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 db.collection.findOneAndReplace()
para definir a chave de shard ausente do documento,
Você deve executar em um
mongos
. Não emita a operação diretamente no fragmento.Você deve executar em uma transação ou como retryable write se o novo valor da chave de shard não for
null
.Você deve incluir um filtro de igualdade na chave de shard completa.
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.findOneAndReplace()
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.findOneAndReplace()
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.
Entradas Oplog
Se uma operação db.collection.findOneAndReplace()
substituir com sucesso um documento, a operação adicionará uma entrada no oplog (registro de operações). Se a operação falhar ou não localizar um documento para substituir, a operação não adicionará uma entrada no oplog.
Exemplos
Substituir um documento
Criar uma coleção scores
de amostra com os seguintes documentos:
db.scores.insertMany([ { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 }, { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 }, { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }, { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }, { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 } ]);
A operação a seguir encontra um documento com score
a menos de 20000
e o substitui:
db.scores.findOneAndReplace( { "score" : { $lt : 20000 } }, { "team" : "Observant Badgers", "score" : 20000 } )
A operação retorna o documento original que foi substituído:
{ "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }
Se returnNewDocument for verdade, a operação retornará o documento de substituição.
Embora vários documentos atendam aos critérios de filtro, db.collection.findOneAndReplace()
substitui apenas um documento.
Classificar e Substituir um documento
Criar uma coleção scores
de amostra com os seguintes documentos:
db.scores.insertMany([ { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 }, { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 }, { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }, { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }, { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 } ]);
Ao incluir uma classificação ascendente no campo score
, o exemplo a seguir substitui o documento pela pontuação mais baixa entre os documentos que correspondem ao filtro:
db.scores.findOneAndReplace( { "score" : { $lt : 20000 } }, { "team" : "Observant Badgers", "score" : 20000 }, { sort: { "score" : 1 } } )
A operação retorna o documento original que foi substituído:
{ "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }
Consulte Substituir um documento para obter o resultado não classificado deste comando.
Campos Específicos do Projeto no Documento de Devolução
Criar uma coleção scores
de amostra com os seguintes documentos:
db.scores.insertMany([ { "_id" : 1, "team" : "Fearful Mallards", "score" : 25000 }, { "_id" : 2, "team" : "Tactful Mooses", "score" : 23500 }, { "_id" : 3, "team" : "Aquatic Ponies", "score" : 19250 }, { "_id" : 4, "team" : "Cuddly Zebras", "score" : 15235 }, { "_id" : 5, "team" : "Garrulous Bears", "score" : 18000 } ])
A seguinte operação usa projeção para exibir apenas o campo team
no documento retornado:
db.scores.findOneAndReplace( { "score" : { $lt : 22250 } }, { "team" : "Therapeutic Hamsters", "score" : 22250 }, { sort : { "score" : 1 }, projection: { "_id" : 0, "team" : 1 } } )
A operação retorna o documento original com somente o campo team
:
{ "team" : "Cuddly Zebras" }
Substituir documento por limite de tempo
A seguinte operação define um limite de tempo de 5ms para completar:
try { db.scores.findOneAndReplace( { "score" : { $gt : 25000 } }, { "team" : "Emphatic Rhinos", "score" : 25010 }, { maxTimeMS: 5 } ); } catch(e){ print(e); }
Se a operação exceder o limite de tempo, ela retornará:
Error: findAndModifyFailed failed: { "ok" : 0, "errmsg" : "operation exceeded time limit", "code" : 50 }
Substituir Documento por Upsert
A operação a seguir usa o campo upsert para inserir o documento de substituição se nenhum documento corresponder ao filtro:
try { db.scores.findOneAndReplace( { "team" : "Fortified Lobsters" }, { "_id" : 6019, "team" : "Fortified Lobsters" , "score" : 32000}, { upsert : true, returnDocument: "after" } ); } catch (e){ print(e); }
A operação retorna o seguinte:
{ "_id" : 6019, "team" : "Fortified Lobsters", "score" : 32000 }
Se returnDocument: "before"
foi definido, a operação retornaria null
porque não há nenhum documento original para retornar.
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.
Criar uma coleção myColl
de amostra com os seguintes documentos:
db.myColl.insertMany([ { _id: 1, category: "café", status: "A" }, { _id: 2, category: "cafe", status: "a" }, { _id: 3, category: "cafE", status: "a" } ]);
A operação a seguir inclui a opção de agrupamento :
db.myColl.findOneAndReplace( { category: "cafe", status: "a" }, { category: "cafÉ", status: "Replaced" }, { collation: { locale: "fr", strength: 1 } } );
A operação retorna o seguinte documento:
{ "_id" : 1, "category" : "café", "status" : "A" }