エンティティごとにメッセージを順番に処理する

Spanner キューは、メッセージを少なくとも 1 回配信し、複数の受信者間で並列処理を行うように設計されています。同じエンティティ(顧客アカウント、注文、デバイスなど)の複数のメッセージがキューに送信されると、異なるワーカーが同時にメッセージを pull して処理できます。1 つのメッセージが最初に送信された場合でも、ネットワーク遅延や再試行によって最初のワーカーの処理が遅くなり、2 番目のワーカーが後のメッセージを完了することがあります。

キュー全体のすべてのメッセージが厳密なグローバル順序で処理されると、1 つの低速なワーカーがキュー全体を停止させる可能性があります(ヘッドオブライン ブロッキングと呼ばれる現象)。ただし、ほとんどのアプリケーションでは、データベース全体のすべてのメッセージを 1 つのグローバルな行で待機させる必要はありません。代わりに、同じエンティティのタスクのみを順番に実行し、異なるエンティティのタスクは並行して実行する必要があります。次のパターンを使用すると、ワークロードに基づいてエンティティごとにメッセージを順番に処理できます。

シーケンシャル ワークフローのチェーン メッセージ

エンティティのバックグラウンド ジョブが、依存する一連のステップ(たとえば、step-1 の後に step-2 と step-3)で構成され、外部リクエストが競合するタスクをそのワークフローに並行して追加しない場合、前のステップが完了した後にのみ各ステップを開始する必要があります。

ステップバイステップの順序を適用するには、最初に最初のステップのみをキューに入れます。ワーカーが現在のステップの処理を完了すると、現在のメッセージ(DELETE ... ASSERT_ROWS_MODIFIED 1)を確認し、同じ読み取り / 書き込みトランザクションに次のステップのメッセージを挿入します。

現在のステップが完了して同じトランザクションで確認されるまで、次のステップのメッセージは作成されないため、同じワークフローの 2 つのステップがキューに同時に存在することはなく、同時実行ワーカーによって順序が入れ替わって処理されることはありません。

たとえば、ワーカーがオンボーディング ワークフローの step-1 を完了し、step-2 をスケジュールする場合、

GoogleSQL

-- Inside the worker transaction after finishing step-1:
-- 1. Acknowledge the current step
DELETE FROM OnboardingQueue
WHERE CustomerId = 456 AND StepName = 'step-1'
ASSERT_ROWS_MODIFIED 1;

-- 2. Enqueue the next step in the sequence
INSERT INTO OnboardingQueue (CustomerId, StepName, DeliverTime, Payload)
VALUES (456, 'step-2', CURRENT_TIMESTAMP(), b'{"stage": "provision_resources"}');

PostgreSQL

-- Inside the worker transaction after finishing step-1:
-- 1. Acknowledge the current step
DELETE FROM onboardingqueue
WHERE customerid = 456 AND stepname = 'step-1'
ASSERT_ROWS_MODIFIED 1;

-- 2. Enqueue the next step in the sequence
INSERT INTO onboardingqueue (customerid, stepname, deliver_time, payload)
VALUES (456, 'step-2', CURRENT_TIMESTAMP, CAST('{"stage": "provision_resources"}' AS bytea));

順序付き作業テーブルとウェイクアップ キューを使用する

ただし、特定のエンティティのすべてのタスクを commit 順に実行する必要がある場合、外部リクエスト、Webhook、ユーザー アクションによって新しいタスクが追加され、以前のタスクがまだ処理されている場合でも、このパターンは、単一のスプリットの書き込み容量に収まるワークロードをサポートします。

エンティティごとに同時実行タスクを順番に処理するには、順序付けされたタスクをインターリーブされたテーブルに保存し、軽量のウェイクアップ通知にのみキューを使用することで、ダーティフラグ パターンを拡張します。

まず、アクティブなクレームを追跡する親エンティティ テーブルに、順序付けられた作業テーブル(commit タイムスタンプを使用)とウェイクアップ キューをインターリーブします。スプリット全体でホットスポットを回避するには、エンティティを均等に分散する主キー(UUID やビット反転シーケンスなど)を選択します。

GoogleSQL

CREATE SEQUENCE CustomerIdSeq OPTIONS (sequence_kind = 'bit_reversed_positive');

CREATE TABLE Customers (
  CustomerId          INT64 NOT NULL DEFAULT (GET_NEXT_SEQUENCE_VALUE(SEQUENCE CustomerIdSeq)),
  CustomerName        STRING(1024),
  IsProcessing        BOOL NOT NULL DEFAULT (FALSE),
  ActiveClaimId       STRING(36),
  ProcessingExpiresAt TIMESTAMP,
) PRIMARY KEY (CustomerId);

CREATE TABLE CustomerWorkItems (
  CustomerId   INT64 NOT NULL,
  CreatedAt    TIMESTAMP NOT NULL DEFAULT (PENDING_COMMIT_TIMESTAMP())
    OPTIONS (allow_commit_timestamp = true),
  BatchIndex   INT64 NOT NULL DEFAULT (0),
  WorkType     STRING(128) NOT NULL,
  WorkPayload  JSON NOT NULL,
) PRIMARY KEY (CustomerId, CreatedAt, BatchIndex),
  INTERLEAVE IN PARENT Customers ON DELETE CASCADE;

CREATE QUEUE CustomerDirtyQueue (
  CustomerId   INT64 NOT NULL,
  MessageId    STRING(36) NOT NULL,
  Payload      BYTES(MAX) NOT NULL,
) PRIMARY KEY (CustomerId, MessageId),
  INTERLEAVE IN PARENT Customers ON DELETE CASCADE;

PostgreSQL

CREATE SEQUENCE customeridseq BIT_REVERSED_POSITIVE;

CREATE TABLE customers (
  customerid          bigint NOT NULL DEFAULT nextval('customeridseq'),
  customername        varchar(1024),
  isprocessing        boolean NOT NULL DEFAULT false,
  activeclaimid       varchar(36),
  processingexpiresat timestamptz,
  PRIMARY KEY (customerid)
);

CREATE TABLE customerworkitems (
  customerid  bigint NOT NULL,
  createdat   spanner.commit_timestamp NOT NULL DEFAULT spanner.pending_commit_timestamp(),
  batchindex  bigint NOT NULL DEFAULT 0,
  worktype    varchar(128) NOT NULL,
  workpayload jsonb NOT NULL,
  PRIMARY KEY (customerid, createdat, batchindex)
) INTERLEAVE IN PARENT customers ON DELETE CASCADE;

CREATE QUEUE customerdirtyqueue (
  customerid  bigint NOT NULL,
  messageid   varchar(36) NOT NULL,
  payload     bytea NOT NULL,
  PRIMARY KEY (customerid, messageid)
) INTERLEAVE IN PARENT customers ON DELETE CASCADE;

このスキーマを導入すると、送信者とワーカーは次のワークフローを使用して調整します。

  1. 順序付けされたタスクとウェイクアップ メッセージを挿入する: 送信者トランザクションで、タスクを CustomerWorkItems に挿入し(PENDING_COMMIT_TIMESTAMP() と 0 ベースの BatchIndex を使用して、同じトランザクション内の複数のタスクを順序付けします)、空のペイロード(b'')を含む単一のウェイクアップ メッセージを CustomerDirtyQueue に挿入します。
  2. エンティティの要求、処理、解放を 3 つのステップで行います。
    • ステップ 1(トランザクション 1 でエンティティを要求する): ワーカーが RECEIVE_CustomerDirtyQueue からウェイクアップ メッセージを受信すると、短い読み取り / 書き込みトランザクションを実行します。
      1. Customers を確認し、受信したウェイクアップ メッセージ(DELETE ... ASSERT_ROWS_MODIFIED 1)を確認します。別のワーカーがすでにアクティブなクレーム(IsProcessing = TRUE と ProcessingExpiresAt > CURRENT_TIMESTAMP())を保持している場合は、トランザクション 1 を commit して終了します。アクティブなワーカーは、クレームを解放する前に残りのタスクを確認します。
      2. それ以外の場合は、CreatedAt ASC, BatchIndex ASC で並べ替えられた CustomerWorkItems から最も古いタスクのバッチ(LIMIT 25 など)を読み取り、残りの期限切れのフォールバック メッセージ(MessageId が以前の ActiveClaimId であるもの)を削除します。
      3. タスクが返された場合は、Customers に IsProcessing = TRUE、ActiveClaimId、ProcessingExpiresAt(10 秒後など)を設定し、ProcessingExpiresAt にスケジュールされた CustomerDirtyQueue にフォールバック メッセージ(MessageId = ActiveClaimId)を挿入します。タスクが残っていない場合は、IsProcessing = FALSE、ActiveClaimId = NULL、ProcessingExpiresAt = NULL をリセットします。
    • ステップ 2(トランザクション外でタスクを処理する): トランザクション 1 が commit されると、ワーカーはアプリケーション コードでタスクを順番に実行します。タスクが失敗すると、ワーカーはバッチを早期に停止し、ステップ 3 を実行して、失敗したタスクを再試行する前に完了したタスクを削除します。
    • ステップ 3(完了したタスクを削除し、トランザクション 2 でエンティティを解放する): ワーカーは 2 番目の短い読み取り / 書き込みトランザクションを開き、ASSERT_ROWS_MODIFIED 1 を使用して CustomerDirtyQueue からフォールバック メッセージ(ActiveClaimId)を削除し、完了したタスクを CustomerWorkItems から削除します。CustomerWorkItems にタスクが残っている場合は、新しいウェイクアップ メッセージを挿入し、Customers の IsProcessing = FALSE、ActiveClaimId = NULL、ProcessingExpiresAt = NULL をリセットします。

このパターンでは、次の理由により、エンティティごとの厳密な順序付けと高スループットが維持されます。

  • commit タイムスタンプの順序付け: (CustomerId, CreatedAt, BatchIndex) をキーとして CustomerWorkItems にタスクを保存すると、複数の送信者が同時に書き込みを行っても、すべてのタスクがトランザクションの commit タイムスタンプ順に並べ替えられます。
  • 単一スプリットの局所性: Customers で CustomerWorkItems と CustomerDirtyQueue をインターリーブすると、エンティティのクレーム状態、タスク、ウェイクアップ メッセージが同じスプリットに保持されます。CustomerDirtyQueue.Payload を空(b'')のままにすると、キュー ストレージとメモリ内配信のオーバーヘッドも最小限に抑えられます。
  • 短期間のデータベース ロック: ステップ 2 で読み取り / 書き込みトランザクションを開いたままにすると、Customers 行がロックされ、同時送信者がブロックされます。クレーム(トランザクション 1)と完了(トランザクション 2)を 2 つの短いトランザクションに分割することで、アプリケーション コードの実行中にデータベース ロックを保持することなく、一度に 1 つのワーカーのみがエンティティを処理するようにします。
  • クラッシュ復旧とフェンシング: トランザクション 1 の最初のウェイクアップ メッセージをすぐに確認し、ProcessingExpiresAt でフォールバック メッセージ(ActiveClaimId)をスケジュールすると、固定の 10 秒の RECEIVE メッセージ リースが、構成可能なエンティティ クレームに置き換えられます。ステップ 2 でワーカーがクラッシュすると、フォールバック メッセージが成熟し、別のワーカーが起動します。低速ワーカーがクレームの期限切れ後に終了し、別のワーカーがすでに引き継いでいる場合、トランザクション 2 で ASSERT_ROWS_MODIFIED 1 を使用して ActiveClaimId を削除すると、OUT_OF_RANGE で失敗します。このエラーを伝播させる(または明示的にロールバックする)と、これらの書き込みが commit される前にトランザクション 2 が中止されます。

次のステートメントは、2 つの順序付きタスクと 1 つのウェイクアップ メッセージを 1 つの送信者トランザクションに挿入します。

GoogleSQL

-- 1. Insert ordered tasks for the entity using a 0-based BatchIndex
INSERT INTO CustomerWorkItems (CustomerId, CreatedAt, BatchIndex, WorkType, WorkPayload)
VALUES
  (456, PENDING_COMMIT_TIMESTAMP(), 0, 'ORDER_CREATED', JSON '{"order_id": 1001}'),
  (456, PENDING_COMMIT_TIMESTAMP(), 1, 'PAYMENT_CAPTURED', JSON '{"order_id": 1001}');

-- 2. Send a single lightweight wake-up message to the interleaved queue
INSERT INTO CustomerDirtyQueue (CustomerId, MessageId, DeliverTime, Payload)
VALUES (456, 'msg-uuid-1', CURRENT_TIMESTAMP(), b'');

PostgreSQL

-- 1. Insert ordered tasks for the entity using a 0-based batchindex
INSERT INTO customerworkitems (customerid, createdat, batchindex, worktype, workpayload)
VALUES
  (456, spanner.pending_commit_timestamp(), 0, 'ORDER_CREATED', '{"order_id": 1001}'::jsonb),
  (456, spanner.pending_commit_timestamp(), 1, 'PAYMENT_CAPTURED', '{"order_id": 1001}'::jsonb);

-- 2. Send a single lightweight wake-up message to the interleaved queue
INSERT INTO customerdirtyqueue (customerid, messageid, deliver_time, payload)
VALUES (456, 'msg-uuid-1', CURRENT_TIMESTAMP, CAST('' AS bytea));

次の SQL ステートメントは、ワーカーがウェイクアップ メッセージを受信し、トランザクション 1 でエンティティを要求し、トランザクション 2 でエンティティを解放する方法を示しています。

GoogleSQL

-- Stream wake-up messages from the queue:
SELECT CustomerId, MessageId, Payload, DeliverTime, SpannerLeaseToken
FROM RECEIVE_CustomerDirtyQueue(max_duration=>'20m', max_batch_size=>10);

-- Transaction 1 (claim the entity):
-- 1. Check whether another worker holds an active claim on the entity
SELECT
  IsProcessing,
  ActiveClaimId,
  IFNULL(ProcessingExpiresAt > CURRENT_TIMESTAMP(), FALSE) AS HasActiveClaim
FROM Customers
WHERE CustomerId = 456;

-- Always acknowledge the incoming wake-up message in Transaction 1.
-- Let OUT_OF_RANGE propagate to roll back the transaction so duplicate workers exit.
-- If IsProcessing = TRUE and HasActiveClaim = TRUE, commit after this DELETE and exit.
DELETE FROM CustomerDirtyQueue
WHERE CustomerId = 456 AND MessageId = 'msg-uuid-1'
ASSERT_ROWS_MODIFIED 1;

-- 2. Only if no active claim exists, read the next ordered batch of work items
SELECT CreatedAt, BatchIndex, WorkType, WorkPayload
FROM CustomerWorkItems
WHERE CustomerId = 456
ORDER BY CreatedAt ASC, BatchIndex ASC
LIMIT 25;

-- 3. Always clean up any remaining expired fallback message
--    (when ActiveClaimId IS NOT NULL AND ActiveClaimId != 'msg-uuid-1'):
DELETE FROM CustomerDirtyQueue
WHERE CustomerId = 456 AND MessageId = 'expired-claim-uuid';

-- 4. If step 2 returns work items, schedule a 10-second fallback message
--    and mark the entity as busy. (If step 2 returns no rows, clear any
--    expired claim fields on Customers instead.)
INSERT INTO CustomerDirtyQueue (CustomerId, MessageId, DeliverTime, Payload)
VALUES (456, 'claim-uuid-2', TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 10 SECOND), b'');

UPDATE Customers
SET IsProcessing = TRUE,
    ActiveClaimId = 'claim-uuid-2',
    ProcessingExpiresAt = TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 10 SECOND)
WHERE CustomerId = 456;

-- Transaction 2 (after processing the batch in order outside a transaction):
-- 1. Verify the claim is still active by deleting the fallback message.
--    Let OUT_OF_RANGE propagate to roll back the transaction if another worker took over.
DELETE FROM CustomerDirtyQueue
WHERE CustomerId = 456 AND MessageId = 'claim-uuid-2'
ASSERT_ROWS_MODIFIED 1;

-- 2. Delete the completed work items
DELETE FROM CustomerWorkItems
WHERE CustomerId = 456
  AND CreatedAt = TIMESTAMP '2026-05-01T12:00:00.123456Z'
  AND BatchIndex IN (0, 1);

-- 3. Check whether any unprocessed work items remain:
SELECT 1 FROM CustomerWorkItems
WHERE CustomerId = 456
LIMIT 1;

-- Run this INSERT only if the preceding SELECT returned a row:
INSERT INTO CustomerDirtyQueue (CustomerId, MessageId, DeliverTime, Payload)
VALUES (456, 'continuation-uuid-3', CURRENT_TIMESTAMP(), b'');

-- 4. Release the entity claim
UPDATE Customers
SET IsProcessing = FALSE, ActiveClaimId = NULL, ProcessingExpiresAt = NULL
WHERE CustomerId = 456 AND ActiveClaimId = 'claim-uuid-2';

PostgreSQL

-- Stream wake-up messages from the queue:
SELECT customerid, messageid, payload, deliver_time, spanner_lease_token
FROM spanner.receive_customerdirtyqueue(
    max_batch_size=>10, priority=>NULL, max_duration=>'20m');

-- Transaction 1 (claim the entity):
-- 1. Check whether another worker holds an active claim on the entity
SELECT
  isprocessing,
  activeclaimid,
  COALESCE(processingexpiresat > CURRENT_TIMESTAMP, false) AS hasactiveclaim
FROM customers
WHERE customerid = 456;

-- Always acknowledge the incoming wake-up message in Transaction 1.
-- Let OUT_OF_RANGE propagate to roll back the transaction so duplicate workers exit.
-- If isprocessing = true and hasactiveclaim = true, commit after this DELETE and exit.
DELETE FROM customerdirtyqueue
WHERE customerid = 456 AND messageid = 'msg-uuid-1'
ASSERT_ROWS_MODIFIED 1;

-- 2. Only if no active claim exists, read the next ordered batch of work items
SELECT createdat, batchindex, worktype, workpayload
FROM customerworkitems
WHERE customerid = 456
ORDER BY createdat ASC, batchindex ASC
LIMIT 25;

-- 3. Always clean up any remaining expired fallback message
--    (when activeclaimid IS NOT NULL AND activeclaimid != 'msg-uuid-1'):
DELETE FROM customerdirtyqueue
WHERE customerid = 456 AND messageid = 'expired-claim-uuid';

-- 4. If step 2 returns work items, schedule a 10-second fallback message
--    and mark the entity as busy. (If step 2 returns no rows, clear any
--    expired claim fields on customers instead.)
INSERT INTO customerdirtyqueue (customerid, messageid, deliver_time, payload)
VALUES (456, 'claim-uuid-2', CURRENT_TIMESTAMP + INTERVAL '10 SECOND', CAST('' AS bytea));

UPDATE customers
SET isprocessing = true,
    activeclaimid = 'claim-uuid-2',
    processingexpiresat = CURRENT_TIMESTAMP + INTERVAL '10 SECOND'
WHERE customerid = 456;

-- Transaction 2 (after processing the batch in order outside a transaction):
-- 1. Verify the claim is still active by deleting the fallback message.
--    Let OUT_OF_RANGE propagate to roll back the transaction if another worker took over.
DELETE FROM customerdirtyqueue
WHERE customerid = 456 AND messageid = 'claim-uuid-2'
ASSERT_ROWS_MODIFIED 1;

-- 2. Delete the completed work items
DELETE FROM customerworkitems
WHERE customerid = 456
  AND createdat = '2026-05-01T12:00:00.123456Z'::timestamptz
  AND batchindex IN (0, 1);

-- 3. Check whether any unprocessed work items remain:
SELECT 1 FROM customerworkitems
WHERE customerid = 456
LIMIT 1;

-- Run this INSERT only if the preceding SELECT returned a row:
INSERT INTO customerdirtyqueue (customerid, messageid, deliver_time, payload)
VALUES (456, 'continuation-uuid-3', CURRENT_TIMESTAMP, CAST('' AS bytea));

-- 4. Release the entity claim
UPDATE customers
SET isprocessing = false, activeclaimid = NULL, processingexpiresat = NULL
WHERE customerid = 456 AND activeclaimid = 'claim-uuid-2';

時間バッチ処理を使用して、バースト性の高いウェイクアップ メッセージの重複を除去する

エンティティが数秒以内に頻繁に更新のバーストを受信すると、トランザクションごとに個別のウェイクアップ メッセージを送信することで、不要なキュー書き込みと冗長なウェイクアップ配信が発生します。

書き込み時にウェイクアップ メッセージを結合するには、時間バッチ処理と決定論的な MessageId を組み合わせます。

  • MessageId を時間枠のバケット ID(5 秒のバケットなど)に設定します。
  • DeliverTime を次の時間枠に切り上げ、FARM_FINGERPRINT(または spanner.farm_fingerprint)で計算されたエンティティごとのオフセットを加算します。
  • GoogleSQL の INSERT OR IGNORE または PostgreSQL の INSERT ... SELECT ... FROM ... WHERE NOT EXISTS を使用して、ウェイクアップ メッセージを挿入します。

その 5 秒間のウィンドウ内の同じエンティティに対するすべてのトランザクションで、同じ MessageId と DeliverTime が計算されます。すべてのトランザクションがタスクを CustomerWorkItems に挿入しますが、ウィンドウ内の最初のトランザクションのみが CustomerDirtyQueue にウェイクアップ メッセージを書き込みます。エンティティごとのオフセットを追加すると、配信時間が 5 秒間隔に分散されるため、異なるエンティティがすべて同じ秒にトリガーされることはありません。

たとえば、次の送信者トランザクションは、ウェイクアップ メッセージを 5 秒のバケットに結合します。

GoogleSQL

-- 1. Insert the ordered work item
INSERT INTO CustomerWorkItems (CustomerId, CreatedAt, BatchIndex, WorkType, WorkPayload)
VALUES (456, PENDING_COMMIT_TIMESTAMP(), 0, 'METRIC_RECORDED', JSON '{"v": 42}');

-- 2. Coalesce wake-up messages into a 5-second window with a per-customer offset
INSERT OR IGNORE INTO CustomerDirtyQueue (CustomerId, MessageId, DeliverTime, Payload)
VALUES (
  456,
  CONCAT('bucket-', CAST(DIV(UNIX_SECONDS(CURRENT_TIMESTAMP()), 5) * 5 AS STRING)),
  TIMESTAMP_SECONDS(
    DIV(UNIX_SECONDS(CURRENT_TIMESTAMP()), 5) * 5 + 5
    + MOD(ABS(FARM_FINGERPRINT(CAST(456 AS STRING))), 5)
  ),
  b''
);

PostgreSQL

-- 1. Insert the ordered work item
INSERT INTO customerworkitems (customerid, createdat, batchindex, worktype, workpayload)
VALUES (456, spanner.pending_commit_timestamp(), 0, 'METRIC_RECORDED', '{"v": 42}'::jsonb);

-- 2. Coalesce wake-up messages into a 5-second window with a per-customer offset
INSERT INTO customerdirtyqueue (customerid, messageid, deliver_time, payload)
SELECT
  456,
  'bucket-' || bucket.start_sec::text,
  to_timestamp(
    bucket.start_sec + 5
    + (abs(spanner.farm_fingerprint(456::text)) % 5)
  ),
  CAST('' AS bytea)
FROM (
  SELECT (floor(EXTRACT(EPOCH FROM CURRENT_TIMESTAMP))::bigint / 5) * 5 AS start_sec
) AS bucket
WHERE NOT EXISTS (
  SELECT 1 FROM customerdirtyqueue
  WHERE customerid = 456
    AND messageid = 'bucket-' || bucket.start_sec::text
);

同時ウェイクアップ メッセージによるロック競合を減らす

同じビジー状態のエンティティに対する複数のウェイクアップ メッセージが同時に成熟すると、複数のワーカーが同時にトランザクション 1 を開始し、同じ Customers 行の読み取り / 書き込みロックを競合する可能性があります。

ホット エンティティのロック競合を減らすには、トランザクション 1 を開始する前にロックフリーの単一読み取り(client.Single())を実行して、IsProcessing = TRUE と ProcessingExpiresAt > CURRENT_TIMESTAMP() を確認します。エンティティがビジー状態の場合は、短いランダムな遅延(10 ~ 50 ミリ秒など)の間スリープしてから、トランザクション 1 を実行して Customers を再確認し、重複するウェイクアップ メッセージを確認します。

1 回の読み取りで、読み取り / 書き込みロックを取得せずにエンティティの申し立てステータスを確認します。ランダムな遅延により、後続の読み取り / 書き込みトランザクションがずらされるため、ワーカーが同じミリ秒で Customers 行を競合することはありません。ウェイクアップ メッセージを削除する前に、トランザクション 1 内の IsProcessing を必ず再確認してください。これにより、アクティブなワーカーが 1 回の読み取りの直後に終了した場合に、新しいタスクが未処理のままウェイクアップ メッセージが削除されることがなくなります。

たとえば、次の Go 関数は、エンティティがすでにビジー状態の場合にランダムな遅延を適用します。

func maybeJitterBeforeClaim(ctx context.Context, client *spanner.Client, customerID int64) error {
    iter := client.Single().Query(ctx, spanner.Statement{
        SQL: `SELECT IsProcessing AND IFNULL(ProcessingExpiresAt > CURRENT_TIMESTAMP(), FALSE) AS IsBusy
              FROM Customers WHERE CustomerId = @cid`,
        Params: map[string]interface{}{"cid": customerID},
    })
    defer iter.Stop()
    row, err := iter.Next()
    if errors.Is(err, iterator.Done) {
        return nil
    }
    if err != nil {
        return err
    }
    var isBusy bool
    if err := row.Columns(&isBusy); err != nil {
        return err
    }
    if isBusy {
        time.Sleep(time.Duration(10+rand.Intn(40)) * time.Millisecond)
    }
    return nil
}

長時間実行バッチと外部呼び出しを処理する

タスクのバッチの処理に最初の 10 秒の ProcessingExpiresAt ウィンドウよりも時間がかかる場合や、データベース トランザクションが中止されたときにロールバックされない外部 API(Payment Gateway や Webhook など)を呼び出す場合は、外部アクションの重複とクレームの早期期限切れを防ぐ必要があります。

外部呼び出しを保護し、低速バッチのエンティティ クレームを拡張するには:

  1. 決定論的なべき等性キーを外部 API に渡す: CustomerId、CreatedAt、BatchIndex を結合し(例: 456:2026-05-01T12:00:00.123456Z:0)、ステップ 2 でそのキーを下流サービスに渡します。
  2. 定期的なハートビートでエンティティ クレームを延長する: トランザクション 1 で初期 ProcessingExpiresAt とフォールバック DeliverTime を長く設定する(30 秒や 60 秒など)か、クレームの有効期限が切れる前にバックグラウンド ハートビート トランザクションを実行します(たとえば、10 秒のクレーム ウィンドウで 3 ~ 4 秒ごと)。各ハートビート トランザクションは、ASSERT_ROWS_MODIFIED 1 を使用して現在のフォールバック メッセージ(ActiveClaimId)を削除し、更新された将来の DeliverTime を含む新しいフォールバック メッセージを挿入し、Customers の ActiveClaimId と ProcessingExpiresAt を更新します。トランザクション 2 を開始する前に、ハートビートを停止します。

ステップ 2 はデータベース トランザクションの外部で実行され、キューの配信は少なくとも 1 回行われるため、外部 API 呼び出し後にワーカーがクラッシュすると、次のワーカーがタスクを再試行します。決定論的なべき等キーを渡すと、外部サービスは重複するリクエストを無視できます。詳細については、トランザクション アウトボックスをご覧ください。フォールバック メッセージを定期的に置き換えて ProcessingExpiresAt を延長すると、ワーカーが正常な間はエンティティ クレームがアクティブに保たれます。また、ワーカーがクラッシュした場合は、別のワーカーが引き継ぐことができます。

たとえば、次のハートビート トランザクションは、アクティブなエンティティ クレームを 10 秒延長します。

GoogleSQL

-- Run every 3 to 4 seconds on a 10-second claim window before starting Transaction 2:
DELETE FROM CustomerDirtyQueue
WHERE CustomerId = 456 AND MessageId = 'claim-uuid-2'
ASSERT_ROWS_MODIFIED 1;

INSERT INTO CustomerDirtyQueue (CustomerId, MessageId, DeliverTime, Payload)
VALUES (456, 'claim-uuid-3', TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 10 SECOND), b'');

UPDATE Customers
SET ActiveClaimId = 'claim-uuid-3',
    ProcessingExpiresAt = TIMESTAMP_ADD(CURRENT_TIMESTAMP(), INTERVAL 10 SECOND)
WHERE CustomerId = 456 AND ActiveClaimId = 'claim-uuid-2';

PostgreSQL

-- Run every 3 to 4 seconds on a 10-second claim window before starting Transaction 2:
DELETE FROM customerdirtyqueue
WHERE customerid = 456 AND messageid = 'claim-uuid-2'
ASSERT_ROWS_MODIFIED 1;

INSERT INTO customerdirtyqueue (customerid, messageid, deliver_time, payload)
VALUES (456, 'claim-uuid-3', CURRENT_TIMESTAMP + INTERVAL '10 SECOND', CAST('' AS bytea));

UPDATE customers
SET activeclaimid = 'claim-uuid-3',
    processingexpiresat = CURRENT_TIMESTAMP + INTERVAL '10 SECOND'
WHERE customerid = 456 AND activeclaimid = 'claim-uuid-2';

シャーディングとステイル読み取りを使用して大量のエンティティをスケーリングする

1 つのエンティティが 1 つの Spanner スプリットで処理できる数を超える書き込みを受信すると、すべてのタスクを 1 つの Customers スプリットに書き込むことで、書き込みホットスポットが作成されます。ただし、そのエンティティのタスクを commit 順に処理する必要がある場合でも、この処理は行われます。

グローバルな順序を維持しながら、大量のエンティティの書き込みスループットをスケーリングするには、N シャードに書き込みを分散し、ステイル読み取りを使用して定期的なスイーパー ワーカーと非同期でマージします。

  • 作業テーブルと重複除去テーブルをシャーディングする: PRIMARY KEY (ShardId, CustomerId)(0 から N - 1 までの ShardId)を使用して CustomerShards 親テーブルを作成し、(ShardId, CustomerId, CreatedAt, BatchIndex) をキーとするシャーディングされた作業テーブルをインターリーブします。ShardId を先頭のキー列にすると、書き込みが N スプリットに分散されます。再試行されたトランザクションが新しい PENDING_COMMIT_TIMESTAMP() を受け取ったときにタスク行が重複しないようにするには、(ShardId, CustomerId, BatchId) をキーとするバッチ重複除去テーブルを TTL ポリシーとインターリーブします。
  • キュー書き込みなしで各プロデューサー バッチを 1 つのシャードにルーティングする: 各プロデューサー トランザクションで、一意の BatchId(FARM_FINGERPRINT など)のハッシュから ShardId を計算し、キューに挿入せずに、重複除去テーブルとシャーディングされた作業テーブルの両方に挿入します。BatchId をハッシュすると、各プロデューサー トランザクションが 1 つのスプリット内に保持され、書き込みごとのキューのオーバーヘッドがなくなります。
  • ステイル読み取りと進行状況カーソルを使用して、シャードを順番にスイープする: アクティブなクレームと (LastSweptAt, LastBatchIndex, LastShardId) カーソルを、エンティティごとに 1 つの繰り返しスイーパー メッセージを含むインターリーブされたウェイクアップ キューを持つ別の CustomerSweeperState テーブルに保持します。トリガーされると、ワーカーはエンティティを要求し(順序付き作業テーブルとウェイクアップ キューを使用すると同じ要求とフォールバック メッセージ パターンを使用)、CreatedAt ASC, BatchIndex ASC, ShardId ASC で順序付けられた 10 秒の正確なステイル読み取りを使用して、カーソルの後にすべての N シャードにわたってクエリを実行し、バッチを順番に処理して、処理された行を削除する完了トランザクションを commit し、カーソルを進めて、次のスイープをスケジュールします。ステイル読み取りを使用すると、スプリット全体で処理中のプロデューサー書き込みがブロックされるのを回避できます。一方、カーソルは、ステイルネス ウィンドウ内で処理および削除された行をスキップします。

次のステップ