Usar a pesquisa de texto

Use os recursos de pesquisa de texto em Cloud Firestore 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:

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

  2. Verifique se você tem um índice de texto ou crie um.

Permissões do IAM

Para criar um índice no Cloud Firestore, 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. Saiba mais sobre os papéis e as permissões associadas de Cloud Firestoreem 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.