$replaceOne (Substituir a Primeira Correspondência)
Última atualização: 2026-10-09
$replaceOne (Substituir a Primeira Correspondência)
$replaceOne substitui a primeira ocorrência de uma substring em uma string por uma substituição fornecida — útil para correções de erros de digitação ou trocas de prefixo. find deve ser uma string não vazia, ou gera erro; quando find não ocorre, a entrada é retornada inalterada. É uma substituição literal, sem suporte a regex — use $regexReplace para padrões. Entrada null ou ausente resulta em null.
| Categoria | String |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $replaceOne: { input: <expressão de string>, find: <procura>, replacement: <substituição> } }⚙️ Parâmetros
| input | Obrigatório; a string a processar. |
|---|---|
| find | Obrigatório; uma string de pesquisa não vazia. |
| replacement | Obrigatório; a string de substituição. |
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):
// $replaceOne: corrigir um erro de digitação nos corpos das postagens
db.posts.aggregate([
{ $project: { fixed: { $replaceOne: { input: '$body', find: 'teh', replacement: 'the' } } } }
])Saída：
{ "_id": 1, "fixed": "the quick brown fox" }
{ "_id": 2, "fixed": "no typo here" }📌 Notas
- Substitui apenas a primeira ocorrência
- Um find vazio gera erro
- Quando find está ausente, a entrada é retornada inalterada
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QPode substituir todas as ocorrências?
ANão — use $replaceAll para todas as ocorrências.
Qfind pode ser uma string vazia?
ANão — ele gera erro.
QSuporta regex?
ANão — use $regexReplace para substituição por padrão.
