$regexFind (Primeira Correspondência de Regex)
Última atualização: 2026-10-09
$regexFind (Primeira Correspondência de Regex)
$regexFind executa uma busca regex compatível com Perl em uma string e retorna a primeira correspondência como um documento (com os campos match, idx e captures), ou null quando nada corresponde. regex recebe o padrão diretamente como string; options aceita flags como i (ignorar maiúsculas/minúsculas) e m (multilinha). Diferente de $regexMatch, ele também retorna grupos de captura, então se encaixa em tarefas de extração e subgrupos.
| Categoria | String |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $regexFind: { input: <expressão de string>, regex: <padrão>, options: <opções> } }⚙️ Parâmetros
| input | Obrigatório; a string a pesquisar. |
|---|---|
| regex | Obrigatório; uma string de padrão regex compatível com Perl. |
| options | Sinalizadores opcionais como i, m, x. |
Retorno：Um documento de correspondência { match, idx, captures }; null quando não há correspondência ou a entrada é null.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $regexFind: extrair um telefone de 11 dígitos dos contatos
db.users.aggregate([
{ $project: { phone: { $regexFind: { input: '$contact', regex: '[0-9]{11}', options: 'i' } } } }
])Saída：
{ "_id": 1, "phone": { "match": "13800138000", "idx": 5, "captures": [] } }
{ "_id": 2, "phone": null }📌 Notas
- Sem correspondência retorna null, não um documento vazio
- captures guarda os grupos de captura; vazio quando não há nenhum
- options suporta i (ignorar maiúsculas/minúsculas), m (multilinha), x (ignorar espaços)
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QNull significa sem correspondência?
ASim — sem correspondência resulta em null; proteja com $ifNull.
QComo obter grupos de captura?
AO campo captures lista os conteúdos dos grupos em ordem.
QOptions consegue combinar flags?
ASim — ex.: 'im' ativa tanto ignorar maiúsculas/minúsculas quanto multilinha.
