$regexReplace (Substituição com Regex)
Última atualização: 2026-10-09
$regexReplace (Substituição com Regex)
$regexReplace encontra texto com um regex e o substitui por uma string fornecida — uma ferramenta avançada de limpeza de texto em pipelines. A substituição pode referenciar grupos de captura via $1, $2 para fluxos de extrair-e-reconstruir. options suporta flags como i, m, x. Diferente de $replaceAll (apenas literal), $regexReplace trabalha com padrões. Introduzido no MongoDB 4.4. Entrada null resulta em null.
| Categoria | String |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $regexReplace: { input: <expressão de string>, regex: <padrão>, replacement: <substituição>, options: <opções> } }⚙️ Parâmetros
| input | Obrigatório; a string a processar. |
|---|---|
| regex | Obrigatório; uma string de padrão regex compatível com Perl. |
| replacement | Obrigatório; a substituição, com $1/$2 referenciando grupos de captura. |
| options | Sinalizadores opcionais como i, m, x. |
Retorno：A string substituída; null se a entrada for null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $regexReplace: mascarar os 4 dígitos centrais dos números de telefone
db.users.aggregate([
{ $project: { masked: { $regexReplace: { input: '$phone', regex: '(\\d{3})\\d{4}(\\d{4})', replacement: '$1****$2' } } } }
])Saída：
{ "_id": 1, "masked": "138****8000" }
{ "_id": 2, "masked": "139****1234" }📌 Notas
- $1/$2 na substituição referenciam grupos de captura; escape um $ literal
- Diferente de $replaceAll (literal), $regexReplace substitui por padrão
- Sem correspondência significa que a entrada é retornada inalterada
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo referenciar grupos de captura na substituição?
AUse $1, $2 na ordem dos grupos de captura.
QE se nada corresponder?
AA entrada é retornada inalterada.
QQual escolher, $regexReplace ou $replaceAll?
APadrões exigem $regexReplace; trocas literais simples são mais rápidas com $replaceAll.
