db.collection.findOneAndReplace()

Nesta página

Definição

Compatibilidade
Sintaxe
Comportamento
Exemplos

MongoDB com drivers

Esta página documenta um método mongosh. Para ver o método equivalente em um driver MongoDB, consulte a página correspondente da sua linguagem de 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.findOneAndReplace( filter, replacement, options ): Substitui um único documento com base no filtroespecificado.

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 findOneAndReplace() tem o seguinte formato:

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

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.

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.

Se o argumento de consulta não for um documento, a operação retornará um erro.

substituição

documento

O documento de substituição.

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

O documento <replacement> não pode especificar um valor _id que difere do documento substituído.

writeConcern

documento

Opcional. Um documento que expressa o write concern. Omitir para usar o write concern padrão.

{ w: <value>, j: <boolean>, wtimeout: <number> }

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.

projeção

documento

Opcional. Um subconjunto de campos para retornar.

Para retornar todos os campos no documento correspondente, omita este campo.

Se o argumento de projeção não for um documento, ocorrerá um erro na operação.

sort

documento

Opcional. Especifica uma ordem de classificação para os documentos correspondentes pelo filtro.

Se o argumento de classificação não for um documento, ocorrerá um erro com a operação.

Consulte cursor.sort().

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.

upsert

booleano

Opcional. Quando,true findOneAndReplace() ou:

Insere o documento a partir do parâmetro replacement se nenhum documento corresponder ao filter. Retorna null após inserir o novo documento, a menos que returnNewDocument seja true.
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.

documento de devolução

string

Opcional. A partir mongosh 0.13.2 de, returnDocument é uma alternativa para ReturnNewDocument. Se ambas as opções forem definidas, o returnDocument terá precedência.

returnDocument: "before" retorna o documento original. returnDocument: "after" retorna o documento atualizado.

Devolver novo documento

booleano

Opcional. Quando true, retorna o documento de substituição em vez do documento original.

Padrão é false.

agrupamento

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.

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 coleção que corresponde ao filter. O campo sort pode ser usado para influenciar qual documento será modificado.

Projeção

Importante

Consistência de linguagem

Como parte da criação da projeção find() e findAndModify() consistente com o estágio $project da agregação,

A projeção find() e findAndModify() 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 `$` para retornar o primeiro elemento que corresponde à condição de consulta no campo de array. Se você especificar um número inteiro diferente de zero para o valor de projeção, a operação tratará o valor como `true`. Não disponível para visualizações.
`<field>: <array projection>`	Usa os operadores de projeção de array (`$elemMatch`, `$slice`) para especificar os elementos da array a serem incluídos. 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. Se você especificar um literal não numérico e não booleano (como uma string literal ou uma array ou uma expressão de operador) para o valor de projeção, o campo será projetado com o novo valor, por exemplo: `{ field: [ 1, 2, 3, "$someExistingField" ] }` `{ field: "New String Value" }` `{ field: { status: "Active", total: { $sum: "$existingArray" } } }` Para projetar um valor literal para um campo, use a expressão de aggregation `$literal`, por exemplo: `{ field: { $literal: 5 } }` `{ field: { $literal: true } }` `{ field: { $literal: { fieldWithValue0: 0, fieldWithValue1: 1 } } }`

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>
formato 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:

Campos do projeto para retornar da consulta

Coleções fragmentadas

Os documentos em uma coleção fragmentada podem não ter campos de chave de fragmento. Para direcionar um documento que não tem a chave de fragmento, você pode usar a correspondência de igualdade nullem 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.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 repetível.
Você deve incluir um filtro de igualdade na chave de shard completa.

Chave de fragmento ausente

Documentos em uma coleção fragmentada podem estar sem os campos de chave de fragmento. Para usar db.collection.findOneAndReplace() para definir a chave de fragmento 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:

Campos de chave de fragmentação ausentes

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 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.findOneAndReplace() 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.

Entradas de oplog

Se uma operação db.collection.findOneAndReplace() substituir um documento com êxito, a operação adicionará uma entrada no oplog (log de operações). Se a operação falhar ou não encontrar 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 do 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 operação a seguir 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

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" }

Voltar

db.collection.findOneAndDelete

db.collection.findOneAndUpdate

Definição

Compatibilidade

Observação

Sintaxe

Campos e opções

Devoluções

Comportamento

Correspondência de documento

Projeção

Importante

Consistência de linguagem

Especificação de campo incorporada

_id Projeção de campo

Inclusão ou exclusão

Coleções fragmentadas

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

Entradas de oplog

Exemplos

Substituir um documento

Classificar e Substituir um documento

Campos Específicos do Projeto no Documento de Devolução

Substituir documento por limite de tempo

Substituir Documento por Upsert

Especifique o agrupamento

`_id` Projeção de campo