Observação:a Vertex AI para Pesquisa está sendo renomeada como Pesquisa de agente. Estamos atualizando o conteúdo para refletir o novo branding.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Filtrar pesquisa de mídia

Se você tiver um app de pesquisa de mídia, poderá usar 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 de mídia e um repositório de dados e ingeriu dados. Para mais informações, consulte Criar um repositório de dados de mídia e Criar um app de mídia.

Exemplos de documentos

Analise estes exemplos de documentos de mídia. Você pode consultá-los ao ler esta página.

{"id":"172851","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: Creating the World of Pandora (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/172851\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"243308","schemaId":"default_schema","jsonData":"{\"title\":\"Capturing Avatar (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/243308\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"280218","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: The Way of Water (2022)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\"],\"uri\":\"http://mytestdomain.movie/content/280218\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"72998","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar (2009)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\",\"IMAX\"],\"uri\":\"http://mytestdomain.movie/content/72998\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}

Sintaxe da expressão de 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 formulário 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 );
    # 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;
  datetime_field = field of datetime data type - for example available_time;
  literal_iso_8601_datetime_format = either a double quoted string representing ISO 8601 datetime or a numerical field representing microseconds from unix epoch.

Filtrar a pesquisa de mídia

Para filtrar a pesquisa de mídia usando metadados, siga estas etapas:

Encontre o ID do seu 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 seu app e acesse o ID dele na coluna ID.
Determine o campo ou os campos de documento que você quer filtrar. Por exemplo, para os documentos em Antes de começar, você pode usar o categories campo como um filtro.

Só é possível usar campos indexáveis em expressões de filtro. Para determinar se um campo é indexável, faça o seguinte:
1. No Google Cloud console, acesse a página Aplicativos de IA e no menu de navegação, clique em Repositórios de dados.
  
  Acessar a página Repositórios de dados
2. Clique no nome do seu repositório de dados.
3. Na coluna Nome, clique no repositório de dados.
4. Clique na guia Esquema para conferir o esquema do seu repositório de dados. Se Indexável para o campo for:
  - Selecionado , esse campo estará pronto para ser filtrado na pesquisa. Pule a etapa 3.
  - Não selecionado , siga a etapa 3 para ativar o campo para indexação.
  - Não disponível , o campo não poderá ser indexado.
Para tornar um campo, como o campo categories, filtrável, faça o seguinte:
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 Apps
2. Clique no app de pesquisa de mídia.
3. No menu de navegação, clique em Dados.
4. Clique na guia Esquema. Essa guia mostra as configurações de campo atuais.
5. Clique em Editar.
6. Se ainda não estiver selecionada, marque a caixa de seleção Indexável na linha categories e clique em Salvar.
7. Aguarde seis horas para que a edição do esquema seja propagada. Após seis horas, você poderá passar para a próxima etapa.

Receba os 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 para pesquisar.
FILTER: um campo de texto para filtrar a pesquisa usando uma expressão de filtro.

Por exemplo, suponha que você queira pesquisar os filmes na seção Antes de começar e queira resultados de pesquisa apenas para filmes que: (1) contenham a palavra "avatar" e (2) estejam na categoria "Documentário" . Para fazer isso, inclua as seguintes declarações na chamada:

"query": "avatar",
"filter": "categories: ANY(\"Documentary\")"

Para mais informações, consulte o search método.

Clique para ver 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 apenas os documentários do Avatar.

{
  "results": [
    {
      "id": "243308",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/243308",
        "id": "243308",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "title": "Capturing Avatar (2010)",
          "uri": "http://mytestdomain.movie/content/243308",
          "media_type": "movie"
        }
      }
    },
    {
      "id": "172851",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/172851",
        "id": "172851",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "uri": "http://mytestdomain.movie/content/172851",
          "media_type": "movie",
          "title": "Avatar: Creating the World of Pandora (2010)"
        }
      }
    }
  ],
  "totalSize": 2,
  "attributionToken": "XfBcCgwIvIzJqwYQ2_qNxwMSJDY1NzEzNmY1LTAwMDAtMmFhMy05YWU3LTE0MjIzYmIwOGVkMiIFTUVESUEqII6-nRXFy_MXnIaOIsLwnhXUsp0VpovvF6OAlyKiho4i",
  "guidedSearchResult": {},
  "summary": {}
}

Filtrar documentos disponíveis

Se você quiser que os resultados da pesquisa retornem apenas documentos disponíveis, inclua um filtro para isso nas consultas. Os documentos disponíveis são aqueles em que o available_time está no passado e o expire_time não está especificado ou está definido para uma data futura.

Filtre para retornar apenas documentos que estão disponíveis no momento:

  available_time <= \"DATE_TIME\" AND expire_time > \"DATE_TIME\"

Substitua DATE_TIME pela data atual. Por exemplo, 2025-04-21 ou 2025-04-21T00:00:00Z.

Filtros para classificações, pessoas e organizações

A sintaxe do filtro para classificações de mídia, pessoas e organizações é exclusiva e não segue os padrões acima. Use os exemplos a seguir e os snippets de filtro copiáveis para criar filtros de classificações, pessoas e organizações.

O filtro varia dependendo se você está usando o esquema predefinido do Google ou seu próprio esquema personalizado.

Filtros para classificações, pessoas e organizações (esquema predefinido do Google)

A sintaxe e os exemplos dos filtros de classificação, pessoa e organização são os seguintes:

Filtrar classificações:filtre as classificações de uma determinada fonte.
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
Substitua:
- RATING_SOURCE: a fonte da classificação. Para um esquema predefinido, esse é um valor no campo aggregate_ratings.rating_source.
- OPERATOR: um dos operadores de comparação, <= , < , >= , > ou =
- RATING_SCORE: um valor de classificação no intervalo [1,5]. Para um esquema predefinido, esse é um valor no campo aggregate_ratings.rating_score.
Exemplo: esse filtro restringe a pesquisa a filmes com classificações do IMDB maiores que 2½ estrelas. O valor entre parênteses é resolvido para o valor da classificação do IMDB:
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
Filtrar pessoas:filtre os nomes das pessoas para uma determinada função.
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
Substitua:
- PERSONS_ROLE: para um esquema predefinido, esse é um valor no campo persons.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel ou custom-role).
- NAME_STRING: um ou mais nomes de pessoas com a função especificada. Para comandos curl, como na etapa 4, as aspas duplas precisam ser escapadas com o caractere de barra invertida.
Exemplo: esse filtro restringe a pesquisa a filmes em que um dos atores é Brad Pitt ou Kate Winslet.
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
Filtrar organizações:filtre o nome de uma organização para uma determinada função.
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
Substitua:
- ORG_ROLE: para um esquema predefinido, esse é um valor no campo organizations.role (director, actor, player, team, league, editor, author, character, contributor, creator, editor, funder, producer, provider, publisher, sponsor, translator, music-by, channel ou custom-role).
- NAME_STRING: um ou mais nomes de organizações com a função especificada. Para comandos curl, como na etapa 4, as aspas duplas precisam ser escapadas com o caractere de barra invertida.
Este exemplo restringe a pesquisa a filmes em que a organização de produção é a Walt Disney Studios:
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

Filtros para classificações, pessoas e organizações (esquema personalizado)

Se você usar um esquema personalizado, revise a seção Esquema predefinido do Google e, em seguida, os exemplos nesta seção. Para que os filtros de classificação, pessoa e organização funcionem em um esquema personalizado, os mapeamentos de propriedades precisam ser definidos corretamente. Para informações sobre mapeamentos de propriedades, consulte Esquema personalizado.

Filtro	Propriedades a serem mapeadas
avaliação	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
pessoa	`media_person` `media_person_name` `media_person_role`
org	`media_organization` `media_organization_name` `media_organization_role`

Exemplo de um filtro de classificações para um esquema personalizado

Esse filtro pesquisa filmes que têm uma classificação de 5 estrelas do Rotten Tomatoes:

"filter": "rating(rotten_tomatoes, custom_rating.star_score) = 5"

O rotten_tomatoes é um valor no campo mapeado para media_aggregated_rating_source. O custom_rating.star_score é o campo mapeado para a propriedade de chave media_aggregated_rating.media_aggregated_rating_score.

Exemplo de um filtro de org para um esquema personalizado

Esse filtro pesquisa filmes em que a música foi feita pela Orquestra Sinfônica de Londres ou pela Hollywood Studio Symphony.

"filter: org(music-by, company.id): ANY (\"London Symphony Orchestra\", \"Hollywood Studio Symphony\" )

O company.id é o nome do campo mapeado para a propriedade media_organization_name. E o music-by é um valor no campo de registro da empresa que é mapeado para media_organization_role.

Filtrar pesquisa de mídia Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.