Filtrar a pesquisa personalizada para dados estruturados ou não estruturados

Se você tiver um app de pesquisa que usa dados estruturados ou não estruturados com metadados, poderá usar os metadados para filtrar suas consultas de pesquisa. Esta página explica como usar campos de metadados para restringir a pesquisa a um conjunto específico de documentos.

Observação:outras abordagens para filtros de dados estruturados são:

• Fazer com que o entendimento de linguagem natural crie filtros com base nas consultas dos usuários' Para mais informações, consulte Filtrar com o entendimento de linguagem natural.
• Usar a filtragem de relevância no nível do documento para reduzir o número de resultados retornados. Para mais informações, consulte Filtrar pesquisas por relevância no nível do documento.

Para conferir um exemplo de metadados de filtros de pesquisa, execute o "Metadados de filtros de pesquisa" notebook em um dos seguintes ambientes:

Abrir no Colab | Conferir no GitHub

Exemplo de metadados

Confira este exemplo de metadados para quatro arquivos PDF (document_1.pdf, document_2.pdf, document_3.pdf e document_4.pdf). Esses metadados estariam em um arquivo JSON em um bucket do Cloud Storage, junto com os arquivos PDF. Você pode consultar esse exemplo ao ler esta página.

{"id": "1", "structData": {"title": "Policy on accepting corrected claims", "category": ["persona_A"]}, "content": {"mimeType": "application/pdf", "uri": "gs://bucketname_87654321/data/document_1.pdf"}}
{"id": "2", "structData": {"title": "Claims documentation and reporting guidelines for commercial members", "category": ["persona_A", "persona_B"]}, "content": {"mimeType": "application/pdf", "uri": "gs://bucketname_87654321/data/document_2.pdf"}}
{"id": "3", "structData": {"title": "Claims guidelines for bundled services and supplies for commercial members", "category": ["persona_B", "persona_C"]}, "content": {"mimeType": "application/pdf", "uri": "gs://bucketname_87654321/data/document_3.pdf"}}
{"id": "4", "structData": {"title": "Advantage claims submission guidelines", "category": ["persona_A", "persona_C"]}, "content": {"mimeType": "application/pdf", "uri": "gs://bucketname_87654321/data/document_4.pdf"}}

Sintaxe da expressão de filtro

Entenda a sintaxe da expressão de filtro que você usará para definir o filtro de pesquisa. A sintaxe da expressão de filtro pode ser resumida pelo seguinte formato Backus-Naur estendido:

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };
  # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A parenthetical expression.
    | "(", expression, ")"
    # A simple expression applying to a text field.
    # Function "ANY" returns true if the field exactly matches any of the literals.
    ( text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # A simple expression applying to a numerical field. Function "IN" returns true
    # if a field value is within the range. By default, lower_bound is inclusive and
    # upper_bound is exclusive.
    | numerical_field, ":", "IN", "(", lower_bound, ",", upper_bound, ")"
    # A simple expression that applies to a numerical field and compares with a double value.
    | numerical_field, comparison, double
    # An expression that applies to a geolocation field with text/street/postal address.
    |  geolocation_field, ":", "GEO_DISTANCE(", literal, ",", distance_in_meters, ")"
    # An expression that applies to a geolocation field with latitude and longitude.
    | geolocation_field, ":", "GEO_DISTANCE(", latitude_double, ",", longitude_double, ",", distance_in_meters, ")"
    # Datetime field
    | datetime_field, comparison, literal_iso_8601_datetime_format);
  # A lower_bound is either a double or "*", which represents negative infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  lower_bound = ( double, [ "e" | "i" ] ) | "*";
  # An upper_bound is either a double or "*", which represents infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  upper_bound = ( double, [ "e" | "i" ] ) | "*";
  # Supported comparison operators.
  comparison = "<=" | "<" | ">=" | ">" | "=";
  # A literal is any double quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double quoted string;
  text_field = text field - for example, category;
  numerical_field = numerical field - for example, score;
  geolocation_field = field of geolocation data type - for example home_address, location;
  datetime_field = field of datetime data type - for example creation_date, expires_on;
  literal_iso_8601_datetime_format = either a double quoted string representing ISO 8601 datetime or a numerical field representing microseconds from unix epoch.

Principais propriedades que oferecem suporte à filtragem

Mesmo que um campo de propriedade de chave esteja definido como indexável, ele pode não oferecer suporte a filtragem, facetas e classificação. Por exemplo, não é possível filtrar um campo que é mapeado para a propriedade de chave title.

Os seguintes campos de propriedade de chave podem ser usados para filtragem, facetas e reordenação.

Campos de propriedade de chave para pesquisa personalizada que podem ser usados em filtros, facetas e classificação:

• CATEGORIES (category)
• CREATE_TIME (create_time)
• HASHTAGS (hashtag)
• LANGUAGE_CODE (language_code)
• UPDATE_TIME (update_time)
• URI (uri)

Campos de propriedade de chave para pesquisa de mídia que podem ser usados em filtros, facetas e classificação:

• MEDIA_AVAILABLE_TIME (media_available_time)
• MEDIA_CONTENT_INDEX (media_content_index)
• MEDIA_CONTENT_RATING (media_content_rating)
• MEDIA_COUNTRY_OF_ORIGIN (media_country_of_origin)
• MEDIA_DURATION (media_duration)
• MEDIA_EXPIRE_TIME (media_expire_time)
• MEDIA_FILTER_TAGS (media_filter_tag)
• MEDIA_HASH_TAGS (media_hash_tag)
• MEDIA_IN_LANGUAGES (media_in_language)
• MEDIA_LIVE_EVENT_END_TIME (media_live_event_end_time)
• MEDIA_LIVE_EVENT_START_TIME (media_live_event_start_time)
• MEDIA_PRODUCTION_YEAR (media_production_year)
• MEDIA_TYPE (media_type)

Antes de começar

Crie um app e ingira dados estruturados ou não estruturados com metadados. Para mais informações, consulte Criar um app de pesquisa.

Pesquisar usando um filtro de metadados

Para pesquisar usando um filtro de metadados, siga estas etapas:

1. Determine o campo de metadados a ser usado para filtrar suas consultas de pesquisa.

   Por exemplo, para os metadados em Antes de começar, você pode usar o category campo como um filtro de pesquisa. Ao filtrar dados estruturados, como no exemplo de metadados, especifique o caminho completo para o campo: structData.category. Em seguida, os usuários podem filtrar por persona_A, persona_B ou persona_C, para que a pesquisa seja restrita aos documentos associados à persona de interesse.

2. Tornar o campo de metadados indexável:

   1. No Google Cloud console, acesse a página Aplicativos de IA e no menu de navegação, clique em Apps.

      Acessar a página de apps

   2. Clique no app de pesquisa.

   3. No menu de navegação, clique em Dados.

   4. Clique na guia Esquema. Essa guia mostra as configurações atuais do campo.

      Observação: a guia Esquema aparece apenas para repositórios de dados que contêm dados estruturados ou não estruturados com metadados.

   5. Clique em Editar.

   6. Marque a caixa de seleção Indexável do campo que você quer tornar indexável.

   7. Clique em Salvar. Para mais informações, consulte Configurar as definições de campo.

3. Encontre o ID do app. Se você já tiver o ID do app, pule para a próxima etapa.

   1. No Google Cloud console, acesse a página Aplicativos de IA.

      Acessar "Apps".

   2. Na página Apps, encontre o nome do app e acesse o ID dele na coluna ID.

4. Receber resultados da pesquisa.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   "https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
   -d '{
   "query": "QUERY",
   "filter": "FILTER"
   }'
   

   Substitua:

   • PROJECT_ID: ID do projeto.
   • APP_ID: ID do app.
   • QUERY: o texto da consulta a ser pesquisado.
   • FILTER: opcional. Um campo de texto que permite filtrar um conjunto especificado de campos usando a sintaxe da expressão de filtro. O valor padrão é uma string vazia, o que significa que nenhum filtro é aplicado.

   Por exemplo, digamos que você tenha importado os quatro arquivos PDF com metadados de Antes de começar. Você quer pesquisar documentos que contenham a palavra "reivindicações" e consultar apenas documentos com um valor category de persona_A. Para fazer isso, inclua as seguintes instruções na chamada:

   "query": "claims",
   "filter": "category: ANY(\"persona_A\")"
   

   Para mais informações, consulte a guia REST em Receber resultados da pesquisa de um app com dados estruturados ou não estruturados.

   Clique para conferir um exemplo de resposta.

   Se você realizar uma pesquisa como a do procedimento anterior, poderá receber uma resposta semelhante à seguinte. Observe que a resposta inclui os três documentos que têm um valor category de persona_A.

   {
   "results": [
   {
     "id": "2",
     "document": {
       "name": "projects/abcdefg/locations/global/collections/default_collection/dataStores/search_store_id/branches/0/documents/2",
       "id": "2",
       "structData": {
         "title": "Claims documentation and reporting guidelines for commercial members",
         "category": [
           "persona_A",
           "persona_B"
         ]
       },
       "derivedStructData": {
         "link": "gs://bucketname_87654321/data/document_2.pdf",
         "extractive_answers": [
           {
             "pageNumber": "1",
             "content": "lorem ipsum"
           }
         ]
       }
     }
   },
   {
     "id": "1",
     "document": {
       "name": "projects/abcdefg/locations/global/collections/default_collection/dataStores/search_store_id/branches/0/documents/1",
       "id": "1",
       "structData": {
         "title": "Policy on accepting corrected claims",
         "category": [
           "persona_A"
         ]
       },
       "derivedStructData": {
         "extractive_answers": [
           {
             "pageNumber": "2",
             "content": "lorem ipsum"
           }
         ],
         "link": "gs://bucketname_87654321/data/document_1.pdf"
       }
     }
   },
   {
     "id": "4",
     "document": {
       "name": "projects/abcdefg/locations/global/collections/default_collection/dataStores/search_store_id/branches/0/documents/4",
       "id": "4",
       "structData": {
         "title": "Advantage claims submission guidelines",
         "category": [
           "persona_A",
           "persona_C"
         ]
       },
       "derivedStructData": {
         "extractive_answers": [
           {
             "pageNumber": "47",
             "content": "lorem ipsum"
           }
         ],
         "link": "gs://bucketname_87654321/data/document_4.pdf"
       }
     }
   }
   ],
   "totalSize": 330,
   "attributionToken": "UvBRCgsI26PxpQYQs7vQZRIkNjRiYWY1MTItMDAwMC0yZWIwLTg3MTAtMTQyMjNiYzYzMWEyIgdHRU5FUklDKhSOvp0VpovvF8XL8xfC8J4V1LKdFQ",
   "guidedSearchResult": {},
   "summary": {}
   }
   

Exemplos de expressões de filtro

A tabela a seguir mostra exemplos de expressões de filtro.

Filtro	Retorna apenas resultados para documentos em que:
category: ANY("persona_A")	o campo de texto category é persona_A
score: IN(*, 100.0e)	o campo numérico score é maior que o infinito negativo e menor que 100,0
non-smoking = "true"	o booleano non-smoking é verdadeiro
pet-friendly = "false"	o booleano pet-friendly é falso
manufactured_date = "2023"	a manufactured date é qualquer momento em 2023
manufactured_date >= "2024-04-16"	a manufactured_date é em ou após 16 de abril de 2024
manufactured_date < "2024-04-16T12:00:00-07:00"	a manufactured_date é antes do meio-dia do horário de verão do Pacífico em 16 de abril de 2024
office.location:GEO_DISTANCE("1600 Amphitheater Pkwy, Mountain View, CA, 94043", 500)	o campo de geolocalização office.location está a uma distância de 500 m de 1600 Amphitheater Pkwy
NOT office.location:GEO_DISTANCE("Palo Alto, CA", 1000)	o campo de geolocalização office.location não está em um raio de 1 km de Palo Alto, Califórnia.
office.location:GEO_DISTANCE(34.1829, -121.293, 500)	o campo de geolocalização office.location está em um raio de 500 m da latitude 34,1829 e da longitude -121,293
category: ANY("persona_A") AND score: IN(*, 100.0e)	category é persona_A e score é menor que 100
office.location:GEO_DISTANCE("Mountain View, CA", 500) OR office.location:GEO_DISTANCE("Palo Alto, CA", 500)	office.location está a uma distância de 500 m de Mountain View ou Palo Alto.
(price<175 AND pet-friendly = "true") OR (price<125 AND pet-friendly = "false")	price é menor que 175 e posso levar meu animal de estimação, ou price é menor que 125 e não posso levar meu animal de estimação

Observação: se você usar esses filtros em um comando curl ou em uma linguagem, como Java ou C++, em que as aspas duplas são um caractere reservado, será necessário usar uma barra invertida para escapar das aspas duplas. Portanto, nesses exemplos, você substituiria as ocorrências de " por \".

A seguir

• Para entender o impacto dos filtros na qualidade da pesquisa, avalie a qualidade da pesquisa. Para mais informações, consulte Avaliar a qualidade da pesquisa.