Fornecer ou detectar automaticamente um esquema

Ao importar dados estruturados usando o Google Cloud console, a Pesquisa de agentes detecta automaticamente o esquema. É possível usar esse esquema detectado automaticamente no seu mecanismo ou usar a API para fornecer um esquema que indique a estrutura dos dados.

Se você fornecer um esquema e atualizá-lo mais tarde com um novo, o novo esquema precisará ser compatível com o original. Caso contrário, a atualização do esquema falhará.

Para informações de referência sobre o esquema, consulte dataStores.schemas.

Abordagens para fornecer o esquema do seu repositório de dados

Há várias abordagens para determinar o esquema de dados estruturados.

  • Detecção e edição automáticas. Permita que a Pesquisa de agentes detecte e sugira um esquema inicial. Em seguida, refine o esquema pela interface do console. O Google recomenda que, depois que os campos forem detectados automaticamente, você mapeie as propriedades principais para todos os campos importantes.

    Essa é a abordagem que você usará ao seguir as Google Cloud instruções do console para dados estruturados em Criar um repositório de dados de pesquisa e Criar um repositório de dados de recomendações personalizadas.

  • Fornecer o esquema como um objeto JSON. Forneça o esquema para a Pesquisa de agentes como um objeto JSON. Você precisa ter preparado um objeto JSON correto. Para um exemplo de objeto JSON, consulte Exemplo de esquema como um objeto JSON. Depois de criar o esquema, faça upload dos dados de acordo com ele.

    Essa é a abordagem que você pode usar ao criar um repositório de dados pela API usando um comando curl (ou programa). Por exemplo, consulte Importar uma vez do BigQuery. Consulte também as instruções a seguir: Fornecer seu próprio esquema.

  • Mídia: forneça seus dados no esquema definido pelo Google. Se você criar um repositório de dados para mídia, poderá usar o esquema predefinido do Google. A escolha dessa opção pressupõe que você tenha estruturado o objeto JSON no formato fornecido em Sobre documentos de mídia e repositório de dados. Por padrão, a detecção automática anexa ao esquema todos os novos campos encontrados durante a ingestão de dados.

    Essa é a abordagem que você usa ao seguir as instruções em Criar um app de mídia e um repositório de dados. Essa também é a abordagem nos tutoriais Primeiros passos com as recomendações de mídia e Primeiros passos com a pesquisa de mídia, em que os dados de amostra são fornecidos no esquema predefinido do Google.

  • Mídia: detecção e edição automáticas, incluindo as propriedades de mídia necessárias. Para dados de mídia, você pode usar a detecção automática para sugerir o esquema e editar para refiná-lo. No objeto JSON, inclua campos que podem ser mapeados para as propriedades de chave de mídia: title, uri, category, media_duration e media_available_time.

    Essa é a abordagem que você usará ao importar dados de mídia pelo Google Cloud console se os dados de mídia não estiverem no esquema definido pelo Google.

  • Mídia: forneça seu próprio esquema como um objeto JSON. Forneça o esquema para a Pesquisa de agentes como um objeto JSON. Você precisa ter preparado um objeto JSON correto. O esquema precisa incluir campos que podem ser mapeados para as propriedades de chave de mídia: title, uri, category, media_duration e media_available_time.

    Para um exemplo de objeto JSON, consulte Exemplo de esquema como um objeto JSON. Depois de criar o esquema, faça upload dos dados de mídia de acordo com ele.

    Para essa abordagem, use a API por um comando curl (ou programa). Consulte as instruções a seguir: Fornecer seu próprio esquema.

Sobre a detecção e edição automáticas

Ao começar a importar dados, a Pesquisa de agentes faz uma amostragem dos primeiros documentos importados. Com base nesses documentos, ela propõe um esquema para os dados, que você pode revisar ou editar.

Se os campos que você quer mapear para as propriedades principais não estiverem presentes nos documentos amostrados, adicione esses campos manualmente ao revisar o esquema.

Se a Pesquisa de agentes encontrar outros campos mais tarde na importação de dados, ela ainda vai importar esses campos e adicioná-los ao esquema. Se você quiser editar o esquema depois que todos os dados forem importados, consulte Atualizar o esquema.

Exemplo de esquema como um objeto JSON

É possível definir seu próprio esquema usando o formato JSON Schema, que é uma linguagem declarativa de código aberto para definir, anotar e validar documentos JSON. Por exemplo, esta é uma anotação de esquema JSON válida:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "dynamic": "true",
  "datetime_detection": true,
  "geolocation_detection": true,
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title",
      "retrievable": true,
      "completable": true
    },
    "description": {
      "type": "string",
      "keyPropertyMapping": "description"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    },
    "brand": {
      "type": "string",
      "indexable": true,
      "dynamicFacetable": true
    },
    "location": {
      "type": "geolocation",
      "indexable": true,
      "retrievable": true
    },
    "creationDate": {
      "type": "datetime",
      "indexable": true,
      "retrievable": true
    },
    "isCurrent": {
      "type": "boolean",
      "indexable": true,
      "retrievable": true
    },
    "runtime": {
      "type": "string",
      "keyPropertyMapping": "media_duration"
    },
    "releaseDate": {
      "type": "string",
      "keyPropertyMapping": "media_available_time"
    }
  }
}

Se você estiver definindo um esquema de mídia, inclua campos que podem ser mapeados para as propriedades de chave de mídia. Essas propriedades de chave são mostradas neste exemplo.

Confira alguns dos campos neste exemplo de esquema:

  • dynamic. Se dynamic estiver definido como o valor de string "true", todas as novas propriedades encontradas nos dados importados serão adicionadas ao esquema. Se dynamic estiver definido como "false", as novas propriedades encontradas nos dados importados serão ignoradas. As propriedades não serão adicionadas ao esquema nem os valores serão importados.

    Por exemplo, um esquema tem duas propriedades: title e description, e você faz upload de dados que contêm propriedades para title, description e rating. Se dynamic for "true", a propriedade e os dados de classificações serão importados. Se dynamic for "false", as propriedades rating não serão importadas, embora title e description sejam.

    O padrão é "true".

  • datetime_detection. Se datetime_detection estiver definido como o booleano true, quando os dados no formato de data e hora forem importados, o tipo de esquema será definido como datetime. Os formatos aceitos são RFC 3339 e ISO 8601.

    Exemplo:

    • 2024-08-05 08:30:00 UTC

    • 2024-08-05T08:30:00Z

    • 2024-08-05T01:30:00-07:00

    • 2024-08-05

    • 2024-08-05T08:30:00+00:00

    Se datatime_detection estiver definido como o booleano false, quando os dados no formato de data e hora forem importados, o tipo de esquema será definido como string.

    O padrão é true.

  • geolocation_detection. Se geolocation_detection estiver definido como o booleano true, quando os dados no formato de geolocalização forem importados, o tipo de esquema será definido como geolocation. Os dados serão detectados como geolocalização se forem um objeto que contém um número de latitude e um número de longitude ou um objeto que contém uma string de endereço.

    Exemplo:

    • "myLocation": {"latitude":37.42, "longitude":-122.08}

    • "myLocation": {"address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"}

    Se geolocation_detection estiver definido como o booleano false, quando os dados no formato de geolocalização forem importados, o tipo de esquema será definido como object.

    O padrão é true.

  • keyPropertyMapping. Um campo que mapeia palavras-chave predefinidas para campos críticos nos documentos, ajudando a esclarecer o significado semântico deles. Os valores incluem title, description, uri e category. O nome do campo não precisa corresponder ao valor keyPropertyValues. Por exemplo, para um campo chamado my_title, você pode incluir um campo keyPropertyValues com um valor de title.

    Para repositórios de dados de pesquisa, os campos marcados com keyPropertyMapping são indexáveis e pesquisáveis por padrão, mas não recuperáveis, completáveis ou dynamicFacetable. Isso significa que não é necessário incluir os campos indexable ou searchable com um campo keyPropertyValues para receber o comportamento padrão esperado.

  • type. O tipo do campo. Esse é um valor de string que é datetime, geolocation ou um dos tipos primitivos (integer, boolean, object, array, number ou string).

Os campos de propriedade a seguir se aplicam apenas a apps de pesquisa:

  • retrievable. Indica se esse campo pode ser retornado em uma resposta de pesquisa. Isso pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. É possível definir no máximo 50 campos como recuperáveis. Os campos definidos pelo usuário e os campos keyPropertyValues não são recuperáveis por padrão. Para tornar um campo recuperável, inclua "retrievable": true com o campo.

  • indexable. Indica se esse campo pode ser filtrado, facetado, promovido ou classificado no método servingConfigs.search. Isso pode ser definido para campos do tipo number, string, boolean, integer, datetime e geolocation. É possível definir no máximo 50 campos como indexáveis. Os campos definidos pelo usuário não são indexáveis por padrão, exceto os campos que contêm o campo keyPropertyMapping. Para tornar um campo indexável, inclua "indexable": true com o campo.

  • dynamicFacetable. Indica que o campo pode ser usado como um atributo dinâmico. Isso pode ser definido para campos do tipo number, string, boolean e integer. Para tornar um campo dinamicamente facetável, ele também precisa ser indexável: inclua "dynamicFacetable": true e "indexable": true com o campo.

  • searchable. Indica se esse campo pode ser indexado inversamente para corresponder a consultas de texto não estruturadas. Isso só pode ser definido para campos do tipo string. É possível definir no máximo 50 campos como pesquisáveis. Os campos definidos pelo usuário não são pesquisáveis por padrão, exceto os campos que contêm o campo keyPropertyMapping. Para tornar um campo pesquisável, inclua "searchable": true com o campo.

  • completable. Indica se esse campo pode ser retornado como uma sugestão de preenchimento automático. Isso só pode ser definido para campos do tipo string. Para tornar um campo completável, inclua "completable": true com o campo.

Além disso, o campo a seguir se aplica apenas a apps de recomendação:

  • recommendationsFilterable. Indica que o campo pode ser usado em uma expressão de filtro de recomendações. Para informações gerais sobre como filtrar recomendações, consulte Filtrar recomendações.

      ...
    "genres": {
    "type": "string",
    "recommendationsFilterable": true,
    ...
  },

Fornecer seu próprio esquema como um objeto JSON

Para fornecer seu próprio esquema, crie um repositório de dados que contenha um esquema vazio e atualize o esquema, fornecendo-o como um objeto JSON. Siga estas etapas:

  1. Prepare o esquema como um objeto JSON, usando o Exemplo de esquema como um objeto JSON como guia.

  2. Crie um repositório de dados.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID" \
-d '{
  "displayName": "DATA_STORE_DISPLAY_NAME",
  "industryVertical": "INDUSTRY_VERTICAL"
}'

    Substitua:

    • PROJECT_ID: o ID do Google Cloud projeto.
    • DATA_STORE_ID: o ID do repositório de dados da Pesquisa de agentes que você quer criar. Esse ID só pode conter letras minúsculas, dígitos, sublinhados e hífens.
    • DATA_STORE_DISPLAY_NAME: o nome de exibição do repositório de dados da Pesquisa de agentes que você quer criar.
    • INDUSTRY_VERTICAL: GENERIC ou MEDIA

  3. Use o método da API schemas.patch para fornecer seu novo esquema JSON como um objeto JSON.

    curl -X PATCH \
-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/schemas/default_schema" \
-d '{
  "structSchema": JSON_SCHEMA_OBJECT
}'

    Substitua:

    • PROJECT_ID: o ID do Google Cloud projeto.
    • DATA_STORE_ID: o ID do repositório de dados da Pesquisa de agentes.

    • JSON_SCHEMA_OBJECT: seu novo esquema JSON como um objeto JSON. Exemplo:

      {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "keyPropertyMapping": "title"
    },
    "categories": {
      "type": "array",
      "items": {
        "type": "string",
        "keyPropertyMapping": "category"
      }
    },
    "uri": {
      "type": "string",
      "keyPropertyMapping": "uri"
    }
  }
}

  4. Opcional: revise o esquema seguindo o procedimento Visualizar uma definição de esquema.

A seguir