データ オブジェクトの同時実行制御に ETag を使用する

Vector Search 2.0 は、特定のデータ オブジェクト バージョンを表す不透明な識別子である ETag（エンティティ タグ）を使用して、オプティミスティック同時実行制御（OCC）をサポートしています。

リアルタイム API の更新や一括インポート ジョブなど、複数のプロセスが同じデータセットで同時に動作する場合、それぞれの変更が上書きされるリスクがあります（後勝ちのシナリオ）。ETag を使用すると、データの完全性を保証し、最後に読み取ってから別のプロセスがレコードを変更していないことを確認できます。

ETag の仕組み

  1. 読み取り: データ オブジェクトを作成または取得すると、サーバーはデータ オブジェクトの正確なバージョンを表す ETag 文字列を返します。

  2. 変更: データ オブジェクトをローカルで変更します。

  3. 書き込み: 最初に受け取った ETag を含めて、更新リクエストまたは削除リクエストを Vector Search 2.0 に送信します。

  4. 検証: サーバーは、提供された ETag がデータベースに保存されている現在の ETag と一致するかどうかを確認します。

    • 一致すると、オペレーションは成功し、サーバーは更新されたデータ オブジェクトの新しい ETag を返します。
    • 一致しない場合、オペレーションはブロックされ、サーバーは ABORTED エラー（HTTP 409 Conflict）を返します。

ETag の取得

同時実行制御に ETag を使用する前に、システムから最新バージョンを取得する必要があります。

ETag は次の方法で取得できます。

  • リアルタイム API レスポンス: DataObjectService（GetDataObject、ListDataObjects、CreateDataObject、UpdateDataObject など）で読み取りまたは書き込みメソッドを呼び出すと、返されるデータ オブジェクト リソースに現在の ETag が含まれます。

  • Import API の出力: ImportDataObjects を呼び出すときに、GcsImportConfig フィールド output-uri で Cloud Storage の URI 接頭辞を指定できます。インポート ジョブが成功すると、各行にインポートされたデータ オブジェクトの ID と ETag が含まれる JSONL ファイルが作成されます。形式は次のとおりです。

    { "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 メソッドは、ペイロードとして完全なデータ オブジェクト リソースを受け取らないため、ETag は DeleteDataObjectRequest の最上位フィールドとして指定する必要があります。

{
  "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 フィールドを含めます。

ベクトル検索は、レコードごとに競合解決モードを自動的に検出します。

  • 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 を使用してオペレーションを再試行します。

次のステップ