BigQuery からインデックス データをインポートする

このガイドでは、ImportIndex API を使用して BigQuery からベクトル検索にインデックス データをインポートする方法について説明します。これにより、ベクトル エンベディングを含む BigQuery テーブルからベクトル検索インデックスに直接データを入力するプロセスを効率化できます。

インポート用に BigQuery データを準備する

インデックス データをインポートする前に、BigQuery テーブルに次の列が必要です。

  • 固有識別子: この列には、各データポイントの固有識別子が含まれます。ベクトル検索の id フィールドにマッピングされます。

  • ベクトル エンベディング: この列には、繰り返し FLOAT フィールドとして表されるベクトル エンベディングが含まれています。ベクトル検索のエンベディング フィールドにマッピングされます。

必要に応じて、次の列を含めることができます。

  • 制限: 文字列と数値の制限の列です。検索時にデータをフィルタできます。

  • メタデータ: ベクトル検索インデックス クエリの結果とともに返されるメタデータの列。

インポート用にベクトル検索インデックスを準備する

BigQuery データを準備したら、宛先のベクトル検索インデックスが次のようになっていることを確認します。

  • プロジェクト内の Vector Search に存在する: このインデックスは、インポートされたデータの宛先として機能します。インデックスはプロジェクト内に作成する必要があります。

  • データの上書きまたは追加に設定されている: インポート プロセスでは、Vector Search インデックス内の既存のデータを上書きするか、BigQuery からインポートしたデータを追加するかを選択できます。上書きすると、現在のデータポイントがインポートしたデータに置き換えられます。追加では、新しいデータが既存のインデックスに追加されます。

  • 次元が一致する: BigQuery データに保存されているエンベディングの次元は、ベクトル検索インデックス用に構成された次元と同一である必要があります。

ImportIndexRequest の指定

BigQuery からデータをインポートする前に、ターゲット インデックス、既存のデータを上書きするかどうか、BigQuery への接続構成を指定する ImportIndexRequest オブジェクトを作成します。このリクエスト オブジェクトを ImportIndex API に送信します。

JSON 形式の ImportIndexRequest の例を次に示します。

{
  "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: データをインポートするベクトル検索インデックスの完全なリソース名。

  • isCompleteOverwrite: インデックス内の既存のデータを上書きするかどうかを示すブール値。既存のデータを置き換える場合は true に設定します。

  • config: BigQuery ソースの構成が含まれます。

    • bigquerySourceConfig: BigQuery テーブルへの接続の詳細を指定します。

    • tablePath: bq://[PROJECT_ID].[DATASET_ID].[TABLE_ID] 形式の BigQuery テーブルの完全パス。

    • datapointFieldMapping: BigQuery テーブルの列をベクトル検索のフィールドにマッピングします。

      • idColumn: 一意の識別子を含む列の名前。

      • embeddingColumn: ベクトル エンベディングを含む列の名前。

      • restricts:（省略可）文字列の制限を指定します。

      • namespace: 制限の名前空間。

      • allowColumn: 制限の許容値の列名を含む配列。

      • denyColumn: 制限の拒否された値の列名を含む配列。

      • numericRestricts:（省略可）数値制限を指定します。

      • namespace: 数値制限の Namespace。

      • value_column: 数値を含む列の名前。

      • value_type: 数値の型（INT、FLOAT、DOUBLE など）。

      • metadataColumns: 省略可。特徴ベクトルのエンベディングに含めるメタデータ フィールド。これらのメタデータ フィールドはインデックス検索結果から取得できますが、検索自体には影響しません。たとえば、メタデータ フィールドでフィルタリングを行うことはできません。

インポートの実行

ImportIndexRequest を作成したら、ImportIndex API エンドポイントに送信します。これにより、インポート プロセスがトリガーされ、BigQuery からデータがエクスポートされて、ベクトル検索インデックスに取り込まれます。ImportIndex は長時間実行オペレーションを返します。オペレーション ID を使用して、インポート オペレーションの進行状況をモニタリングできます。

インポートされたデータは、保存されるとベクトル検索インデックス内に存在し、他の方法で取り込まれたデータと区別できません。インデックスは、標準の Vector Search API を使用して引き続き管理できます。

次のコードサンプルは、return_full_datapoint が true に設定されたクエリ結果と、genre 制限、year 数値制限、メタデータ列 title と description を指定する BigQuery コネクタ構成を示しています。

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
  }
}