Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Operações de agregação
/
Referência
/
Operadores

$replaceOne (agregação)

Nesta página

  • Definição
  • Sintaxe
  • Comportamento
  • Exemplo

Definição

$replaceOne

Substitui a primeira instância de uma string de pesquisa em uma string de entrada por uma string de substituição.

Se nenhuma ocorrência for localizada, $replaceOne avaliará para a string de entrada.

$replaceOne diferencia maiúsculas de minúsculas e diacríticos e ignora qualquer agrupamento presente em uma collection.

Sintaxe

O operador $replaceOne tem a seguinte sintaxe de expressão do operador:

{ $replaceOne: { input: <expression>, find: <expression>, replacement: <expression> } }

Campos do operador

Campo
Descrição

A string em que você deseja aplicar a localização. Pode ser qualquer expressão válida que resolva para uma string ou um null. Se input referir-se a um campo ausente, $replaceOne retornará null.

A string a pesquisar na entrada dada. Pode ser qualquer expressão válida que resolva para uma string ou um null. Se find referir-se a um campo ausente, $replaceOne retornará null.

A string a utilizar para substituir a primeira instância correspondente de localizar na entrada. Pode ser qualquer expressão válida que resolva para uma string ou um null.

Comportamento

Se nenhuma ocorrência de encontrar for encontrada na entrada, $replaceOne será avaliado como a string de entrada.

As expressões entrada, localização e substituição devem ser avaliadas como uma string ou um null. Caso contrário, $replaceOne falhará com um erro.

$replaceOne e valores nulos

Se a entrada ou localizar se referirem a um campo ausente, elas retornarão null.

Se qualquer uma de entrada, localização ou substituição equivalerem a um null, toda a expressão $replaceOne equivalerá a null:

Exemplo
Resultado
{ $replaceOne: { input: null, find: "abc", replacement: "ABC" } }
null
{ $replaceOne: { input: "abc", find: null, replacement: "ABC" } }
null
{ $replaceOne: { input: "abc", find: "abc", replacement: null } }
null

$replaceOne e agrupamento

A correspondência de strings para todas as expressões $replaceOne sempre diferencia maiúsculas, minúsculas e diacríticos. Todo agrupamento configurado é ignorado na realização de comparações de strings com $replaceOne.

Por exemplo, crie uma collection de amostras com força de agrupamento 1:

db.createCollection( "myColl", { collation: { locale: "fr", strength: 1 } } )

A força de um agrupamento de 1 compara apenas o caractere base e ignora outras diferenças, como letras maiúsculas, letras minúsculas e diacríticos.

Em seguida, insira três documentos de exemplo:

db.myColl.insertMany([
   { _id: 1, name: "cafe" },
   { _id: 2, name: "Cafe" },
   { _id: 3, name: "café" }
])

A operação $replaceOne a seguir tenta localizar e substituir a primeira instância de "Cafe" no campo name:

db.myColl.aggregate([
  {
    $addFields:
      {
        resultObject: { $replaceOne: { input: "$name", find: "Cafe", replacement: "CAFE" } }
      }
  }
])

Como $replaceOne ignora o agrupamento configurado para essa coleção, a operação só corresponde à instância de "Cafe" no documento 2:

{ "_id" : 1, "name" : "cafe", "resultObject" : "cafe" }
{ "_id" : 2, "name" : "Cafe", "resultObject" : "CAFE" }
{ "_id" : 3, "name" : "café", "resultObject" : "café" }

Os operadores que respeitam o agrupamento, como $match, corresponderiam a todos os três documentos ao realizar uma comparação de strings de "Cafe" devido à força de agrupamento dessa collection de 1.

$replaceOne e normalização Unicode

A expressão de agregação $replaceOne não executa nenhuma normalização unicode. Isso significa que a correspondência de strings de todas as expressões $replaceOne considerará o número de pontos de código utilizados para representar um caractere em unicode ao tentar uma correspondência.

Por exemplo, o caractere é pode ser representado em unicode usando um ou dois pontos de código:

Unicode
Aparece como
Pontos de código
\xe9
é
1 ( \xe9 )
e\u0301
é
2 ( e + \u0301 )

Usar $replaceOne com uma string de localizar em que o caractere é é representado em unicode com um ponto de código não corresponderá a nenhuma instância de é que utilize dois pontos de código na string de entrada.

A tabela a seguir mostra se há alguma correspondência para a string localização de "café" quando comparada a strings entrada em que é é representada por um ou dois pontos de código. A string localização nesse exemplo utiliza um ponto de código para representar o caractere é:

Exemplo
corresponder
{ $replaceOne: { input: "caf\xe9", find: "café", replacement: "CAFE" } }
sim
{ $replaceOne: { input: "cafe\u0301", find: "café", replacement: "CAFE" } }
no

Como $replaceOne não executa nenhuma normalização unicode, somente a primeira comparação de string corresponde, em que ambas as strings de localizar e entrada utilizam um ponto de código para representar é.

Exemplo

Cria uma collection inventory com os seguintes documentos:

db.inventory.insertMany([
   { "_id" : 1, "item" : "blue paint" },
   { "_id" : 2, "item" : "blue and green paint" },
   { "_id" : 3, "item" : "blue paint with blue paintbrush" },
   { "_id" : 4, "item" : "blue paint with green paintbrush" },
])

O exemplo a seguir substitui a primeira instância de "blue paint" no campo item por "red paint":

db.inventory.aggregate([
   {
     $project:
      {
         item: { $replaceOne: { input: "$item", find: "blue paint", replacement: "red paint" } }
      }
   }
])

A operação retorna os seguintes resultados:

{ "_id" : 1, "item" : "red paint" }
{ "_id" : 2, "item" : "blue and green paint" }
{ "_id" : 3, "item" : "red paint with blue paintbrush" }
{ "_id" : 4, "item" : "red paint with green paintbrush" }

Observe que, com o documento 3, somente a primeira instância correspondente de "blue print" é substituída.

Voltar

$regexMatch

Próximo

$replaceAll