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:
- Geordnete Aufgaben und eine Aktivierungsnachricht einfügen: Fügen Sie in der Absendertransaktion die Aufgaben in
CustomerWorkItemsein (mitPENDING_COMMIT_TIMESTAMP()und einem nullbasiertenBatchIndex, um mehrere Aufgaben innerhalb derselben Transaktion zu ordnen) und fügen Sie eine einzelne Aktivierungsnachricht mit einer leeren Nutzlast (b'') inCustomerDirtyQueueein. - 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_CustomerDirtyQueueempfängt, führt er eine kurze Lese-/Schreibtransaktion aus:- Prüfen Sie
Customersund bestätigen Sie die eingehende Aktivierungsnachricht (DELETE ... ASSERT_ROWS_MODIFIED 1). Wenn ein anderer Worker bereits einen aktiven Anspruch hat (IsProcessing = TRUEundProcessingExpiresAt > 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. - Andernfalls lesen Sie den ältesten Batch von Aufgaben (z. B.
LIMIT 25) ausCustomerWorkItems, sortiert nachCreatedAt ASC, BatchIndex ASC, und löschen Sie alle verbleibenden abgelaufenen Fallback-Nachrichten (derenMessageIddie vorherigeActiveClaimIdist). - Wenn Aufgaben zurückgegeben werden, legen Sie
IsProcessing = TRUE,ActiveClaimIdundProcessingExpiresAt(z. B. 10 Sekunden in der Zukunft) fürCustomersfest und fügen Sie eine Fallback-Nachricht (MessageId = ActiveClaimId) inCustomerDirtyQueueein, die fürProcessingExpiresAtgeplant ist. Wenn keine Aufgaben mehr vorhanden sind, setzen SieIsProcessing = FALSE,ActiveClaimId = NULLundProcessingExpiresAt = NULLzurück.
- Prüfen Sie
- 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) ausCustomerDirtyQueuemitASSERT_ROWS_MODIFIED 1, löscht die abgeschlossenen Aufgaben ausCustomerWorkItems, fügt eine neue Aktivierungsnachricht ein, wenn weitere Aufgaben inCustomerWorkItemsverbleiben, und setztIsProcessing = FALSE,ActiveClaimId = NULLundProcessingExpiresAt = NULLaufCustomerszurück.
- Schritt 1 (Entität in Transaktion 1 beanspruchen): Wenn ein Worker eine Aktivierungsnachricht von
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
CustomerWorkItemsmit 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
CustomerWorkItemsundCustomerDirtyQueueinCustomerswerden der Anspruchsstatus, die Aufgaben und die Aktivierungsnachrichten einer Entität im selben Split beibehalten. Wenn SieCustomerDirtyQueue.Payloadleer 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
Customersgesperrt 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) umProcessingExpiresAtwird 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 vonActiveClaimIdmitASSERT_ROWS_MODIFIED 1in Transaktion 2 mitOUT_OF_RANGEfehl. 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
MessageIddie Bucket-ID des Zeitfensters fest (z. B. einen 5-Sekunden-Bucket). - Runden Sie
DeliverTimeauf das nächste Zeitfenster auf und addieren Sie einen Offset pro Entität, der mitFARM_FINGERPRINT(oderspanner.farm_fingerprint) berechnet wird. - Fügen Sie die Aktivierungsnachricht mit
INSERT OR IGNOREin GoogleSQL oderINSERT ... SELECT ... FROM ... WHERE NOT EXISTSin 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:
- Deterministischen Idempotenzschlüssel an externe APIs übergeben: Kombinieren Sie
CustomerId,CreatedAtundBatchIndex(z. B.456:2026-05-01T12:00:00.123456Z:0) und übergeben Sie diesen Schlüssel in Schritt 2 an nachgelagerte Dienste. - Entitätsanspruch mit einem regelmäßigen Heartbeat verlängern: Legen Sie entweder in Transaktion 1 einen längeren anfänglichen
ProcessingExpiresAtund 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) mitASSERT_ROWS_MODIFIED 1gelöscht, eine neue Fallback-Nachricht mit einem aktualisierten zukünftigenDeliverTimeeingefügt undActiveClaimIdundProcessingExpiresAtinCustomersaktualisiert. 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 mitPRIMARY KEY (ShardId, CustomerId)(ShardIdvon0bisN - 1) und verschachteln Sie eine fragmentierte Arbeitstabelle mit dem Schlüssel(ShardId, CustomerId, CreatedAt, BatchIndex). Wenn SieShardIdzur führenden Schlüsselspalte machen, werden Schreibvorgänge aufNSplits verteilt. Um doppelte Aufgabenzeilen zu vermeiden, wenn eine wiederholte Transaktion eine neuePENDING_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
ShardIdaus einem Hash eines eindeutigenBatchId(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 vonBatchIdwird 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 separatenCustomerSweeperState-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 alleN-Shards nach dem Cursor mit einem 10-Sekunden-Lesevorgang mit exakter Aktualität ab, sortiert nachCreatedAt 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
- Informationen zur Verwendung von Spanner-Warteschlangen, einschließlich Best Practices und Monitoring
- Weitere Szenarien und Beispiele für Cloud Spanner-Warteschlangen ansehen
- Genau einmalige Verarbeitung und höchstens einmalige Bestätigung
- Konfigurieren Sie die Zugriffssteuerung mit der detaillierten Zugriffssteuerung für Warteschlangen.