$replaceAll (agregação)

Nesta página

Definição

Sintaxe
Comportamento
Exemplo

Definição

$replaceAll

Substitui todas as instâncias de uma string de pesquisa em uma string de entrada por uma string de substituição.

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

Sintaxe

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

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

Campos do operador

Campo	Descrição
Entrada	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, `$replaceAll` retornará `null`.
find	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, `$replaceAll` retornará `null`.
substituição	A string a usar para substituir todas as instâncias correspondentes de localização na entrada. Pode ser qualquer expressão válida que resolva para uma string ou um `null`.

Comportamento

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

`$replaceAll` 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 $replaceAll equivalerá a null:

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

`$replaceAll` e agrupamento

A correspondência de strings para todas as expressões $replaceAll sempre diferencia maiúsculas, minúsculas e diacríticos. Qualquer agrupamento configurado em uma coleção, db.collection.aggregate() ou índice é ignorado ao executar comparações de strings com $replaceAll.

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 a seguir de $replaceAll tenta localizar e substituir todas as instâncias de "Cafe" no campo name:

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

Como $replaceAll 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.

`$replaceAll` e normalização Unicode

A expressão de agregação $replaceAll não executa nenhuma normalização unicode. Isso significa que a correspondência de strings de todas as expressões $replaceAll 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 $replaceAll 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
`{ $replaceAll: { input: "caf\xe9", find: "café", replacement: "CAFE" } }`	sim
`{ $replaceAll: { input: "cafe\u0301", find: "café", replacement: "CAFE" } }`	no

Como $replaceAll 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 cada instância de "tinta azul" no campo item por "tinta vermelha":

db.inventory.aggregate([
   {
     $project:
      {
         item: { $replaceAll: { 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 red paintbrush" }
{ "_id" : 4, "item" : "red paint with green paintbrush" }

Voltar

$replaceOne

$reverseArray