Importe dados de índice do BigQuery

Este guia explica como importar dados de índice do BigQuery para a Pesquisa vetorial com a API ImportIndex, simplificando o processo de preenchimento de índices da Pesquisa vetorial diretamente a partir das suas tabelas do BigQuery que contêm incorporações vetoriais.

Preparar dados do BigQuery para importação

Antes de importar dados de índice, a sua tabela do BigQuery tem de ter as seguintes colunas:

  • Identificadores únicos: esta coluna contém identificadores únicos para cada ponto de dados. É mapeado para o campo id na pesquisa vetorial.

  • Incorporações de vetores: esta coluna contém as incorporações de vetores, representadas como um campo FLOAT repetido. Está mapeado para o campo de incorporação na pesquisa vetorial.

Opcionalmente, pode incluir as seguintes colunas:

  • Restringe: estas são colunas para restrições de strings e numéricas, que lhe permitem filtrar os dados durante as pesquisas.

  • Metadados: estas são colunas de metadados a devolver com os resultados da consulta do índice de pesquisa vetorial.

A preparar o índice do Vector Search para importação

Depois de preparar os dados do BigQuery, certifique-se de que o índice de pesquisa vetorial de destino:

  • Existe na pesquisa vetorial no seu projeto: este índice serve como destino dos seus dados importados. O índice tem de ser criado no seu projeto.

  • Está definido para substituir ou acrescentar dados: durante o processo de importação, tem a opção de substituir os dados existentes no índice de pesquisa vetorial ou acrescentar os dados importados do BigQuery. A substituição substitui os pontos de dados atuais pelos dados importados. A anexação adiciona os novos dados ao índice existente.

  • Corresponde à dimensionalidade: a dimensionalidade das incorporações armazenadas nos seus dados do BigQuery tem de ser idêntica à dimensionalidade configurada para o seu índice de pesquisa vetorial.

Especificar o ImportIndexRequest

Antes de importar dados do BigQuery, crie um objeto ImportIndexRequest que especifique o índice de destino, se deve substituir os dados existentes e a configuração para estabelecer ligação ao BigQuery. Envie este objeto de pedido para a ImportIndexAPI.

Segue-se um exemplo de um ImportIndexRequest no formato JSON:

{
  "name": "projects/[PROJECT_ID]/locations/[LOCATION]/indexes/[INDEX_ID]",
  "isCompleteOverwrite": true,
  "config": {
    "bigQuerySourceConfig": {
      "tablePath": "bq://[PROJECT_ID].[DATASET_ID].[TABLE_ID]",
      "datapointFieldMapping": {
        "idColumn": "[ID_COLUMN_NAME]",
        "embeddingColumn": "[EMBEDDING_COLUMN_NAME]",
        "restricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "allowColumn": ["[RESTRICT_ALLOW_COLUMN_NAME]"],
            "denyColumn": ["[RESTRICT_DENY_COLUMN_NAME]"]
          }
        ],
        "numericRestricts": [
          {
            "namespace": "[RESTRICT_NAMESPACE]",
            "valueColumn": "[RESTRICT_VALUE_COLUMN_NAME]",
            "valueType": "INT"
          }
        ],
        "metadataColumns": ["METADATA_COLUMN1", "METADATA_COLUMN2", ...]
      }
    }
  }
}

  • name: o nome completo do recurso do índice do Vector Search onde quer importar os dados.

  • isCompleteOverwrite: um valor booleano que indica se deve substituir os dados existentes no índice. Defina como true para substituir os dados existentes.

  • config: contém a configuração da origem do BigQuery.

    • bigquerySourceConfig: especifica os detalhes da ligação à sua tabela do BigQuery.

    • tablePath: o caminho completo para a sua tabela do BigQuery no formato bq://[PROJECT_ID].[DATASET_ID].[TABLE_ID].

    • datapointFieldMapping: mapeia as colunas na sua tabela do BigQuery para os campos na pesquisa vetorial.

      • idColumn: o nome da coluna que contém identificadores exclusivos.

      • embeddingColumn: o nome da coluna que contém as incorporações de vetores.

      • restricts: (Opcional) Especifica restrições de strings.

      • namespace: o espaço de nomes da restrição.

      • allowColumn: a matriz que contém os nomes das colunas para os valores permitidos para a restrição.

      • denyColumn: a matriz que contém os nomes das colunas para valores recusados para a restrição.

      • numericRestricts: (opcional) especifica restrições numéricas.

      • namespace: o espaço de nomes para a restrição numérica.

      • value_column: o nome da coluna que contém valores numéricos.

      • value_type: o tipo do valor numérico, como INT, FLOAT ou DOUBLE.

      • metadataColumns: (opcional) Campos de metadados a incluir com a incorporação de caraterísticas. Estes campos de metadados podem ser obtidos a partir dos resultados da pesquisa do índice, mas não afetam a própria pesquisa. Por exemplo, não é possível filtrar campos de metadados.

Executar a importação

Depois de criar um ImportIndexRequest, envie-o para o ponto final da API ImportIndex. Isto aciona o processo de importação, que exporta dados do BigQuery e carrega-os no seu índice de pesquisa vetorial. ImportIndex devolve uma operação de longa duração. Pode usar o ID da operação para monitorizar o progresso da operação de importação.

Depois de armazenados, os dados importados residem no seu índice de pesquisa vetorial e são indistinguíveis dos dados carregados através de outros métodos. O índice pode continuar a ser gerido através das APIs Vector Search padrão.

O exemplo de código seguinte demonstra um resultado de consulta com return_full_datapoint definido como verdadeiro e a configuração do conetor do BigQuery que especifica um genre, restrições numéricas year e colunas de metadados title e description.

nearest_neighbors {
  neighbors {
    datapoint {
      datapoint_id: "4"
      feature_vector: 0.7
      feature_vector: 0.8
      restricts {
        namespace: "genre"
        allow_list: "Drama"
      }
      embedding_metadata {
        title: "A Movie"
        description: "The story of A Movie..."
      }
      crowding_tag {
        crowding_attribute: "0"
      }
      numeric_restricts {
        namespace: "year"
        value_int: 1942
      }
    }
    distance: 0.75
  }
}