Página inicial do Docs → Desenvolver aplicações → Manual do MongoDB
$text
Observação
Esta página descreve os recursos de pesquisa de texto para sistemas autogerenciados (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução aprimorada de pesquisa de texto completo, oAtlas Search.
Esta página descreve o operador $text
para sistemas managed.
Definição
$text
$text
executa uma pesquisa de texto no conteúdo dos campos indexados com um índice de texto.
Compatibilidade
Você pode utilizar o $text
para implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão código-disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
Uma expressão $text
tem a seguinte sintaxe:
{ $text: { $search: <string>, $language: <string>, $caseSensitive: <boolean>, $diacriticSensitive: <boolean> } }
O operador $text
aceita um documento de query de texto com os seguintes campos:
Campo | Tipo | Descrição |
---|---|---|
$search | string | Uma sequência de termos que o MongoDB analisa e usa para consultar o índice de texto. O MongoDB realiza uma pesquisa OR lógica dos termos, a menos que seja especificado como uma frase. Para obter mais informações sobre o campo, consulte Comportamento. |
$language | string | Opcional. O idioma que determina a lista de palavras de parada para a pesquisa e as regras para o stemmer e o tokenizer. Se não for especificado, a pesquisa utilizará o idioma padrão do índice. Para obter os idiomas suportados, consulte Idiomas de pesquisa de texto. Se você especificar um valor |
$caseSensitive | boleano | Opcional. Um sinalizador booleano para habilitar ou desabilitar a pesquisa sensível a maiúsculas e minúsculas. O padrão é Para obter mais informações, consulte Insensibilidade a maiúsculas e minúsculas. |
$diacriticSensitive | boleano | Opcional. Um sinalizador booleano para habilitar ou desabilitar a pesquisa sensível de diacríticos nos índices de texto da versão 3. O padrão é Pesquisas de texto em relação a versões anteriores do índice de texto são inerentemente sensíveis a diacríticos e não podem ser insensíveis a diacríticos. Assim, a opção Para obter mais informações, consulte Insensibilidade a diacríticos. |
O operador $text
, por padrão, não retorna resultados classificados em termos de pontuações dos resultados. Para obter mais informações sobre a classificação pelas pontuações de pesquisa de texto, consulte a documentação Pontuação de texto .
Comportamento
Restrições
Uma query pode especificar, no máximo, uma expressão
$text
.A query
$text
não pode aparecer em expressões$nor
.A query
$text
não pode aparecer em expressões de query$elemMatch
ou expressões de projeção$elemMatch
.Para utilizar uma query
$text
em uma expressão$or
, todas as cláusulas na array$or
devem ser indexadas.Se uma query incluir uma expressão
$text
, você não poderá usarhint()
para especificar o índice a ser usado na query.Você não pode especificar a ordem de classificação
$natural
se a query incluir uma expressão$text
.Você não pode combinar a expressão
$text
, que exige um índice de texto especial, com um operador de query que exige um tipo diferente de índice especial. Por exemplo, você não pode combinar a expressão$text
com o operador$near
.Os modos de exibição não oferecem suporte à pesquisa de texto.
$text
não é suportado para criar índices utilizando a API estável V1.
Se estiver usando o operador $text
em agregação, as seguintes restrições também se aplicarão.
O estágio
$match
que inclui um$text
deve ser o primeiro estágio no pipeline.Um operador
$text
pode ocorrer somente uma vez no estágio.A expressão do operador
$text
não pode aparecer em expressões$or
ou$not
.A pesquisa de texto, por padrão, não retorna os documentos correspondentes na ordem das pontuações correspondentes. Para classificar por pontuação decrescente, use a expressão de aggregation
$meta
no estágio$sort
.
$search
Campo
No campo $search
, especifique uma string de palavras que o operador $text
analisa e utiliza para query o índice de texto.
O operador $text
trata a maior parte da pontuação na string como delimitadores, exceto um hífen/sinal de menos (-
) que nega o termo ou uma aspa dupla evitada \"
que especifica uma frase.
Observação
O campo $search
para a expressão $text
é diferente do estádio de aggregation $search fornecido pelo Atlas Search. O estágio de aggregation $search
executa a full text search em campos especificados e está disponível somente no MongoDB Atlas.
Frases
Para corresponder em uma frase, em oposição a termos individuais, coloque a frase entre aspas duplas (\"
), como em:
"\"ssl certificate\""
Se a string $search
de uma operação $text
incluir uma frase e termos individuais, a pesquisa de texto corresponderá somente aos documentos que incluem a frase.
Por exemplo, passou uma string $search
:
"\"ssl certificate\" authority key"
O operador $text
pesquisar a frase "ssl
certificate"
.
Observação
Você não pode usar o operador $text
para pesquisar diversas frases.
Negações
Prefixar uma palavra com um hífen/sinal de menos (-
) nega uma palavra:
A palavra negada exclui documentos que contêm a palavra negada do conjunto de resultados.
Quando for passada uma string de pesquisa que contém apenas palavras negadas, a pesquisa de texto não corresponderá a nenhum documento.
Uma palavra hifenizada, como
pre-market
, não é uma negação. Se usado em uma palavra hifenizada, o operador$text
trata o hífen/sinal de menos (-
) como delimitador. Para negar a palavramarket
nesta instância, inclua um espaço entrepre
e-market
, ou seja,pre -market
.
O operador $text
adiciona todas as negações à query com o operador AND
lógico.
Operação de correspondência
Palavras vazias
O operador $text
ignora palavras vazias específicas do idioma, como the
e and
em inglês.
Palavras derivadas
Para pesquisas de texto sem distinção entre maiúsculas e minúsculas e diacríticos, o operador $text
corresponde à palavra derivada completa. Portanto, se um campo do documento contiver a palavra blueberry
, uma pesquisa sobre o termo blue
não corresponderá. No entanto, blueberry
ou blueberries
será compatível.
Pesquisa sensível a maiúsculas e minúsculas e palavras derivadas
Para pesquisas sensíveis a maiúsculas e minúsculas (ou seja, $caseSensitive: true
), se a base do sufixo contiver letras maiúsculas, o operador $text
corresponderá à palavra exata.
Pesquisa sensível a diacríticos e palavras derivadas
Para pesquisas sensíveis a diacríticos (ou seja, $diacriticSensitive: true
), se a base do sufixo contiver diacríticos, o operador $text
corresponderá à palavra exata.
Insensibilidade a maiúsculas e minúsculas
O operador $text
usa como padrão a insensibilidade a maiúsculas e minúsculas do índice de texto :
O índice de texto versão 3 diferencia maiúsculas de minúsculas para caracteres latinos com ou sem diacríticos e caracteres de alfabetos não latinos, como o alfabeto cirílico. Consulte o índice de texto para obter detalhes.
As versões anteriores do índice
text
não diferenciam maiúsculas de minúsculas para caracteres latinos sem diacríticos, ou seja, para[A-z]
.
$caseSensitive
Opção
Para oferecer suporte à pesquisa sensível a maiúsculas e minúsculas em que o índice text
não diferencia maiúsculas de minúsculas, especifique $caseSensitive: true
.
Processo de pesquisa sensível a maiúsculas e minúsculas
Ao realizar uma pesquisa sensível a maiúsculas e minúsculas ($caseSensitive: true
) em que o índice text
não diferencia maiúsculas de minúsculas, o operador $text
:
Primeiro, pesquisa o índice
text
em busca de correspondências sem diferenciação de maiúsculas e minúsculas e diacríticos.Em seguida, para retornar apenas os documentos que correspondem às maiúsculas e minúsculas dos termos da pesquisa, a operação de query
$text
inclui um estágio adicional para filtrar os documentos que não correspondem às maiúsculas e minúsculas especificadas.
Para pesquisas sensíveis a maiúsculas e minúsculas (ou seja, $caseSensitive: true
), se a base do sufixo contiver letras maiúsculas, o operador $text
corresponderá à palavra exata.
Especificar $caseSensitive: true
pode afetar o desempenho.
Dica
Veja também:
Insensibilidade a diacríticos
O operador $text
tem como padrão a insensibilidade a diacríticos do índice de texto :
O índice de texto versão 3 é insensível a diacríticos. Ou seja, o índice não faz distinção entre caracteres que contêm diacríticos e sua contraparte sem sinais, como
é
,ê
ee
.Versões anteriores do índice
text
são sensíveis a diacríticos.
$diacriticSensitive
Opção
Para suportar pesquisa de texto sensível a diacríticos no índice text
, especifique $diacriticSensitive: true
.
As pesquisas de texto em versões anteriores do índice text
são inerentemente sensíveis a diacríticos e não podem ser insensíveis a diacríticos. Dessa forma, a opção $diacriticSensitive
para o operador $text
não tem efeito com versões anteriores do índice text
.
Processo de pesquisa sensível a diacríticos
Para executar uma pesquisa de texto sensível a diacríticos ($diacriticSensitive:
true
) em relação a um índice 3 text
versão, o operador $text
:
Primeiro pesquisa o índice
text
, que não faz distinção entre diacríticos.Em seguida, para retornar apenas os documentos que correspondem aos caracteres com diacríticos dos termos da pesquisa, a operação de query
$text
inclui um estágio adicional para filtrar os documentos que não correspondem.
Especificar $diacriticSensitive: true
pode afetar o desempenho.
Para executar uma pesquisa sensível a diacríticos em relação a uma versão anterior do índice text
, o operador $text
pesquisa o índice text
, que é sensível a diacríticos.
Para pesquisas sensíveis a diacríticos, se a base do sufixo contiver diacríticos, o operador $text
corresponderá à palavra exata.
Dica
Veja também:
Pontuação de texto
O operador $text
atribui uma pontuação a cada documento que contém o termo de pesquisa nos campos indexados. A pontuação representa a relevância de um documento para determinada query de pesquisa de texto. A pontuação pode ser parte de uma especificação de método sort()
, bem como parte da expressão de projeção. A expressão { $meta: "textScore" }
fornece informações sobre o processamento da operação $text
. Consulte o operador de projeção $meta
para obter detalhes sobre como acessar a pontuação para projeção ou ordenação.
Exemplos
Os exemplos a seguir pressupõem uma collection articles
que tenha um índice de texto versão 3 no campo subject
:
db.articles.createIndex( { subject: "text" } )
Preencha a collection com os seguintes documentos:
db.articles.insertMany( [ { _id: 1, subject: "coffee", author: "xyz", views: 50 }, { _id: 2, subject: "Coffee Shopping", author: "efg", views: 5 }, { _id: 3, subject: "Baking a cake", author: "abc", views: 90 }, { _id: 4, subject: "baking", author: "xyz", views: 100 }, { _id: 5, subject: "Café Con Leche", author: "abc", views: 200 }, { _id: 6, subject: "Сырники", author: "jkl", views: 80 }, { _id: 7, subject: "coffee and cream", author: "efg", views: 10 }, { _id: 8, subject: "Cafe con Leche", author: "xyz", views: 10 } ] )
Pesquisar uma única palavra
A seguinte query especifica uma string $search
de coffee
:
db.articles.find( { $text: { $search: "coffee" } } )
Essa query retorna os documentos que contêm o termo coffee
no campo subject
indexado ou, mais precisamente, a versão derivada da palavra:
{ _id: 1, subject: 'coffee', author: 'xyz', views: 50 }, { _id: 7, subject: 'coffee and cream', author: 'efg', views: 10 }, { _id: 2, subject: 'Coffee Shopping', author: 'efg', views: 5 }
Dica
Corresponder a qualquer um dos termos da pesquisa
Se a string de pesquisa for uma string delimitada por espaço, o operador $text
executará uma pesquisa OR
lógica em cada termo e retornará documentos que contenham qualquer um dos termos.
A query a seguir especifica uma string $search
de três termos delimitados por espaço, "bake coffee cake"
:
db.articles.find( { $text: { $search: "bake coffee cake" } } )
Essa query retorna documentos que contêm bake
ou coffee
ou cake
no campo subject
indexado ou, mais precisamente, a versão derivada destas palavras:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 } { "_id" : 7, "subject" : "coffee and cream", "author" : "efg", "views" : 10 } { "_id" : 1, "subject" : "coffee", "author" : "xyz", "views" : 50 } { "_id" : 3, "subject" : "Baking a cake", "author" : "abc", "views" : 90 } { "_id" : 4, "subject" : "baking", "author" : "xyz", "views" : 100 }
Dica
Pesquisar uma frase
Para corresponder à frase exata em um único termo, evite as aspas.
A query a seguir pesquisa a frase coffee shop
:
db.articles.find( { $text: { $search: "\"coffee shop\"" } } )
Esta query retorna documentos que contêm a frase coffee shop
:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 }
A query a seguir pesquisa as frases coffee shop
e Cafe
con Leche
. Este é um OR lógico das duas frases.
db.articles.find( { $text: { $search: "\'coffee shop\' \'Cafe con Leche\'" } } )
Esta query retorna documentos que contêm ambas as frases, incluindo documentos que contêm termos de ambas as frases:
[ { _id: 8, subject: 'Cafe con Leche', author: 'xyz', views: 10 }, { _id: 5, subject: 'Café Con Leche', author: 'abc', views: 200 }, { _id: 1, subject: 'coffee', author: 'xyz', views: 50 }, { _id: 7, subject: 'coffee and cream', author: 'efg', views: 10 }, { _id: 2, subject: 'Coffee Shopping', author: 'efg', views: 5 } ]
Dica
Veja também:
Excluir documentos que contenham um termo
Um termo negado é um termo prefixado por um sinal de menos -
. Se você negar um termo, o operador $text
excluirá os documentos que contêm esses termos dos resultados.
O exemplo a seguir pesquisa documentos que contenham as palavras coffee
, mas não contenham o termo shop
ou, mais precisamente, a versão derivada das palavras:
db.articles.find( { $text: { $search: "coffee -shop" } } )
A consulta retorna os seguintes documentos:
{ "_id" : 7, "subject" : "coffee and cream", "author" : "efg", "views" : 10 } { "_id" : 1, "subject" : "coffee", "author" : "xyz", "views" : 50 }
Dica
Veja também:
Pesquisar um idioma diferente
Use o campo $language
opcional na expressão $text
para especificar um idioma que determine a lista de palavras vazias e as regras para o derivador e o tokenizador para a string de pesquisa.
Se você especificar um valor default_language
de none
, o índice de texto analisará cada palavra no campo, incluindo palavras vazias, e ignorará a derivação do sufixo.
A seguinte query especifica es
, ou seja, Espanhol, como o idioma que determina a tokenização, a derivação e as palavras vazias:
db.articles.find( { $text: { $search: "leche", $language: "es" } } )
A consulta retorna os seguintes documentos:
{ "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 } { "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz", "views" : 10 }
A expressão $text
também pode aceitar o idioma por nome, spanish
. Consulte Idiomas de pesquisa de texto para obter os idiomas suportados.
Dica
Veja também:
Pesquisa insensível a maiúsculas e minúsculas e diacríticos
O operador $text
adia a insensibilidade a maiúsculas e minúsculas do índice text
. O índice 3 text
versão não faz distinção entre diacríticos e expande sua distinção entre maiúsculas e minúsculas para incluir o alfabeto cirílico, bem como caracteres com diacríticos. Para obter detalhes, consulte Insensibilidade a maiúsculas e minúsculas do índice de texto e Insensibilidade a diacríticos do índice de texto.
A query a seguir realiza uma pesquisa de texto sem distinção entre maiúsculas e minúsculas e diacríticos para os termos сы́рники
ou CAFÉS
:
db.articles.find( { $text: { $search: "сы́рники CAFÉS" } } )
Usando o índice text
versão 3, a query corresponde aos documentos a seguir.
{ "_id" : 6, "subject" : "Сырники", "author" : "jkl", "views" : 80 } { "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 } { "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz", "views" : 10 }
Com versões anteriores do índice text
, a query não corresponderia a nenhum documento.
Executar pesquisa sensível a maiúsculas de minúsculas
Para habilitar a pesquisa com distinção entre maiúsculas e minúsculas, especifique $caseSensitive: true
. A especificação de $caseSensitive: true
pode impactar o desempenho.
Pesquisa sensível a maiúsculas e minúsculas de um termo
A query a seguir executa uma pesquisa que diferencia maiúsculas de minúsculas para o termo Coffee
:
db.articles.find( { $text: { $search: "Coffee", $caseSensitive: true } } )
A pesquisa corresponde apenas ao documento:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 }
Pesquisa sensível a maiúsculas e minúsculas de uma frase
A seguinte query executa uma pesquisa sensível a maiúsculas e minúsculas para a frase Café Con Leche
:
db.articles.find( { $text: { $search: "\"Café Con Leche\"", $caseSensitive: true } } )
A pesquisa corresponde apenas ao documento:
{ "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 }
Sensibilidade a maiúsculas e minúsculas com termo negado
Um termo negado é um termo prefixado por um sinal de menos -
. Se você negar um termo, o operador $text
excluirá os documentos que contêm esses termos dos resultados. Você também pode especificar a sensibilidade a maiúsculas e minúsculas para termos negados.
O exemplo a seguir executa uma pesquisa com distinção entre maiúsculas e minúsculas para documentos que contêm a palavra Coffee
, mas não contêm o termo em minúsculas shop
ou, mais precisamente, a versão derivada das palavras:
db.articles.find( { $text: { $search: "Coffee -shop", $caseSensitive: true } } )
A query corresponde ao seguinte documento:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg" }
Pesquisa sensível a diacríticos
Para ativar a pesquisa sensível a diacríticos em um índice de texto versão 3, especifique $diacriticSensitive: true
. A especificação de $diacriticSensitive: true
pode impactar o desempenho.
Pesquisa sensível a diacríticos de um termo
A seguinte query executa uma pesquisa de texto sensível a diacríticos no termo CAFÉ
ou, mais precisamente, na versão derivada da palavra:
db.articles.find( { $text: { $search: "CAFÉ", $diacriticSensitive: true } } )
A query corresponde apenas ao seguinte documento:
{ "_id" : 5, "subject" : "Café Con Leche", "author" : "abc" }
Sensibilidade a diacríticos com termo negado
A opção $diacriticSensitive
também se aplica a termos negados. Um termo negado é um termo prefixado por um sinal de menos -
. Se você negar um termo, o operador $text
excluirá os documentos que contêm esses termos dos resultados.
A query a seguir executa uma pesquisa de texto sensível a diacríticos para o documento que contém o termo leches
, mas não o termo cafés
, ou, mais precisamente, a versão derivada das palavras:
db.articles.find( { $text: { $search: "leches -cafés", $diacriticSensitive: true } } )
A query corresponde ao seguinte documento:
{ "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz" }
Exemplos de pontuação de pesquisa de texto
Retornar a pontuação da pesquisa de texto
A query a seguir executa uma pesquisa de texto para o termo cake
e usa o operador $meta
no documento de projeção para acrescentar a pontuação de relevância a cada documento correspondente:
db.articles.find( { $text: { $search: "cake" } }, { score: { $meta: "textScore" } } )
O documento retornado inclui um campo adicional score
que contém a pontuação de relevância do documento:
{ "_id" : 3, "subject" : "Baking a cake", "author" : "abc", "views" : 90, "score" : 0.75 }
Dica
Veja também:
Ordenar por pontuação de pesquisa de texto
Você pode especificar a expressão
{ $meta: "textScore" }
nosort()
sem também especificar a expressão na projeção. Por exemplo:db.articles.find( { $text: { $search: "cake" } } ).sort( { score: { $meta: "textScore" } } ) Como resultado, você pode ordenar os documentos resultantes por sua relevância de pesquisa sem projetar
textScore
.Se você incluir a expressão
{ $meta: "textScore" }
na projeção e nosort()
, a projeção e a ordenação dos documentos poderão ter nomes de campo diferentes para a expressão.Por exemplo, na seguinte operação, a projeção utiliza um campo denominadoscore
para a expressão esort()
utiliza o campo denominadoignoredName
.db.articles.find( { $text: { $search: "cake" } } , { score: { $meta: "textScore" } } ).sort( { ignoredName: { $meta: "textScore" } } )
No MongoDB 4.2, para ordenar pela pontuação de texto, inclua a mesma expressão
$meta
em ambos o documento de projeção e a expressão de ordenação. A seguinte query pesquisa o termocoffee
e ordena os resultados pela pontuação decrescente:db.articles.find( { $text: { $search: "coffee" } }, { score: { $meta: "textScore" } } ).sort( { score: { $meta: "textScore" } } ) A query retorna os documentos correspondentes ordenados pela pontuação decrescente.
Dica
Veja também:
Retornar os 2 principais documentos correspondentes
Use o método limit()
em conjunto com um sort()
para retornar os principais documentos n
correspondentes.
A query a seguir pesquisa o termo coffee
e ordena os resultados pela pontuação decrescente, limitando os resultados aos dois principais documentos correspondentes:
db.articles.find( { $text: { $search: "coffee" } }, { score: { $meta: "textScore" } } ).sort( { score: { $meta: "textScore" } } ).limit(2)
Dica
Veja também:
Pesquisa de texto com query adicional e expressões de ordenação
A seguinte query pesquisa documentos onde author
é igual a "xyz"
e o campo indexado subject
contém os termos coffee
ou bake
. A operação também especifica uma ordem de classificação de date
crescente e, em seguida, pontuação decrescente da pesquisa de texto:
db.articles.find( { author: "xyz", $text: { $search: "coffee bake" } }, { score: { $meta: "textScore" } } ).sort( { date: 1, score: { $meta: "textScore" } } )