Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/ / /

$text (Sistemas autogerenciados)

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamento
  • Exemplos

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.

$text

$text executa uma consulta de texto no conteúdo dos campos indexados com um índice de texto.

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

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 default_language de none, o índice de texto analisará cada palavra no campo, incluindo palavras vazias, e ignorará a derivação do sufixo.

$caseSensitive
booleano

Opcional. Um sinalizador booleano para habilitar ou desabilitar a diferenciação de maiúsculas e minúsculas. O padrão é false. Se não for especificado, o MongoDB se submete à indiferenciação entre maiúsculas e minúsculas do índice de texto.

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 é false. Se não for especificado, o MongoDB se submete à insensibilidade diacrítica do índice de texto.

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 $diacriticSensitive não tem efeito em versões anteriores do índice text.

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.

  • 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 usar hint() 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.

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.

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.

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 palavra market nesta instância, inclua um espaço entre pre e -market, ou seja, pre -market.

O operador $text adiciona todas as negações à operação com o operador AND lógico.

O operador $text ignora palavras vazias específicas do idioma, como the e and em inglês.

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.

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.

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.

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].

Para dar suporte à diferenciação de maiúsculas e minúsculas onde o índice text não faz essa diferenciação, especifique $caseSensitive: true.

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.

Dica

Veja também:

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 é, ê e e.

  • Versões anteriores do índice text são sensíveis a diacríticos.

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.

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.

Dica

Veja também:

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.

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 }
] )

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 }

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 }

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 }
]

Dica

Veja também:

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 }

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.

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.

Para habilitar a diferenciação entre maiúsculas e minúsculas, especifique $caseSensitive: true. A especificação de $caseSensitive: true pode afetar o desempenho.

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 }

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 }

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" }

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.

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" }

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" }

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 }

Dica

Veja também:

  • Você pode especificar a expressão { $meta: "textScore" } no sort() 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 e sort(), 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 named score for the expression and the sort() uses the field named ignoredName.
    db.articles.find(
    { $text: { $search: "cake" } } ,
    { score: { $meta: "textScore" } }
    ).sort( { ignoredName: { $meta: "textScore" } } )

Dica

Veja também:

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)

Dica

Veja também:

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" } } )

Voltar

Operadores de pesquisa de texto