$text (Sistemas autogerenciados)
Observação
Esta página descreve as funcionalidades de consulta de texto para implantações autogerenciadas (não Atlas). Para dados hospedados no MongoDB Atlas, o MongoDB oferece uma solução aprimorada de consulta de texto completo, Atlas Search.
Esta página descreve o operador $text
para implantações autogerenciadas.
Definição
$text
$text
executa uma consulta 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 do MongoDB na nuvem
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
A expressão $text
tem a seguinte sintaxe:
{ $text: { $search: <string>, $language: <string>, $caseSensitive: <boolean>, $diacriticSensitive: <boolean> } }
O operador $text
aceita um documento de consulta de texto com os seguintes campos:
Campo | Tipo | Descrição |
---|---|---|
$search | string | Uma string de termos que o MongoDB analisa e usa para consultar o índice de texto. O MongoDB executa uma consulta lógica OR nos termos, a menos que você especifique os termos 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 consulta e as regras para o stemmer e o tokenizador. Se não especificado, o MongoDB utilizará o idioma padrão do índice. Para os idiomas suportados, consulte Idiomas de pesquisa de texto em implantações autogerenciadas. Se você especificar um valor |
$caseSensitive | booleano | Opcional. Um sinalizador booleano para habilitar ou desabilitar a diferenciação de maiúsculas e minúsculas. O padrão é Para obter mais informações, consulte Insensibilidade a maiúsculas e minúsculas. |
$diacriticSensitive | booleano | Opcional. Um sinalizador booleano para ativar ou desativar a sensibilidade diacrítica em relação aos índices de texto da versão 3 . O padrão é As consultas de texto em 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 das pontuações dos resultados. Para obter mais informações sobre a classificação pelas pontuações dos resultados, consulte a documentação Pontuação de texto.
Comportamento
Restrições
Uma query pode especificar, no máximo, uma expressão
$text
.$text
não pode aparecer em expressões$nor
.$text
não pode aparecer em$elemMatch
expressões de consulta ou$elemMatch
expressões de projeção.Para usar
$text
em uma expressão$or
, todas as cláusulas na array$or
devem ser indexadas.Se uma query incluir uma expressão
$text
, não sera possível usarhint()
para especificar o índice a ser utilizado na query.Não é possível 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 consulta que exige um tipo diferente de índice especial. Por exemplo, você não pode combinar a expressão$text
com o operador$near
.As visualizações não suportam
$text
.$text
não é compatível com a criação de índices usando a Stable API V1.
Se estiver usando o operador $text
na agregação, as restrições a seguir também se aplicam.
O estágio
$match
que inclui um$text
deve ser o primeiro estágio no pipeline.Um operador
$text
só pode ocorrer uma vez no estágio.A expressão do operador
$text
não pode aparecer em expressões$or
ou$not
.$text
, 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 agregação$meta
no estágio$sort
.
$search
Campo
No campo $search
, especifique uma string de palavras que o operador $text
analisa e usa para fazer uma query do í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 ignorada \"
que especifica uma frase.
Observação
O campo $search
para a expressão $text
é diferente do estágio de agregação $search fornecido pelo Atlas Search. O estágio de agregação $search
executa uma pesquisa de texto completo 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, $text
corresponderá somente aos documentos que incluem a frase.
Por exemplo, passou uma string $search
:
"\"ssl certificate\" authority key"
O operador $text
retorna documentos que incluem a frase "ssl
certificate"
.
Observação
Você não pode usar o operador $text
com várias 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 é passada uma string que contém somente palavras negadas, o
$text
não corresponde 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 à operação 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
Quando você não diferencia maiúsculas e minúsculas e também diacríticos, o operador $text
corresponde à palavra radical completa. Se um campo de documento contiver a palavra blueberry
, uma operação $text
com um termo $search
de blue
não terá correspondência. No entanto, blueberry
ou blueberries
terão correspondência.
Sensibilidade a maiúsculas e minúsculas e palavras com haste
Quando você usa sensibilidade a maiúsculas e minúsculas ($caseSensitive: true
), se a base do sufixo contiver letras maiúsculas, o operador $text
corresponderá à palavra exata.
Sensibilidade a diacríticos e palavras derivadas
Quando você usa a confidencialidade diacrítica ($diacriticSensitive: true
), se a base do sufixo contiver a marca ou marcas diacríticas, o operador $text
corresponderá à palavra exata.
Insensibilidade a maiúsculas e minúsculas
O operador $text
usa como padrão a falta de diferenciação de 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 dar suporte à diferenciação de maiúsculas e minúsculas onde o índice text
não faz essa diferenciação, especifique $caseSensitive: true
.
Processo com diferenciação entre maiúsculas e minúsculas
Se $caseSensitive: true
e o índice text
não diferenciarem maiúsculas de minúsculas, o operador $text
:
Primeiro, faz query no índice
text
em busca de correspondências sem diferenciação de maiúsculas e minúsculas e diacríticos.Em seguida, para obter apenas os documentos que correspondem ao padrão de maiúsculas e minúsculas dos termos especificados, a operação
$text
inclui um estágio adicional para filtrar os documentos que não correspondem ao padrão especificado.
Se $caseSensitive: true
e se a base do sufixo contiver letras maiúsculas, o operador $text
encontrará correspondência para a palavra exata.
Especificar $caseSensitive: true
pode afetar o desempenho.
Insensibilidade a diacríticos
O operador $text
tem como padrão a falta de detecção de 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 permitir diferenciar diacríticos com o índice text
, especifique $diacriticSensitive: true
.
As queries de texto em versões anteriores do índice text
já diferenciam diacríticos de forma inerente e não é possível alterar isso. Dessa forma, a opção $diacriticSensitive
para o operador $text
não tem efeito com versões anteriores do índice text
.
Processo de diferenciação de diacríticos
Para usar a diferenciação de diacríticos ($diacriticSensitive: true
) com um índice text
de versão 3, o operador $text
:
Primeiro consulta 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 especificados, a operação
$text
inclui um estágio adicional para filtrar os documentos que não têm correspondência.
Especificar $diacriticSensitive: true
pode afetar o desempenho.
Se você usar $diacriticSensitive: true
com uma versão anterior do índice text
, o operador $text
consultará o índice text
, que diferencia diacríticos.
Se $diacriticSensitive: true
e se o radical do sufixo contiver a marca ou marcas diacríticas, o operador $text
encontrará correspondência para a palavra exata.
Pontuação de texto
O operador $text
atribui uma pontuação a cada documento de resultado. A pontuação representa a relevância de um documento para uma determinada query. 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" }
apresenta 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 classificaçã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 } ] )
$text
com uma única palavra
O exemplo a seguir especifica uma string $search
de coffee
:
db.articles.find( { $text: { $search: "coffee" } } )
Essa operação 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 }
Corresponde a qualquer um $search
dos termos da
Se a string $search
for uma string delimitada por espaço, $text
executará uma operação lógica OR
em cada termo e retornará documentos que contenham qualquer um dos termos.
O exemplo 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" } } )
Esta operação retorna documentos que contêm bake
ou coffee
ou cake
no campo subject
indexado ou, mais precisamente, a versão derivada dessas 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 }
$text
com uma frase
Para corresponder à frase exata em um único termo, evite as aspas.
O exemplo a seguir faz correspondência da frase coffee shop
:
db.articles.find( { $text: { $search: "\"coffee shop\"" } } )
Essa operação retorna documentos que contêm a frase coffee shop
:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 }
O exemplo a seguir corresponde às 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\'" } } )
Essa operação 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 } ]
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 faz a correspondência de documentos que contêm a palavra coffee
, mas não contêm o termo shop
ou, mais precisamente, a versão derivada das palavras:
db.articles.find( { $text: { $search: "coffee -shop" } } )
A operação retorna os seguintes documentos:
{ "_id" : 7, "subject" : "coffee and cream", "author" : "efg", "views" : 10 } { "_id" : 1, "subject" : "coffee", "author" : "xyz", "views" : 50 }
Consultar 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 $search
.
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.
O exemplo a seguir 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" } } )
O exemplo 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 em implantações autogerenciadas para obter os idiomas com suporte.
Não diferenciação entre maiúsculas e minúsculas e diacríticos
O operador $text
adia a insensibilidade a maiúsculas e minúsculas e diacríticos do índice text
. O índice text
versão 3 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 saber mais, consulte Insensibilidade a maiúsculas e minúsculas do índice de texto e Insensibilidade a diacríticos do índice de texto.
O exemplo a seguir realiza uma query 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 versão 3 text
, a operação 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.
Diferenciação entre maiúsculas e minúsculas
Para habilitar a diferenciação entre maiúsculas e minúsculas, especifique $caseSensitive: true
. A especificação de $caseSensitive: true
pode afetar o desempenho.
Sensibilidade a maiúsculas e minúsculas com um termo
O exemplo a seguir executa uma query que diferencia maiúsculas de minúsculas para o termo Coffee
:
db.articles.find( { $text: { $search: "Coffee", $caseSensitive: true } } )
A operação corresponde apenas ao seguinte documento:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 }
Diferenciação de maiúsculas e minúsculas com uma frase
O exemplo a seguir executa uma query que diferencia maiúsculas de minúsculas para a frase Café Con Leche
:
db.articles.find( { $text: { $search: "\"Café Con Leche\"", $caseSensitive: true } } )
A operação corresponde apenas ao seguinte 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 diferenciação de maiúsculas e minúsculas para termos negados.
O exemplo a seguir executa uma query 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 operação faz a correspondência do seguinte documento:
{ "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg" }
Sensibilidade a diacríticos
Para habilitar a diferenciação de diacríticos com um índice de texto da versão 3, especifique $diacriticSensitive: true
. A especificação de $diacriticSensitive: true
pode impactar o desempenho.
Diferenciação de diacríticos com um termo
O exemplo a seguir executa uma query de texto que diferencia diacríticos no termo CAFÉ
ou, mais precisamente, na versão derivada da palavra:
db.articles.find( { $text: { $search: "CAFÉ", $diacriticSensitive: true } } )
A operação 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.
O exemplo a seguir executa uma query de texto com distinção de diacríticos para documentos 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 operação faz a correspondência do seguinte documento:
{ "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz" }
Exemplos de pontuação de relevância
Retornar à Pontuação de Relevância
O exemplo a seguir executa uma query de texto para o termo cake
e usa o operador $meta
no documento de projeção para anexar 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 }
Classificar por pontuação de relevância
Você pode especificar a expressão
{ $meta: "textScore" }
nosort()
sem especificar também 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 sem projetar o
textScore
.Se você incluir a expressão
{ $meta: "textScore" }
na projeção esort()
, os documentos de projeção e classificação poderão ter nomes de campo diferentes para a expressão.For example, in the following operation, the projection uses a field namedscore
for the expression and thesort()
uses the field namedignoredName
.db.articles.find( { $text: { $search: "cake" } } , { score: { $meta: "textScore" } } ).sort( { ignoredName: { $meta: "textScore" } } )
Retornar os 2 principais documentos correspondentes
Use o método limit()
em conjunto com um sort()
para retornar os principais documentos n
correspondentes.
O exemplo a seguir faz uma query do termo coffee
e ordena os resultados pela pontuação decrescente, limitando os resultados aos dois principais documentos com correspondência:
db.articles.find( { $text: { $search: "coffee" } }, { score: { $meta: "textScore" } } ).sort( { score: { $meta: "textScore" } } ).limit(2)
$text com query adicional e expressões de ordenação
O exemplo a seguir corresponde a 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 de relevância decrescente:
db.articles.find( { author: "xyz", $text: { $search: "coffee bake" } }, { score: { $meta: "textScore" } } ).sort( { date: 1, score: { $meta: "textScore" } } )