Memproses pesan secara berurutan per entitas

Antrean Spanner mengirimkan pesan setidaknya sekali dan dirancang untuk pemrosesan paralel di beberapa penerima. Jika beberapa pesan untuk entity yang sama (seperti akun pelanggan, pesanan, atau perangkat) dikirim ke antrean, worker yang berbeda dapat mengambil dan memprosesnya secara bersamaan. Meskipun satu pesan dikirim terlebih dahulu, penundaan atau percobaan ulang jaringan dapat memperlambat worker pertama sementara worker kedua menyelesaikan pesan berikutnya.

Jika setiap pesan di seluruh antrean diproses dalam urutan global yang ketat, satu worker yang lambat dapat menghentikan seluruh antrean (fenomena yang dikenal sebagai pemblokiran head-of-line). Namun, sebagian besar aplikasi tidak memerlukan setiap pesan di seluruh database untuk menunggu dalam satu antrean global. Sebagai gantinya, Anda hanya memerlukan tugas untuk entity yang sama agar berjalan secara berurutan, sementara tugas untuk entity yang berbeda berjalan secara paralel. Anda dapat menggunakan pola berikut untuk memproses pesan secara berurutan per entity berdasarkan workload Anda.

Pesan berantai untuk alur kerja berurutan

Jika tugas latar belakang untuk suatu entity terdiri dari langkah-langkah berurutan yang dependen (misalnya, step-1 diikuti oleh step-2 dan step-3), dan permintaan eksternal tidak menambahkan tugas yang bersaing ke alur kerja tersebut secara paralel, Anda ingin setiap langkah dimulai hanya setelah langkah sebelumnya selesai.

Untuk menerapkan pengurutan langkah demi langkah, masukkan hanya langkah pertama ke dalam antrean di awal. Saat worker selesai memproses langkah saat ini, worker akan mengonfirmasi pesan saat ini (DELETE ... ASSERT_ROWS_MODIFIED 1) dan menyisipkan pesan untuk langkah berikutnya dalam transaksi baca-tulis yang sama.

Karena pesan untuk langkah berikutnya tidak dibuat hingga langkah saat ini diselesaikan dan diakui dalam transaksi yang sama, dua langkah untuk alur kerja yang sama tidak akan pernah ada dalam antrean pada saat yang sama dan tidak dapat diproses secara tidak berurutan oleh worker serentak.

Misalnya, saat worker menyelesaikan step-1 alur kerja orientasi dan menjadwalkan 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));

Menggunakan tabel kerja yang diurutkan dan antrean bangun

Namun, jika Anda memerlukan semua tugas untuk entity tertentu agar berjalan dalam urutan commit, bahkan saat permintaan eksternal, webhook, atau tindakan pengguna menambahkan tugas baru saat tugas sebelumnya masih diproses, pola ini mendukung workload yang sesuai dengan kapasitas tulis satu pemisahan.

Untuk memproses tugas serentak secara berurutan per entity, perluas pola dirty flag dengan menyimpan tugas yang diurutkan dalam tabel yang disisipkan dan menggunakan antrean hanya untuk notifikasi bangun yang ringan.

Pertama, sisipkan tabel kerja yang diurutkan (menggunakan stempel waktu commit) dan antrean bangun dalam tabel parent entity yang melacak klaim aktif. Untuk menghindari hotspot di seluruh pemisahan, pilih kunci utama (seperti UUID atau urutan bit-reversed) yang mendistribusikan entity secara merata:

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;

Dengan skema ini, pengirim dan worker berkoordinasi menggunakan alur kerja berikut:

  1. Sisipkan tugas yang diurutkan dan pesan bangun: Dalam transaksi pengirim, sisipkan tugas ke dalam CustomerWorkItems (menggunakan PENDING_COMMIT_TIMESTAMP() dan BatchIndex berbasis nol untuk mengurutkan beberapa tugas dalam transaksi yang sama) dan sisipkan satu pesan bangun dengan payload kosong (b'') ke dalam CustomerDirtyQueue.
  2. Klaim, proses, dan rilis entitas dalam tiga langkah:
    • Langkah 1 (Klaim entity di Transaksi 1): Saat worker menerima pesan bangun dari RECEIVE_CustomerDirtyQueue, worker akan menjalankan transaksi baca-tulis singkat:
      1. Periksa Customers dan konfirmasi pesan bangun yang masuk (DELETE ... ASSERT_ROWS_MODIFIED 1). Jika worker lain sudah memegang klaim aktif (IsProcessing = TRUE dan ProcessingExpiresAt > CURRENT_TIMESTAMP()), commit Transaksi 1 dan keluar. Worker yang aktif memeriksa tugas yang tersisa sebelum melepaskan klaimnya.
      2. Jika tidak, baca batch tugas terlama (misalnya, LIMIT 25) dari CustomerWorkItems yang diurutkan berdasarkan CreatedAt ASC, BatchIndex ASC, dan hapus pesan penggantian yang sudah tidak berlaku (yang MessageId-nya adalah ActiveClaimId sebelumnya).
      3. Jika tugas ditampilkan, tetapkan IsProcessing = TRUE, ActiveClaimId, dan ProcessingExpiresAt (seperti 10 detik di masa mendatang) pada Customers, dan sisipkan pesan penggantian (MessageId = ActiveClaimId) ke dalam CustomerDirtyQueue yang dijadwalkan untuk ProcessingExpiresAt. Jika tidak ada tugas yang tersisa, reset IsProcessing = FALSE, ActiveClaimId = NULL, dan ProcessingExpiresAt = NULL.
    • Langkah 2 (Memproses tugas di luar transaksi): Setelah Transaksi 1 di-commit, worker menjalankan tugas secara berurutan dalam kode aplikasi. Jika tugas gagal, worker akan menghentikan batch lebih awal dan tetap menjalankan Langkah 3, sehingga tugas yang selesai akan dihapus sebelum mencoba ulang tugas yang gagal.
    • Langkah 3 (Menghapus tugas yang telah selesai dan merilis entity di Transaksi 2): Worker membuka transaksi baca-tulis singkat kedua, menghapus pesan penggantinya (ActiveClaimId) dari CustomerDirtyQueue dengan ASSERT_ROWS_MODIFIED 1, menghapus tugas yang telah selesai dari CustomerWorkItems, menyisipkan pesan bangun baru jika masih ada tugas di CustomerWorkItems, dan mereset IsProcessing = FALSE, ActiveClaimId = NULL, dan ProcessingExpiresAt = NULL di Customers.

Pola ini mempertahankan pengurutan per entitas yang ketat dan throughput yang tinggi karena alasan berikut:

  • Pengurutan stempel waktu commit: Menyimpan tugas di CustomerWorkItems yang di-key oleh (CustomerId, CreatedAt, BatchIndex) akan mengurutkan setiap tugas berdasarkan stempel waktu commit transaksinya, bahkan saat beberapa pengirim menulis secara serentak.
  • Lokalitas pemisahan tunggal: Interleaving CustomerWorkItems dan CustomerDirtyQueue di Customers mempertahankan status klaim, tugas, dan pesan bangun entitas dalam pemisahan yang sama. Membiarkan CustomerDirtyQueue.Payload kosong (b'') juga meminimalkan penyimpanan antrean dan overhead pengiriman dalam memori.
  • Kunci database berumur pendek: Membiarkan transaksi baca-tulis terbuka selama Langkah 2 akan mengunci baris Customers dan memblokir pengirim serentak. Memisahkan klaim (Transaksi 1) dan penyelesaian (Transaksi 2) menjadi dua transaksi singkat memastikan bahwa hanya satu worker yang memproses entity dalam satu waktu tanpa menahan kunci database saat kode aplikasi berjalan.
  • Pemulihan dan fencing error: Segera mengonfirmasi pesan pengaktifan awal di Transaksi 1 dan menjadwalkan pesan penggantian (ActiveClaimId) di ProcessingExpiresAt akan menggantikan sewa pesan RECEIVE 10 detik tetap dengan klaim entity yang dapat dikonfigurasi. Jika worker mengalami error selama Langkah 2, pesan penggantian akan matang dan mengaktifkan worker lain. Jika worker yang lambat selesai setelah klaimnya berakhir dan worker lain sudah mengambil alih, penghapusan ActiveClaimId dengan ASSERT_ROWS_MODIFIED 1 di Transaksi 2 akan gagal dengan OUT_OF_RANGE. Membiarkan error tersebut menyebar (atau melakukan roll back secara eksplisit) akan membatalkan Transaksi 2 sebelum operasi tulis tersebut dapat di-commit.

Pernyataan berikut menyisipkan dua tugas yang diurutkan dan pesan bangun dalam satu transaksi pengirim:

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));

Pernyataan SQL berikut menunjukkan cara worker menerima pesan bangun, mengklaim entity di Transaksi 1, dan merilis entity di Transaksi 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';

Menghapus duplikat pesan bangun yang meledak dengan pengelompokan temporal

Saat entity menerima burst update yang sering dalam beberapa detik, mengirimkan pesan bangun terpisah pada setiap transaksi akan membuat penulisan antrean yang tidak perlu dan pengiriman bangun yang redundan.

Untuk menggabungkan pesan bangun pada waktu penulisan, gabungkan pengelompokan temporal dengan MessageId deterministik:

  • Tetapkan MessageId ke ID bucket rentang waktu (misalnya, bucket 5 detik).
  • Membulatkan DeliverTime ke atas ke rentang waktu berikutnya ditambah offset per entity yang dihitung dengan FARM_FINGERPRINT (atau spanner.farm_fingerprint).
  • Sisipkan pesan bangun menggunakan INSERT OR IGNORE di GoogleSQL atau INSERT ... SELECT ... FROM ... WHERE NOT EXISTS di PostgreSQL.

Setiap transaksi untuk entity yang sama dalam periode 5 detik tersebut menghitung MessageId dan DeliverTime yang sama. Semua transaksi menyisipkan tugasnya ke dalam CustomerWorkItems, tetapi hanya transaksi pertama di jendela yang menulis pesan bangun ke CustomerDirtyQueue. Menambahkan offset per entity akan menyebarkan waktu pengiriman di seluruh interval 5 detik sehingga entity yang berbeda tidak semuanya dipicu pada detik yang sama persis.

Misalnya, transaksi pengirim berikut menggabungkan pesan bangun ke dalam bucket 5 detik:

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
);

Mengurangi pertentangan kunci dari pesan pengaktifan serentak

Jika beberapa pesan bangun untuk entity sibuk yang sama jatuh tempo pada saat yang sama, beberapa worker dapat memulai Transaksi 1 secara bersamaan dan bersaing untuk mendapatkan kunci baca-tulis pada baris Customers yang sama.

Untuk mengurangi pertentangan kunci pada entity panas, lakukan pembacaan tunggal (client.Single()) bebas kunci sebelum memulai Transaksi 1 untuk memeriksa apakah IsProcessing = TRUE dan ProcessingExpiresAt > CURRENT_TIMESTAMP(). Jika entity sedang sibuk, tunggu selama penundaan acak singkat (seperti 10 hingga 50 milidetik) sebelum menjalankan Transaksi 1 untuk memeriksa ulang Customers dan mengonfirmasi pesan bangun duplikat.

Satu pembacaan memeriksa status klaim entity tanpa memperoleh kunci baca-tulis, dan penundaan acak akan mengacak transaksi baca-tulis berikutnya sehingga worker tidak bersaing di baris Customers pada milidetik yang sama. Selalu periksa ulang IsProcessing di dalam Transaksi 1 sebelum menghapus pesan bangun, sehingga jika worker aktif selesai tepat setelah pembacaan tunggal, pesan bangun tidak akan dihapus saat tugas baru masih belum diproses.

Misalnya, fungsi Go berikut menerapkan penundaan acak saat entity sudah sibuk:

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
}

Menangani batch yang berjalan lama dan panggilan eksternal

Jika pemrosesan batch tugas memerlukan waktu lebih lama daripada periode ProcessingExpiresAt awal selama 10 detik, atau memanggil API eksternal (seperti gateway pembayaran atau webhook) yang tidak di-roll back saat transaksi database dibatalkan, Anda harus mencegah tindakan eksternal duplikat dan masa berlaku klaim yang berakhir sebelum waktunya.

Untuk melindungi panggilan eksternal dan memperpanjang klaim entity untuk batch yang lambat:

  1. Teruskan kunci idempotensi deterministik ke API eksternal: Gabungkan CustomerId, CreatedAt, dan BatchIndex (misalnya, 456:2026-05-01T12:00:00.123456Z:0) dan teruskan kunci tersebut ke layanan downstream selama Langkah 2.
  2. Perpanjang klaim entity dengan heartbeat berkala: Tetapkan ProcessingExpiresAt awal dan DeliverTime penggantian yang lebih lama (seperti 30 atau 60 detik) di Transaksi 1, atau jalankan transaksi heartbeat latar belakang sebelum klaim berakhir (misalnya, setiap 3 hingga 4 detik pada periode klaim 10 detik). Setiap transaksi heartbeat menghapus pesan penggantian saat ini (ActiveClaimId) dengan ASSERT_ROWS_MODIFIED 1, menyisipkan pesan penggantian baru dengan DeliverTime mendatang yang diperbarui, dan memperbarui ActiveClaimId dan ProcessingExpiresAt di Customers. Hentikan heartbeat sebelum memulai Transaksi 2.

Karena Langkah 2 berjalan di luar transaksi database dan pengiriman antrean dilakukan setidaknya sekali, error worker setelah panggilan API eksternal akan menyebabkan worker berikutnya mencoba ulang tugas. Dengan meneruskan kunci idempotensi deterministik, layanan eksternal dapat mengabaikan permintaan duplikat. Untuk mengetahui informasi selengkapnya, lihat Kotak keluar transaksional. Mengganti pesan penggantian secara berkala dan memperpanjang ProcessingExpiresAt akan membuat klaim entity tetap aktif selama worker responsif, sekaligus memungkinkan worker lain mengambil alih jika worker mengalami error.

Misalnya, transaksi heartbeat berikut memperpanjang klaim entity aktif selama 10 detik:

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';

Menskalakan entity bervolume tinggi dengan sharding dan stale read

Jika satu entity menerima lebih banyak operasi tulis daripada yang dapat ditangani oleh satu pemisahan Spanner, menulis setiap tugas ke dalam satu pemisahan Customers akan membuat hotspot tulis, meskipun Anda masih perlu memproses tugas untuk entity tersebut dalam urutan commit.

Untuk menskalakan throughput tulis untuk entity bervolume tinggi sekaligus mempertahankan pengurutan global, distribusikan penulisan di seluruh shard N dan gabungkan secara asinkron dengan worker sweeper berkala menggunakan pembacaan usang:

  • Melakukan sharding pada tabel pekerjaan dan penghapusan duplikat: Buat tabel induk CustomerShards dengan PRIMARY KEY (ShardId, CustomerId) (ShardId dari 0 hingga N - 1) dan lakukan interleave pada tabel pekerjaan yang di-sharding dengan kunci (ShardId, CustomerId, CreatedAt, BatchIndex). Menjadikan ShardId sebagai kolom kunci utama akan menyebarkan penulisan ke seluruh pemisahan N. Untuk mencegah baris tugas duplikat saat transaksi yang dicoba ulang menerima PENDING_COMMIT_TIMESTAMP() baru, gabungkan juga tabel penghapusan duplikat batch yang di-key oleh (ShardId, CustomerId, BatchId) dengan kebijakan TTL.
  • Merutekan setiap batch produsen ke satu shard tanpa penulisan antrean: Di setiap transaksi produsen, komputasi ShardId dari hash BatchId unik (seperti FARM_FINGERPRINT) dan sisipkan ke dalam tabel penghapusan duplikat dan tabel kerja yang di-sharding tanpa menyisipkan ke dalam antrean. Hashing BatchId mempertahankan setiap transaksi produsen dalam satu pemisahan dan menghilangkan overhead antrean per penulisan.
  • Menyapu shard secara berurutan menggunakan pembacaan yang tidak berlaku dan kursor progres: Pertahankan klaim aktif dan kursor (LastSweptAt, LastBatchIndex, LastShardId) dalam tabel CustomerSweeperState terpisah dengan antrean bangun yang disisipkan yang berisi satu pesan penyapu berulang per entity. Saat dipicu, worker mengklaim entity (menggunakan pola klaim dan pesan penggantian yang sama seperti Menggunakan tabel kerja yang diurutkan dan antrean bangun), membuat kueri di semua shard N setelah kursor menggunakan pembacaan keusangan persis 10 detik yang diurutkan berdasarkan CreatedAt ASC, BatchIndex ASC, ShardId ASC, memproses batch secara berurutan, dan melakukan transaksi penyelesaian yang menghapus baris yang diproses, memajukan kursor, dan menjadwalkan pembersihan berikutnya. Menggunakan pembacaan yang usang akan menghindari pemblokiran pada penulisan produsen yang sedang berlangsung di seluruh pemisahan, sementara kursor melewati baris yang diproses dan dihapus dalam periode keusangan.

Langkah berikutnya