Esta página foi traduzida pela API Cloud Translation.

Filtrar a pesquisa genérica de 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.

Antes de começar

Verifique se você criou um app e consumiu dados estruturados ou não estruturados com metadados. Para mais informações, consulte Criar um app de pesquisa.

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 referir-se a este exemplo enquanto lê 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 do filtro

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

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

Pesquisar usando um filtro de metadados

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

Determine o campo de metadados a ser usado para filtrar as consultas de pesquisa. Por exemplo, para os metadados em Antes de começar, é possível usar o campo category como um filtro de pesquisa. 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.
Torne o campo de metadados indexável:
1. No console do Google Cloud, acesse a página Criador de agentes e, no menu de navegação, clique em Apps.
  
  Acessar a página "Apps"
2. Clique no seu 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 Indexable do campo que você quer indexar.
7. Clique em Salvar. Para mais informações, consulte Configurar as configurações de campo.
Encontre o ID do repositório de dados. Se você já tiver o ID do repositório de dados, pule para a próxima etapa.
1. No console do Google Cloud, acesse a página Criador de agentes e, no menu de navegação, clique em Repositórios de dados.
  
  Acesse a página "Repositórios de dados"
2. Clique no nome do seu repositório de dados.
3. Na página Dados do seu repositório de dados, encontre o ID do repositório.

Receber resultados de pesquisa.

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

PROJECT_ID: o ID do seu projeto.
DATA_STORE_ID: o ID do repositório de dados.
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 de 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 tenham a palavra "claims" e consultar apenas documentos com um valor de category igual a 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 de pesquisa para 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, a resposta será semelhante a esta. A resposta inclui os três documentos com um valor de category igual a 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	Só retorna 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\"`	o `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\"`	o `manufactured_date` é antes do meio-dia no 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á dentro de 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á dentro de um raio de 500 m da latitude 34,1829 e 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

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.