Nachrichten pro Entität in der richtigen Reihenfolge verarbeiten

Spanner-Warteschlangen stellen Nachrichten mindestens einmal zu und sind für die parallele Verarbeitung durch mehrere Empfänger konzipiert. Wenn mehrere Nachrichten für dieselbe Entität (z. B. ein Kundenkonto, eine Bestellung oder ein Gerät) an eine Warteschlange gesendet werden, können verschiedene Worker sie gleichzeitig abrufen und verarbeiten. Selbst wenn eine Nachricht zuerst gesendet wird, kann eine Netzwerkverzögerung oder ein Wiederholungsversuch den ersten Worker verlangsamen, während ein zweiter Worker eine spätere Nachricht abschließt.

Wenn jede Nachricht in der gesamten Warteschlange in einer strikten globalen Reihenfolge verarbeitet würde, könnte ein langsamer Worker die gesamte Warteschlange blockieren (ein Phänomen, das als Head-of-Line-Blocking bezeichnet wird). Die meisten Anwendungen benötigen jedoch nicht jede Nachricht in der gesamten Datenbank, um in einer einzigen globalen Warteschlange zu warten. Stattdessen müssen nur Aufgaben für dieselbe Entität nacheinander ausgeführt werden, während Aufgaben für verschiedene Entitäten parallel ausgeführt werden. Sie können die folgenden Muster verwenden, um Nachrichten pro Entität basierend auf Ihrer Arbeitslast in der richtigen Reihenfolge zu verarbeiten.

Nachrichten für sequenzielle Workflows verketten

Wenn ein Hintergrundjob für eine Entität aus abhängigen sequenziellen Schritten besteht (z. B. step-1 gefolgt von step-2 und step-3) und externe Anfragen diesem Workflow keine konkurrierenden Aufgaben parallel hinzufügen, soll jeder Schritt erst nach Abschluss des vorherigen Schritts gestartet werden.

Wenn Sie eine schrittweise Reihenfolge erzwingen möchten, stellen Sie zuerst nur den ersten Schritt in die Warteschlange. Wenn ein Worker die Verarbeitung des aktuellen Schritts abgeschlossen hat, bestätigt er die aktuelle Nachricht (DELETE ... ASSERT_ROWS_MODIFIED 1) und fügt die Nachricht für den nächsten Schritt in dieselbe Lese-/Schreibtransaktion ein.

Da die Nachricht für den nächsten Schritt erst erstellt wird, wenn der aktuelle Schritt abgeschlossen und in derselben Transaktion bestätigt wurde, befinden sich nie zwei Schritte für denselben Workflow gleichzeitig in der Warteschlange und können nicht von gleichzeitigen Workern in der falschen Reihenfolge verarbeitet werden.

Beispiel: Ein Worker schließt step-1 eines Onboarding-Workflows ab und plant 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));

Geordnete Arbeitstabelle und Aktivierungswarteschlange verwenden

Wenn jedoch alle Aufgaben für eine bestimmte Entität in der Commit-Reihenfolge ausgeführt werden müssen, auch wenn externe Anfragen, Webhooks oder Nutzeraktionen neue Aufgaben hinzufügen, während frühere Aufgaben noch verarbeitet werden, unterstützt dieses Muster Arbeitslasten, die in die Schreibkapazität eines einzelnen Splits passen.

Wenn Sie gleichzeitige Aufgaben pro Entität in der richtigen Reihenfolge verarbeiten möchten, erweitern Sie das Dirty-Flag-Muster, indem Sie geordnete Aufgaben in einer verschachtelten Tabelle speichern und die Warteschlange nur für einfache Aktivierungsbenachrichtigungen verwenden.

Verschachteln Sie zuerst eine geordnete Arbeitstabelle (mit Commit-Zeitstempeln) und eine Aktivierungswarteschlange in einer übergeordneten Entitätstabelle, die den aktiven Anspruch verfolgt. Wählen Sie einen Primärschlüssel (z. B. eine UUID oder eine bitumgekehrte Sequenz) aus, der Entitäten gleichmäßig verteilt, um Hotspots über Splits hinweg zu vermeiden:

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;

Mit diesem Schema koordinieren sich Sender und Worker über den folgenden Workflow:

  1. Geordnete Aufgaben und eine Aktivierungsnachricht einfügen: Fügen Sie in der Absendertransaktion die Aufgaben in CustomerWorkItems ein (mit PENDING_COMMIT_TIMESTAMP() und einem nullbasierten BatchIndex, um mehrere Aufgaben innerhalb derselben Transaktion zu ordnen) und fügen Sie eine einzelne Aktivierungsnachricht mit einer leeren Nutzlast (b'') in CustomerDirtyQueue ein.
  2. In drei Schritten können Sie die Entität beanspruchen, verarbeiten und freigeben:
    • Schritt 1 (Entität in Transaktion 1 beanspruchen): Wenn ein Worker eine Aktivierungsnachricht von RECEIVE_CustomerDirtyQueue empfängt, führt er eine kurze Lese-/Schreibtransaktion aus:
      1. Prüfen Sie Customers und bestätigen Sie die eingehende Aktivierungsnachricht (DELETE ... ASSERT_ROWS_MODIFIED 1). Wenn ein anderer Worker bereits einen aktiven Anspruch hat (IsProcessing = TRUE und ProcessingExpiresAt > CURRENT_TIMESTAMP()), führen Sie Transaktion 1 aus und beenden Sie den Vorgang. Der aktive Worker prüft, ob noch Aufgaben vorhanden sind, bevor er seinen Anspruch freigibt.
      2. Andernfalls lesen Sie den ältesten Batch von Aufgaben (z. B. LIMIT 25) aus CustomerWorkItems, sortiert nach CreatedAt ASC, BatchIndex ASC, und löschen Sie alle verbleibenden abgelaufenen Fallback-Nachrichten (deren MessageId die vorherige ActiveClaimId ist).
      3. Wenn Aufgaben zurückgegeben werden, legen Sie IsProcessing = TRUE, ActiveClaimId und ProcessingExpiresAt (z. B. 10 Sekunden in der Zukunft) für Customers fest und fügen Sie eine Fallback-Nachricht (MessageId = ActiveClaimId) in CustomerDirtyQueue ein, die für ProcessingExpiresAt geplant ist. Wenn keine Aufgaben mehr vorhanden sind, setzen Sie IsProcessing = FALSE, ActiveClaimId = NULL und ProcessingExpiresAt = NULL zurück.
    • Schritt 2 (Aufgaben außerhalb einer Transaktion verarbeiten): Nachdem Transaktion 1 abgeschlossen ist, führt der Worker die Aufgaben nacheinander im Anwendungscode aus. Wenn eine Aufgabe fehlschlägt, bricht der Worker den Batch vorzeitig ab und führt trotzdem Schritt 3 aus, damit abgeschlossene Aufgaben gelöscht werden, bevor die fehlgeschlagene Aufgabe noch einmal versucht wird.
    • Schritt 3 (Abgeschlossene Aufgaben löschen und Entität in Transaktion 2 freigeben): Der Worker öffnet eine zweite kurze Lese-/Schreibtransaktion, löscht seine Fallback-Nachricht (ActiveClaimId) aus CustomerDirtyQueue mit ASSERT_ROWS_MODIFIED 1, löscht die abgeschlossenen Aufgaben aus CustomerWorkItems, fügt eine neue Aktivierungsnachricht ein, wenn weitere Aufgaben in CustomerWorkItems verbleiben, und setzt IsProcessing = FALSE, ActiveClaimId = NULL und ProcessingExpiresAt = NULL auf Customers zurück.

Dieses Muster sorgt aus folgenden Gründen für eine strikte Reihenfolge pro Entität und einen hohen Durchsatz:

  • Reihenfolge nach Commit-Zeitstempel: Wenn Sie Aufgaben in CustomerWorkItems mit dem Schlüssel (CustomerId, CreatedAt, BatchIndex) speichern, wird jede Aufgabe nach ihrem Transaktions-Commit-Zeitstempel sortiert, auch wenn mehrere Absender gleichzeitig schreiben.
  • Lokalisierung mit einem einzelnen Split: Durch das Verschachteln von CustomerWorkItems und CustomerDirtyQueue in Customers werden der Anspruchsstatus, die Aufgaben und die Aktivierungsnachrichten einer Entität im selben Split beibehalten. Wenn Sie CustomerDirtyQueue.Payload leer lassen (b''), werden auch der Warteschlangenspeicher und der Overhead für die In-Memory-Zustellung minimiert.
  • Kurzlebige Datenbanksperren: Wenn Sie eine Lese-/Schreibtransaktion während Schritt 2 offen halten, wird die Zeile Customers gesperrt und gleichzeitige Absender werden blockiert. Durch die Aufteilung der Anforderung (Transaktion 1) und des Abschlusses (Transaktion 2) in zwei kurze Transaktionen wird sichergestellt, dass jeweils nur ein Worker eine Entität verarbeitet, ohne dass Datenbanksperren gehalten werden, während der Anwendungscode ausgeführt wird.
  • Absturzwiederherstellung und Fencing: Durch die sofortige Bestätigung der ersten Aktivierungsnachricht in Transaktion 1 und die Planung einer Fallback-Nachricht (ActiveClaimId) um ProcessingExpiresAt wird die feste 10-Sekunden-Nachrichten-Lease (RECEIVE) durch einen konfigurierbaren Entitätsanspruch ersetzt. Wenn der Worker während Schritt 2 abstürzt, wird die Fallback-Nachricht fällig und ein anderer Worker wird aktiviert. Wenn ein langsamer Worker nach Ablauf seines Anspruchs fertig ist und ein anderer Worker bereits übernommen hat, schlägt das Löschen von ActiveClaimId mit ASSERT_ROWS_MODIFIED 1 in Transaktion 2 mit OUT_OF_RANGE fehl. Wenn dieser Fehler weitergegeben wird (oder ein expliziter Rollback erfolgt), wird Transaktion 2 abgebrochen, bevor diese Schreibvorgänge festgeschrieben werden können.

Mit den folgenden Anweisungen werden zwei geordnete Aufgaben und eine Aktivierungsnachricht in eine einzelne Absendertransaktion eingefügt:

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

Die folgenden SQL-Anweisungen zeigen, wie ein Worker Aktivierungsnachrichten empfängt, die Entität in Transaktion 1 beansprucht und die Entität in Transaktion 2 freigibt:

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

Burst-Wecknachrichten mit zeitlichem Batching deduplizieren

Wenn eine Entität innerhalb weniger Sekunden häufige Aktualisierungen erhält, führt das Senden einer separaten Aktivierungsnachricht bei jeder Transaktion zu unnötigen Warteschlangenschreibvorgängen und redundanten Aktivierungszustellungen.

Wenn Sie Aktivierungsnachrichten beim Schreiben zusammenfassen möchten, kombinieren Sie zeitliches Batching mit einem deterministischen MessageId:

  • Legen Sie für MessageId die Bucket-ID des Zeitfensters fest (z. B. einen 5-Sekunden-Bucket).
  • Runden Sie DeliverTime auf das nächste Zeitfenster auf und addieren Sie einen Offset pro Entität, der mit FARM_FINGERPRINT (oder spanner.farm_fingerprint) berechnet wird.
  • Fügen Sie die Aktivierungsnachricht mit INSERT OR IGNORE in GoogleSQL oder INSERT ... SELECT ... FROM ... WHERE NOT EXISTS in PostgreSQL ein.

Für jede Transaktion für dieselbe Entität innerhalb dieses 5-Sekunden-Fensters werden dieselben MessageId- und DeliverTime-Werte berechnet. Alle Transaktionen fügen ihre Aufgaben in CustomerWorkItems ein, aber nur die erste Transaktion im Fenster schreibt eine Aktivierungsnachricht in CustomerDirtyQueue. Durch das Hinzufügen eines Offsets pro Entität werden die Lieferzeiten über das 5-Sekunden-Intervall verteilt, sodass verschiedene Entitäten nicht alle in derselben Sekunde ausgelöst werden.

In der folgenden Absendertransaktion werden beispielsweise Aktivierungsnachrichten in 5-Sekunden-Buckets zusammengefasst:

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

Sperrkonflikte durch gleichzeitige Aktivierungsnachrichten reduzieren

Wenn mehrere Aktivierungsnachrichten für dieselbe ausgelastete Entität gleichzeitig fällig werden, können mehrere Worker gleichzeitig Transaktion 1 starten und um Lese-/Schreibsperren für dieselbe Customers-Zeile konkurrieren.

Um Sperrkonflikte bei Hot Entities zu reduzieren, führen Sie vor dem Start von Transaktion 1 einen sperrfreien einzelnen Lesevorgang (client.Single()) aus, um zu prüfen, ob IsProcessing = TRUE und ProcessingExpiresAt > CURRENT_TIMESTAMP(). Wenn die Entität beschäftigt ist, wird eine kurze zufällige Verzögerung (z. B. 10 bis 50 Millisekunden) eingelegt, bevor Transaktion 1 ausgeführt wird, um Customers noch einmal zu prüfen und die doppelte Aktivierungsnachricht zu bestätigen.

Bei einem einzelnen Lesevorgang wird der Anspruchsstatus der Entität geprüft, ohne dass Lese-/Schreibsperren erworben werden. Durch die zufällige Verzögerung werden die nachfolgenden Lese-/Schreibtransaktionen gestaffelt, sodass Worker nicht in derselben Millisekunde um die Zeile Customers konkurrieren. Prüfen Sie IsProcessing in Transaktion 1 immer noch einmal, bevor Sie die Aktivierungsnachricht löschen. Wenn der aktive Worker direkt nach dem einzelnen Lesevorgang fertig ist, wird die Aktivierungsnachricht so nicht gelöscht, während neue Aufgaben unverarbeitet bleiben.

Die folgende Go-Funktion wendet beispielsweise eine zufällige Verzögerung an, wenn eine Entität bereits beschäftigt ist:

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
}

Batches mit langer Ausführungszeit und externe Aufrufe verarbeiten

Wenn die Verarbeitung eines Aufgabenbatches länger als das anfängliche 10-Sekunden-Fenster von ProcessingExpiresAt dauert oder externe APIs (z. B. Zahlungs-Gateways oder Webhooks) aufgerufen werden, die beim Abbruch einer Datenbanktransaktion nicht zurückgesetzt werden, müssen Sie doppelte externe Aktionen und einen vorzeitigen Ablauf des Anspruchs verhindern.

So schützen Sie externe Aufrufe und erweitern Entitätsansprüche für langsame Batches:

  1. Deterministischen Idempotenzschlüssel an externe APIs übergeben: Kombinieren Sie CustomerId, CreatedAt und BatchIndex (z. B. 456:2026-05-01T12:00:00.123456Z:0) und übergeben Sie diesen Schlüssel in Schritt 2 an nachgelagerte Dienste.
  2. Entitätsanspruch mit einem regelmäßigen Heartbeat verlängern: Legen Sie entweder in Transaktion 1 einen längeren anfänglichen ProcessingExpiresAt und Fallback-DeliverTime (z. B. 30 oder 60 Sekunden) fest oder führen Sie eine Heartbeat-Transaktion im Hintergrund aus, bevor der Anspruch abläuft (z. B. alle 3 bis 4 Sekunden bei einem 10-Sekunden-Anspruchsfenster). Bei jeder Heartbeat-Transaktion wird die aktuelle Fallback-Nachricht (ActiveClaimId) mit ASSERT_ROWS_MODIFIED 1 gelöscht, eine neue Fallback-Nachricht mit einem aktualisierten zukünftigen DeliverTime eingefügt und ActiveClaimId und ProcessingExpiresAt in Customers aktualisiert. Beenden Sie den Heartbeat, bevor Sie Transaktion 2 starten.

Da Schritt 2 außerhalb einer Datenbanktransaktion ausgeführt wird und die Zustellung in der Warteschlange mindestens einmal erfolgt, führt ein Worker-Absturz nach einem externen API-Aufruf dazu, dass der nächste Worker die Aufgabe wiederholt. Wenn Sie einen deterministischen Idempotenzschlüssel übergeben, kann der externe Dienst doppelte Anfragen ignorieren. Weitere Informationen finden Sie unter Transaktions-Outbox. Durch regelmäßiges Ersetzen der Fallback-Nachricht und Verlängern von ProcessingExpiresAt bleibt der Entitätsanspruch aktiv, solange der Worker fehlerfrei ist. Gleichzeitig kann ein anderer Worker übernehmen, wenn der Worker abstürzt.

Mit der folgenden Heartbeat-Transaktion wird beispielsweise ein aktiver Entitätsanspruch um 10 Sekunden verlängert:

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

Entitäten mit hohem Volumen durch Sharding und Lesevorgänge veralteter Daten skalieren

Wenn eine einzelne Entität mehr Schreibvorgänge empfängt, als ein einzelner Spanner-Split verarbeiten kann, wird durch das Schreiben jeder Aufgabe in einen einzelnen Customers-Split ein Schreib-Hotspot erstellt, auch wenn Sie Aufgaben für diese Entität weiterhin in der Commit-Reihenfolge verarbeiten müssen.

Wenn Sie den Schreibdurchsatz für eine Entität mit hohem Volumen skalieren und gleichzeitig die globale Reihenfolge beibehalten möchten, verteilen Sie die Schreibvorgänge auf N Shards und führen Sie sie asynchron mit einem regelmäßigen Sweeper-Worker zusammen, der Lesevorgänge veralteter Daten verwendet:

  • Arbeits- und Deduplizierungstabellen fragmentieren: Erstellen Sie eine übergeordnete CustomerShards-Tabelle mit PRIMARY KEY (ShardId, CustomerId) (ShardId von 0 bis N - 1) und verschachteln Sie eine fragmentierte Arbeitstabelle mit dem Schlüssel (ShardId, CustomerId, CreatedAt, BatchIndex). Wenn Sie ShardId zur führenden Schlüsselspalte machen, werden Schreibvorgänge auf N Splits verteilt. Um doppelte Aufgabenzeilen zu vermeiden, wenn eine wiederholte Transaktion eine neue PENDING_COMMIT_TIMESTAMP() erhält, verschachteln Sie auch eine Batch-Deduplizierungstabelle mit dem Schlüssel (ShardId, CustomerId, BatchId) mit einer TTL-Richtlinie.
  • Jeden Producer-Batch ohne Warteschlangenschreibvorgänge an einen Shard weiterleiten: Berechnen Sie in jeder Producer-Transaktion ShardId aus einem Hash eines eindeutigen BatchId (z. B. FARM_FINGERPRINT) und fügen Sie ihn sowohl in die Deduplizierungstabelle als auch in die fragmentierte Arbeitstabelle ein, ohne ihn in eine Warteschlange einzufügen. Durch das Hashen von BatchId wird jede Ersteller-Transaktion innerhalb eines einzelnen Splits gehalten und der Overhead pro Schreibvorgang in der Warteschlange eliminiert.
  • Shards der Reihe nach mit einem Lesevorgang veralteter Daten und einem Fortschrittscursor bereinigen: Behalten Sie eine aktive Anforderung und einen (LastSweptAt, LastBatchIndex, LastShardId)-Cursor in einer separaten CustomerSweeperState-Tabelle mit einer verschachtelten Aktivierungswarteschlange bei, die eine wiederkehrende Sweeper-Nachricht pro Entität enthält. Wenn der Worker ausgelöst wird, beansprucht er die Entität (mit demselben Anspruchs- und Fallback-Nachrichtenmuster wie unter Geordnete Arbeitstabelle und Aktivierungswarteschlange verwenden). Er fragt alle N-Shards nach dem Cursor mit einem 10-Sekunden-Lesevorgang mit exakter Aktualität ab, sortiert nach CreatedAt ASC, BatchIndex ASC, ShardId ASC, verarbeitet den Batch in der richtigen Reihenfolge und führt eine Abschlusstransaktion aus, die die verarbeiteten Zeilen löscht, den Cursor vorrückt und den nächsten Durchlauf plant. Durch die Verwendung eines Lesevorgangs veralteter Daten wird das Blockieren von laufenden Schreibvorgängen von Producern über Splits hinweg vermieden, während der Cursor Zeilen überspringt, die innerhalb des Zeitfensters für veraltete Daten verarbeitet und gelöscht wurden.

Nächste Schritte