Usar consultas de texto

Use os recursos de pesquisa de texto no Firestore com compatibilidade com o MongoDB para pesquisar strings específicas em uma coleção.

Antes de começar

Antes de começar a usar consultas de texto, faça o seguinte:

Verifique se você tem acesso a um banco de dados de operações compatível com o MongoDB ou crie e conecte um banco de dados.
Verifique se você tem um índice de texto ou crie um.

Permissões do IAM

Para criar um índice no Firestore com compatibilidade com o MongoDB, confirme se um dos papéis a seguir foi atribuído:

roles/datastore.owner
roles/datastore.indexAdmin
roles/editor
roles/owner

Para conceder um papel, consulte Conceder um único papel. Para mais informações sobre os papéis do Firestore e as permissões associadas, consulte Papéis predefinidos.

Se você tiver definido papéis personalizados, atribua todas as permissões a seguir para criar índices:

datastore.indexes.create
datastore.indexes.delete
datastore.indexes.get
datastore.indexes.list
datastore.indexes.update

Executar uma consulta de texto

As consultas de texto usam o operador $text em um filtro. Especifique a string consultada no argumento $search.

Executar uma consulta de texto geral

Execute a consulta a seguir para fazer uma consulta geral:

  # Find query
  db.cities.find({ $text: { $search: "french bread" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "french bread" } } }
  ]);

Se o índice for particionado, você poderá filtrar com base na partição incluindo-a em um filtro de igualdade "and" na consulta. Por exemplo, se você tiver uma partição city, poderá filtrar uma consulta de texto da seguinte maneira:

db.myCollection.find( { $and: [
  { $text: { $search: "french bread" } },
  { "city": "Paris" }
] } )

Também é possível filtrar uma agregação com base em uma partição. Exemplo:

db.myCollection.aggregate([
 { $match: { $text: { $search: "french bread" } } },
 { "city": "Paris" }
] );

O valor da sua partição precisa ser uma string. O filtro de particionamento precisa ser combinado à consulta usando um "and".

Definir a linguagem de consulta

É possível definir a linguagem de consulta usando o argumento $language. Exemplo:

  db.cities.find({ $text: { $search: "french bread", $language: "en"} })

Se você não definir o idioma da consulta, ela vai usar o idioma do índice de texto.

Consultar um termo exato

Para consultar um termo exato, configure-o como uma sequência de palavras entre aspas duplas. Exemplo:

  # Find query
  db.cities.find({ $text: { $search: "\"best french bread\"" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "\"best french bread\"" } } },
  ]);

Consultar uma combinação de termos

Para tornar sua consulta mais precisa, especifique uma cadeia de termos. Por exemplo, a consulta a seguir retorna documentos que correspondem à combinação best AND french AND ("bread" OR "is"):

  # Find query
  db.cities.find({ $text: { $search: "\"best\" \"french\" bread is" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "\"best\" \"french\" bread is" } } },
  ]);

Excluir um termo

Para excluir um termo de uma consulta, adicione um hífen (-) antes dele:

  # Find query
  db.cities.find({ $text: { $search: "best bread -french"} })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best bread -french" } } },
  ]);

Calcular a pontuação de relevância

Use a expressão {$meta: "textScore"} para calcular a pontuação de relevância dos documentos correspondentes à consulta de texto. Para classificar os resultados em ordem decrescente de pontuação, use $meta em uma expressão de classificação. Considere os exemplos a seguir, em que SCORE_FIELD é o nome do campo usado para armazenar o valor da pontuação:

  # Find query
  db.cities
    .find({ $text: { $search: "best french bread" } })
    .sort({ SCORE_FIELD: { $meta: "textScore" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best french bread" } } },
    { $sort: { "SCORE_FIELD": { $meta: "textScore"} } },
  ]);

Você também pode usar a pontuação de texto em expressões de projeção. Exemplo:

  # Find query
  db.cities
    .find({ $text: { $search: "best french bread" } })
    .project({ score: { $meta: "textScore" } })

  # Aggregation query
  db.cities.aggregate([
    { $match: { $text: { $search: "best french bread" } } },
    { $project: { "scoreField": { $meta: "textScore"} } },
  ]);

Expandir consulta

Para aumentar a relevância dos resultados da consulta, o operador $text aumenta a string de pesquisa de acordo com o idioma especificado para incluir correspondências de sinônimos sensíveis ao contexto, formas derivadas, termos corrigidos ortograficamente, variações de diacríticos e muito mais.

Limitações

Não é possível usar operadores $near e $text na mesma consulta.
É permitido um único operador $text por consulta find ou aggregation.
Nas agregações, a etapa $match com $text precisa ser a primeira etapa do pipeline.
$text só pode ser aninhado em $and e $or.
Se $text estiver dentro de $or, as disjunções não relacionadas à pesquisa poderão usar índices ordenados atuais para otimizar a consulta. Se os outros disjuntos não forem indexados, a consulta vai depender de uma verificação de coleção.
$text não pode ser usado com dicas de consulta.
As consultas com pesquisa de texto não podem ser classificadas por $natural.