從 BigQuery 匯入索引資料

本指南說明如何使用 ImportIndex API，將 BigQuery 中的索引資料匯入向量搜尋，直接從含有向量嵌入的 BigQuery 資料表填入向量搜尋索引，簡化相關程序。

準備要匯入的 BigQuery 資料

匯入索引資料前，BigQuery 資料表必須包含下列資料欄：

  • 專屬 ID：這個資料欄包含每個資料點的專屬 ID。這會對應至 Vector Search 中的 id 欄位。

  • 向量嵌入：這個資料欄包含向量嵌入，以重複的 FLOAT 欄位表示。這會對應至 Vector Search 中的嵌入欄位。

您也可以加入下列資料欄：

  • 限制：這些是字串和數值限制的資料欄，可讓您在搜尋期間篩選資料。

  • 中繼資料：這些是中繼資料欄，會與向量搜尋索引查詢結果一併傳回。

準備要匯入的 Vector Search 索引

準備好 BigQuery 資料後，請確認目的地向量搜尋索引：

  • 存在於專案的向量搜尋中：這個索引是匯入資料的目的地。索引必須在專案中建立。

  • 設為覆寫或附加資料：在匯入程序中，您可以選擇覆寫向量搜尋索引中的現有資料，或附加從 BigQuery 匯入的資料。覆寫會以匯入的資料取代目前的資料點。附加作業會將新資料新增至現有索引。

  • 維度相符：儲存在 BigQuery 資料中的嵌入內容維度，必須與為向量搜尋索引設定的維度相同。

指定 ImportIndexRequest

從 BigQuery 匯入資料前，請先建立 ImportIndexRequest 物件，指定目標索引、是否要覆寫現有資料，以及連線至 BigQuery 的設定。將這個要求物件傳送至 ImportIndex API。

以下是 JSON 格式的 ImportIndexRequest 範例：

{
  "name": "projects/[PROJECT_ID]/locations/[LOCATION]/indexes/[INDEX_ID]",
  "isCompleteOverwrite": true,
  "config": {
    "bigQuerySourceConfig": {
      "tablePath": "[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：要匯入資料的 Vector Search 索引完整資源名稱。

  • isCompleteOverwrite：布林值，表示是否要覆寫索引中的現有資料。設為 true 即可取代現有資料。

  • config：包含 BigQuery 來源的設定。

    • bigquerySourceConfig：指定連線至 BigQuery 資料表的詳細資料。

    • tablePath：BigQuery 資料表的完整路徑，格式為 [PROJECT_ID].[DATASET_ID].[TABLE_ID]。

    • datapointFieldMapping：將 BigQuery 資料表中的資料欄對應至向量搜尋中的欄位。

      • idColumn：包含專屬 ID 的資料欄名稱。

      • embeddingColumn：包含向量嵌入內容的資料欄名稱。

      • restricts：(選用) 指定字串限制。

      • namespace：限制的命名空間。

      • allowColumn：陣列，內含限制允許值的資料欄名稱。

      • denyColumn：包含受限值遭拒的資料欄名稱的陣列。

      • numericRestricts：(選用) 指定數字限制。

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