使用 ETag 进行数据对象并发控制

Vector Search 2.0 支持使用 ETag（实体标记）进行乐观并发控制 (OCC)，ETag 是表示特定 数据对象版本的不透明标识符。

当多个进程同时对同一数据集进行操作（例如实时 API 更新和批量导入作业）时，存在相互覆盖彼此更改的风险（“后写优先”场景）。 借助 ETag，您可以保证数据完整性，并确保自您上次读取记录以来，没有其他进程修改过该记录。

ETag 的工作原理

  1. 读取：当您创建 或获取数据对象时， 服务器会返回一个 ETag 字符串，表示数据对象的准确版本。

  2. 修改：您在本地对数据对象进行更改。

  3. 写入：您将更新 或删除请求发送回 Vector Search 2.0，其中包含您最初收到的 ETag。

  4. 验证：服务器会检查提供的 ETag 是否与数据库中存储的当前 ETag 匹配。

    • 如果它们匹配，则操作成功，服务器会为更新后的数据对象返回新的 ETag 。
    • 如果它们不匹配，则操作会被阻止，服务器会返回 ABORTED错误（HTTP 409 Conflict）。

检索 ETag

您需要从系统中检索最新版本，然后才能使用 ETag 进行并发控制。

您可以通过以下方式检索 ETag：

  • 实时 API 响应：当您对 DataObjectService调用读取或写入方法（例如 GetDataObject、ListDataObjects、 CreateDataObject 或 UpdateDataObject）时，返回的数据对象资源 会包含其当前 ETag。

  • 导入 API 输出：当您调用 ImportDataObjects 时，可以在 GcsImportConfig 字段 output-uri 中指定 Cloud Storage 的 URI 前缀。如果导入作业成功，系统会创建 JSONL 文件 ，其中每行包含导入的数据对象的 ID 和 ETag。格式如下：

    { "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"}

  • 导出 API (ExportDataObjects) - 当您将数据从 Vector Search 2.0 导出到 Cloud Storage 时，生成的规范 JSONL 数据文件会包含所有导出的数据对象的 ETag。

创建数据对象

调用 CreateDataObject 或 BatchCreateDataObjects 时，系统会忽略您 在请求中提供的任何 ETag，因为数据对象尚不存在。

创建请求成功后，服务器会在返回的数据对象资源中包含新生成的 ETag。

更新数据对象

如需使用 UpdateDataObject 或 BatchUpdateDataObjects 安全地更新现有记录，请在请求中直接将 ETag 包含在数据对象 资源中。

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d",
  "data": {
    "genre": ["science-fiction", "thriller", "action"]
  }
}

删除数据对象

由于 DeleteDataObject 和 BatchDeleteDataObjects 方法不会将 完整的数据对象资源作为其载荷，因此必须在 DeleteDataObjectRequest 中将 ETag 作为 顶级字段提供。

{
  "name": "projects/my-project/locations/us-central1/collections/my-collection/dataObjects/movie-789",
  "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d"
}

将 ETag 与批量注入 (ImportDataObjects) 结合使用

使用 ImportDataObjects API 会以异步方式运行，并且可能会与实时更新发生冲突。在您的 JSONL导入文件中包含 etag 字段，以便在导入期间强制执行并发控制。

Vector Search 会自动检测每条记录的冲突解决模式：

  • 使用 ETag (OCC)：如果提供了 ETag 且与服务器的 当前版本不匹配，则特定记录将无法导入。然后，系统会将失败记录到您指定的错误 URI，但导入作业的其余部分会继续进行。

  • 不使用 ETag：如果省略了 ETag，系统会注入记录，并覆盖 任何现有数据。当不需要并发控制时，这可以最大限度地提高吞吐量。

JSONL 格式

在导入文件中 JSON 对象的根级别包含 ETag，如以下示例所示。

{ "id": "movie-789", "etag": "a3b8c1d9-e4f2-4a1b-9c8d-0e6f7a8b9c0d", "data":{ "genre": ["science-fiction", "thriller"] }, "vectors": { ... } }

处理并发错误

如果某项操作未能通过 ETag 检查，API 将返回 ABORTED (HTTP 409 Conflict) 错误代码。

建议的错误处理方式：

当您收到 ABORTED 错误时，您的应用应执行以下操作：

  1. 从服务器重新提取最新版本的数据对象。

  2. 解决新提取的数据与预期更新之间的任何业务逻辑冲突。

  3. 使用新的 ETag 重试该操作。

接下来怎么做？