从 BigQuery 导入索引数据

本指南介绍了如何使用 ImportIndex API 将索引数据从 BigQuery 导入到 Vector Search 中，相比直接从包含向量嵌入的 BigQuery 表填充 Vector Search 索引，这样更加便捷高效。

准备要导入的 BigQuery 数据

在导入索引数据之前，需确保您的 BigQuery 表包含以下列：

唯一标识符：此列包含每个数据点的唯一标识符。该列会映射到 Vector Search 中的 id 字段。
向量嵌入：此列包含向量嵌入，以重复的 FLOAT 字段表示。该列会映射到 Vector Search 中的嵌入字段。

您还可以选择性地添加以下列：

限制：这些列可包含字符串和数值限制，可让您在搜索期间过滤数据。
元数据：这些列可包含与 Vector Search 索引查询结果一起返回的元数据。

准备要导入的 Vector Search 索引

准备好 BigQuery 数据后，请确保目标 Vector Search 索引满足以下要求：

存在于您的项目内的 Vector Search 中：此索引将是导入数据的目标位置。该索引必须在您的项目内创建。
设置为覆盖或附加数据：在导入过程中，您可以选择覆盖 Vector Search 索引中的现有数据，也可以选择附加从 BigQuery 导入的数据。覆盖会用导入的数据替换掉当前的数据点。附加则会将新数据添加到现有索引。
维度匹配：存储在 BigQuery 数据中的嵌入的维度必须与为 Vector Search 索引配置的维度完全相同。

指定 `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 表中的列映射到 Vector Search 中的字段。
  - idColumn：包含唯一标识符的列的名称。
  - embeddingColumn：包含向量嵌入的列的名称。
  - restricts：（可选）指定字符串限制。
  - namespace：限制适用的命名空间。
  - allowColumn：包含限制允许值的列名称的数组。
  - denyColumn：包含限制禁止值的列名称的数组。
  - numericRestricts：（可选）指定数值限制。
  - namespace：数值限制适用的命名空间。
  - value_column：包含数值的列的名称。
  - value_type：数值的类型，例如 INT、FLOAT 或 DOUBLE。
  - metadataColumns：（可选）要包含在特征嵌入中的元数据字段。这些元数据字段可以从索引搜索结果中检索，但不会影响搜索本身。例如，无法对元数据字段执行过滤。

执行导入

创建 ImportIndexRequest 后，将其发送到 ImportIndex API 端点。这会触发导入流程，该流程会从 BigQuery 中导出数据并将其注入到 Vector Search 索引中。ImportIndex 会返回一个长时间运行的操作。您可以使用操作 ID 监控导入操作的进度。

存储后的导入数据会驻留在您的 Vector Search 索引中，并且与使用其他方法注入的数据没有区别。您可以继续使用标准 Vector Search API 管理索引。

以下代码示例展示了一个查询结果，该查询将 return_full_datapoint 设置为 true，并且通过 BigQuery 连接器配置指定了 genre 限制、year 数值限制以及元数据列 title 和 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
  }
}