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