Elabora i messaggi in ordine per entità

Le code di Spanner consegnano i messaggi almeno una volta e sono progettate per l'elaborazione parallela su più destinatari. Quando più messaggi per la stessa entità (ad esempio un account cliente, un ordine o un dispositivo) vengono inviati a una coda, worker diversi possono eseguirne il pull ed elaborarli contemporaneamente. Anche se un messaggio viene inviato per primo, un ritardo di rete o un nuovo tentativo può rallentare il primo worker mentre un secondo worker completa un messaggio successivo.

Se ogni messaggio nell'intera coda venisse elaborato in un ordine globale rigoroso, un worker lento potrebbe bloccare l'intera coda (un fenomeno noto come blocco head-of-line). Tuttavia, la maggior parte delle applicazioni non richiede che ogni messaggio nell'intero database attenda in un'unica coda globale. Devi solo fare in modo che le attività per la stessa entità vengano eseguite in ordine, mentre le attività per entità diverse vengono eseguite in parallelo. Puoi utilizzare i seguenti pattern per elaborare i messaggi in ordine per entità in base al tuo workload.

Concatenare i messaggi per i workflow sequenziali

Quando un job in background per un'entità è costituito da passaggi sequenziali dipendenti (ad esempio, step-1 seguito da step-2 e step-3) e le richieste esterne non aggiungono attività in conflitto a quel workflow in parallelo, vuoi che ogni passaggio inizi solo dopo il completamento del passaggio precedente.

Per applicare l'ordinamento passo passo, metti in coda inizialmente solo il primo passaggio. Quando un worker termina l'elaborazione del passaggio corrente, conferma il messaggio corrente (DELETE ... ASSERT_ROWS_MODIFIED 1) e inserisce il messaggio per il passaggio successivo nella stessa transazione di lettura/scrittura.

Poiché il messaggio per il passaggio successivo non viene creato finché il passaggio corrente non viene completato e confermato nella stessa transazione, due passaggi per lo stesso workflow non esistono mai contemporaneamente nella coda e non possono essere elaborati in ordine non corretto da worker simultanei.

Ad esempio, quando un lavoratore completa step-1 di un workflow di onboarding e pianifica 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));

Utilizza una tabella di lavoro ordinata e una coda di riattivazione

Tuttavia, quando devi eseguire tutte le attività per una determinata entità in ordine di commit, anche se le richieste esterne, i webhook o le azioni utente aggiungono nuove attività mentre quelle precedenti sono ancora in fase di elaborazione, questo pattern supporta workload che rientrano nella capacità di scrittura di una singola suddivisione.

Per elaborare le attività simultanee in ordine per entità, estendi il pattern dirty flag memorizzando le attività ordinate in una tabella con interleaving e utilizzando la coda solo per notifiche di attivazione leggere.

Innanzitutto, interfolia una tabella di lavoro ordinata (utilizzando i timestamp di commit) e una coda di riattivazione in una tabella di entità padre che monitora la richiesta attiva. Per evitare hotspot tra le suddivisioni, scegli una chiave primaria (ad esempio un UUID o una sequenza con bit invertiti) che distribuisca le entità in modo uniforme:

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;

Con questo schema, i mittenti e i worker si coordinano utilizzando il seguente workflow:

  1. Inserisci le attività ordinate e un messaggio di attivazione: nella transazione del mittente, inserisci le attività in CustomerWorkItems (utilizzando PENDING_COMMIT_TIMESTAMP() e un BatchIndex in base zero per ordinare più attività all'interno della stessa transazione) e inserisci un singolo messaggio di attivazione con un payload vuoto (b'') in CustomerDirtyQueue.
  2. Rivendica, elabora e rilascia l'entità in tre passaggi:
    • Passaggio 1 (rivendica l'entità nella Transazione 1): quando un worker riceve un messaggio di attivazione da RECEIVE_CustomerDirtyQueue, esegue una breve transazione di lettura-scrittura:
      1. Controlla Customers e conferma il messaggio di attivazione in arrivo (DELETE ... ASSERT_ROWS_MODIFIED 1). Se un altro worker ha già una rivendicazione attiva (IsProcessing = TRUE e ProcessingExpiresAt > CURRENT_TIMESTAMP()), esegui il commit della Transazione 1 ed esci. Il worker attivo verifica la presenza di attività rimanenti prima di rilasciare la richiesta.
      2. In caso contrario, leggi il batch di attività meno recente (ad esempio, LIMIT 25) da CustomerWorkItems ordinato per CreatedAt ASC, BatchIndex ASC, ed elimina eventuali messaggi di riserva scaduti rimanenti (il cui MessageId è il ActiveClaimId precedente).
      3. Se vengono restituite attività, imposta IsProcessing = TRUE, ActiveClaimId e ProcessingExpiresAt (ad esempio 10 secondi nel futuro) su Customers e inserisci un messaggio di riserva (MessageId = ActiveClaimId) in CustomerDirtyQueue pianificato per ProcessingExpiresAt. Se non rimangono attività, reimposta IsProcessing = FALSE, ActiveClaimId = NULL e ProcessingExpiresAt = NULL.
    • Passaggio 2 (elaborazione delle attività all'esterno di una transazione): dopo il commit della Transazione 1, il worker esegue le attività in sequenza nel codice dell'applicazione. Se un'attività non riesce, il worker interrompe il batch in anticipo ed esegue comunque il passaggio 3, in modo che le attività completate vengano eliminate prima di riprovare l'attività non riuscita.
    • Passaggio 3 (elimina le attività completate e rilascia l'entità nella Transazione 2): il worker apre una seconda breve transazione di lettura/scrittura, elimina il messaggio di riserva (ActiveClaimId) da CustomerDirtyQueue con ASSERT_ROWS_MODIFIED 1, elimina le attività completate da CustomerWorkItems, inserisce un nuovo messaggio di attivazione se rimangono altre attività in CustomerWorkItems e reimposta IsProcessing = FALSE, ActiveClaimId = NULL e ProcessingExpiresAt = NULL su Customers.

Questo pattern preserva l'ordinamento rigoroso per entità e un throughput elevato per i seguenti motivi:

  • Ordinamento in base al timestamp di commit: l'archiviazione delle attività in CustomerWorkItems con chiave (CustomerId, CreatedAt, BatchIndex) ordina ogni attività in base al timestamp di commit della transazione, anche quando più mittenti scrivono contemporaneamente.
  • Località a suddivisione singola: l'interleaving di CustomerWorkItems e CustomerDirtyQueue in Customers mantiene lo stato di rivendicazione, le attività e i messaggi di attivazione di un'entità nella stessa suddivisione. Se lasci vuoto CustomerDirtyQueue.Payload (b''), riduci al minimo anche lo spazio di archiviazione della coda e l'overhead di distribuzione in memoria.
  • Blocchi del database di breve durata: mantenere aperta una transazione di lettura/scrittura durante il passaggio 2 blocca la riga Customers e blocca i mittenti simultanei. La suddivisione della rivendicazione (Transazione 1) e del completamento (Transazione 2) in due transazioni brevi garantisce che un solo worker elabori un'entità alla volta senza bloccare il database durante l'esecuzione del codice dell'applicazione.
  • Ripristino da arresto anomalo e fencing: la conferma immediata del messaggio di attivazione iniziale nella Transazione 1 e la pianificazione di un messaggio di riserva (ActiveClaimId) alle ore ProcessingExpiresAt sostituisce il lease del messaggio RECEIVE fisso di 10 secondi con un claim di entità configurabile. Se il worker si arresta in modo anomalo durante il passaggio 2, il messaggio di riserva matura e attiva un altro worker. Se un worker lento termina dopo la scadenza della sua rivendicazione e un altro worker ha già preso il sopravvento, l'eliminazione di ActiveClaimId con ASSERT_ROWS_MODIFIED 1 nella Transazione 2 non va a buon fine con OUT_OF_RANGE. Se lasci che l'errore si propaghi (o esegui un rollback esplicito), la Transazione 2 viene interrotta prima che i commit di queste scritture possano essere eseguiti.

Le seguenti istruzioni inseriscono due attività ordinate e un messaggio di riattivazione in una singola transazione del mittente:

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

Le seguenti istruzioni SQL mostrano come un worker riceve i messaggi di attivazione, rivendica l'entità nella Transazione 1 e la rilascia nella Transazione 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';

Deduplica i messaggi di attivazione con burst con il raggruppamento in batch temporale

Quando un'entità riceve frequenti picchi di aggiornamenti nell'arco di pochi secondi, l'invio di un messaggio di attivazione separato per ogni transazione crea scritture in coda non necessarie e recapiti di attivazione ridondanti.

Per unire i messaggi di attivazione al momento della scrittura, combina il temporal batching con un MessageId deterministico:

  • Imposta MessageId sull'ID bucket della finestra temporale (ad esempio, un bucket di 5 secondi).
  • Arrotonda DeliverTime alla finestra temporale successiva più un offset per entità calcolato con FARM_FINGERPRINT (o spanner.farm_fingerprint).
  • Inserisci il messaggio di attivazione utilizzando INSERT OR IGNORE in GoogleSQL o INSERT ... SELECT ... FROM ... WHERE NOT EXISTS in PostgreSQL.

Ogni transazione per la stessa entità all'interno di questa finestra di 5 secondi calcola gli stessi valori MessageId e DeliverTime. Tutte le transazioni inseriscono le proprie attività in CustomerWorkItems, ma solo la prima transazione nella finestra scrive un messaggio di attivazione in CustomerDirtyQueue. L'aggiunta di un offset per entità distribuisce i tempi di consegna nell'intervallo di 5 secondi, in modo che entità diverse non vengano attivate tutte nello stesso secondo.

Ad esempio, la seguente transazione del mittente unisce i messaggi di attivazione in bucket di 5 secondi:

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

Riduci la contesa dei blocchi dovuta ai messaggi di attivazione simultanei

Quando più messaggi di attivazione per la stessa entità occupata maturano contemporaneamente, diversi worker possono avviare la Transazione 1 contemporaneamente e competere per i blocchi di lettura e scrittura sulla stessa riga Customers.

Per ridurre la contesa dei blocchi sulle entità hot, esegui una singola lettura senza blocchi (client.Single()) prima di avviare la Transazione 1 per verificare se IsProcessing = TRUE e ProcessingExpiresAt > CURRENT_TIMESTAMP(). Se l'entità è occupata, attendi un breve ritardo casuale (ad esempio da 10 a 50 millisecondi) prima di eseguire la Transazione 1 per ricontrollare Customers e confermare il messaggio di attivazione duplicato.

Una singola lettura controlla lo stato di rivendicazione dell'entità senza acquisire blocchi di lettura/scrittura e il ritardo casuale scagliona le transazioni di lettura/scrittura successive in modo che i worker non competano per la riga Customers nello stesso millisecondo. Controlla sempre di nuovo IsProcessing all'interno della Transazione 1 prima di eliminare il messaggio di attivazione, in modo che se il worker attivo termina subito dopo la singola lettura, il messaggio di attivazione non venga eliminato mentre le nuove attività rimangono non elaborate.

Ad esempio, la seguente funzione Go applica un ritardo casuale quando un'entità è già occupata:

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
}

Gestisci batch a lunga esecuzione e chiamate esterne

Quando l'elaborazione di un batch di attività richiede più tempo rispetto alla finestra iniziale di 10 secondi di ProcessingExpiresAt o chiama API esterne (come gateway di pagamento o webhook) di cui non viene eseguito il rollback quando una transazione del database viene interrotta, devi impedire azioni esterne duplicate e la scadenza prematura della richiesta.

Per proteggere le chiamate esterne ed estendere le rivendicazioni delle entità per i batch lenti:

  1. Passa una chiave di idempotenza deterministica alle API esterne: combina CustomerId, CreatedAt e BatchIndex (ad esempio 456:2026-05-01T12:00:00.123456Z:0) e passa la chiave ai servizi downstream durante il passaggio 2.
  2. Estendi la rivendicazione dell'entità con un heartbeat periodico: imposta un ProcessingExpiresAt iniziale e un DeliverTime di riserva più lunghi (ad esempio 30 o 60 secondi) nella Transazione 1 oppure esegui una transazione di heartbeat in background prima della scadenza della rivendicazione (ad esempio, ogni 3-4 secondi in una finestra di rivendicazione di 10 secondi). Ogni transazione di heartbeat elimina il messaggio di riserva corrente (ActiveClaimId) con ASSERT_ROWS_MODIFIED 1, inserisce un nuovo messaggio di riserva con un DeliverTime futuro aggiornato e aggiorna ActiveClaimId e ProcessingExpiresAt su Customers. Interrompi l'heartbeat prima di avviare la Transazione 2.

Poiché il passaggio 2 viene eseguito al di fuori di una transazione di database e la distribuzione della coda avviene almeno una volta, un arresto anomalo del worker dopo una chiamata API esterna fa sì che il worker successivo riprovi l'attività. Il passaggio di una chiave di idempotenza deterministica consente al servizio esterno di ignorare le richieste duplicate. Per saperne di più, consulta Outbox transazionale. La sostituzione periodica del messaggio di riserva e l'estensione di ProcessingExpiresAt mantengono attiva la rivendicazione dell'entità mentre il worker è integro, consentendo comunque a un altro worker di subentrare in caso di arresto anomalo del worker.

Ad esempio, la seguente transazione heartbeat estende una rivendicazione di entità attiva di 10 secondi:

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

Scala le entità con volumi elevati con lo sharding e le letture di dati obsoleti

Quando una singola entità riceve più scritture di quelle che una suddivisione Spanner può gestire, la scrittura di ogni attività in una singola suddivisione Customers crea un hotspot di scrittura, anche se devi comunque elaborare le attività per quell'entità in ordine di commit.

Per scalare il throughput di scrittura per un'entità con un volume elevato, mantenendo l'ordinamento globale, distribuisci le scritture su N shard e uniscile in modo asincrono con un worker di pulizia periodica utilizzando le letture di dati obsoleti:

  • Suddividi in shard le tabelle di lavoro e di deduplicazione: crea una tabella principale CustomerShards con PRIMARY KEY (ShardId, CustomerId) (ShardId da 0 a N - 1) e interfolia una tabella di lavoro suddivisa in shard con chiave (ShardId, CustomerId, CreatedAt, BatchIndex). Se imposti ShardId come colonna chiave principale, le scritture vengono distribuite su N suddivisioni. Per evitare righe di attività duplicate quando una transazione ritentata riceve un nuovo PENDING_COMMIT_TIMESTAMP(), interfolia anche una tabella di deduplicazione batch con chiave (ShardId, CustomerId, BatchId) con una policy TTL.
  • Instrada ogni batch di producer a uno shard senza scritture in coda: in ogni transazione del producer, calcola ShardId da un hash di un BatchId univoco (ad esempio FARM_FINGERPRINT) e inseriscilo sia nella tabella di deduplicazione sia nella tabella di lavoro con sharding senza inserirlo in una coda. L'hashing di BatchId mantiene ogni transazione del producer all'interno di una singola suddivisione ed elimina l'overhead della coda per scrittura.
  • Esegui lo sweep degli shard in ordine utilizzando una lettura di dati obsoleti e un cursore di avanzamento: mantieni un claim attivo e un cursore (LastSweptAt, LastBatchIndex, LastShardId) in una tabella CustomerSweeperState separata con una coda di attivazione interleaved contenente un messaggio di sweep ricorrente per entità. Quando viene attivato, il worker acquisisce l'entità (utilizzando lo stesso pattern di acquisizione e messaggio di riserva di Utilizza una tabella di lavoro ordinata e una coda di riattivazione), esegue query su tutti gli shard N dopo il cursore utilizzando una lettura con esatta inattività di 10 secondi ordinata per CreatedAt ASC, BatchIndex ASC, ShardId ASC, elabora il batch in ordine ed esegue il commit di una transazione di completamento che elimina le righe elaborate, fa avanzare il cursore e pianifica la scansione successiva. L'utilizzo di una lettura di dati obsoleti evita il blocco delle scritture del producer in corso tra le suddivisioni, mentre il cursore salta le righe che sono state elaborate ed eliminate entro la finestra di inattività.

Passaggi successivi