Traiter les messages dans l'ordre par entité

Les files d'attente Spanner distribuent les messages au moins une fois et sont conçues pour un traitement parallèle sur plusieurs destinataires. Lorsque plusieurs messages pour la même entité (un compte client, une commande ou un appareil, par exemple) sont envoyés à une file d'attente, différents nœuds de calcul peuvent les extraire et les traiter en même temps. Même si un message est envoyé en premier, un délai réseau ou une nouvelle tentative peut ralentir le premier nœud de calcul, tandis qu'un deuxième nœud de calcul termine un message ultérieur.

Si chaque message de l'ensemble de la file d'attente était traité dans un ordre global strict, un seul nœud de calcul lent pourrait bloquer l'ensemble de la file d'attente (phénomène appelé "blocage en tête de ligne"). Cependant, la plupart des applications n'ont pas besoin que chaque message de l'ensemble de la base de données attende dans une seule file d'attente globale. Au lieu de cela, vous n'avez besoin que des tâches de la même entité pour s'exécuter dans l'ordre, tandis que les tâches de différentes entités s'exécutent en parallèle. Vous pouvez utiliser les modèles suivants pour traiter les messages dans l'ordre par entité en fonction de votre charge de travail.

Enchaîner les messages pour les workflows séquentiels

Lorsqu'un job en arrière-plan pour une entité se compose d'étapes séquentielles dépendantes (par exemple, step-1 suivi de step-2 et step-3) et que les requêtes externes n'ajoutent pas de tâches concurrentes à ce workflow en parallèle, vous souhaitez que chaque étape ne démarre qu'une fois l'étape précédente terminée.

Pour appliquer un ordre étape par étape, ne mettez en file d'attente que la première étape au départ. Lorsqu'un nœud de calcul termine le traitement de l'étape en cours, il accuse réception du message actuel (DELETE ... ASSERT_ROWS_MODIFIED 1) et insère le message pour l'étape suivante dans la même transaction en lecture-écriture.

Étant donné que le message de l'étape suivante n'est pas créé tant que l'étape en cours n'est pas terminée et confirmée dans la même transaction, deux étapes du même workflow n'existent jamais simultanément dans la file d'attente et ne peuvent pas être traitées dans le désordre par des nœuds de calcul simultanés.

Par exemple, lorsqu'un nœud de calcul termine step-1 d'un workflow d'intégration et planifie 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));

Utiliser une table de travail ordonnée et une file d'attente de réveil

Toutefois, lorsque vous avez besoin que toutes les tâches d'une entité particulière s'exécutent dans l'ordre de commit, même si des requêtes externes, des webhooks ou des actions utilisateur ajoutent de nouvelles tâches alors que les tâches précédentes sont toujours en cours de traitement, ce modèle accepte les charges de travail qui correspondent à la capacité d'écriture d'une seule division.

Pour traiter les tâches simultanées dans l'ordre par entité, étendez le modèle de dirty flag en stockant les tâches ordonnées dans une table entrelacée et en n'utilisant la file d'attente que pour les notifications de réveil légères.

Tout d'abord, entrelacez une table de travail ordonnée (à l'aide de codes temporels de commit) et une file d'attente de réveil dans une table d'entités parentes qui suit la revendication active. Pour éviter les hotspots entre les divisions, choisissez une clé primaire (telle qu'un UUID ou une séquence d'inversion de bits) qui répartit uniformément les entités :

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;

Une fois ce schéma en place, les expéditeurs et les nœuds de calcul se coordonnent à l'aide du workflow suivant :

  1. Insérer des tâches ordonnées et un message de réveil : dans la transaction de l'expéditeur, insérez les tâches dans CustomerWorkItems (en utilisant PENDING_COMMIT_TIMESTAMP() et un BatchIndex basé sur zéro pour ordonner plusieurs tâches au sein de la même transaction) et insérez un seul message de réveil avec une charge utile vide (b'') dans CustomerDirtyQueue.
  2. Revendiquez, traitez et libérez l'entité en trois étapes :
    • Étape 1 (revendiquer l'entité dans la transaction 1) : lorsqu'un nœud de calcul reçoit un message de réveil de RECEIVE_CustomerDirtyQueue, il exécute une transaction de lecture-écriture courte :
      1. Vérifiez Customers et accusez réception du message de réveil entrant (DELETE ... ASSERT_ROWS_MODIFIED 1). Si un autre nœud de calcul détient déjà une revendication active (IsProcessing = TRUE et ProcessingExpiresAt > CURRENT_TIMESTAMP()), validez la transaction 1 et quittez. Le nœud de calcul actif vérifie s'il reste des tâches avant de libérer sa revendication.
      2. Sinon, lisez le lot de tâches le plus ancien (par exemple, LIMIT 25) de CustomerWorkItems classé par CreatedAt ASC, BatchIndex ASC, puis supprimez tout message de remplacement expiré restant (dont la valeur MessageId est la valeur ActiveClaimId précédente).
      3. Si des tâches sont renvoyées, définissez IsProcessing = TRUE, ActiveClaimId et ProcessingExpiresAt (par exemple, 10 secondes dans le futur) sur Customers, puis insérez un message de remplacement (MessageId = ActiveClaimId) dans CustomerDirtyQueue planifié pour ProcessingExpiresAt. S'il ne reste aucune tâche, réinitialisez IsProcessing = FALSE, ActiveClaimId = NULL et ProcessingExpiresAt = NULL.
    • Étape 2 (traiter les tâches en dehors d'une transaction) : une fois la transaction 1 validée, le nœud de calcul exécute les tâches de manière séquentielle dans le code de l'application. Si une tâche échoue, le nœud de calcul arrête le lot plus tôt et exécute toujours l'étape 3 afin que les tâches terminées soient supprimées avant de réessayer la tâche ayant échoué.
    • Étape 3 (supprimer les tâches terminées et libérer l'entité dans la transaction 2) : l'outil de traitement ouvre une deuxième transaction de lecture-écriture courte, supprime son message de remplacement (ActiveClaimId) de CustomerDirtyQueue avec ASSERT_ROWS_MODIFIED 1, supprime les tâches terminées de CustomerWorkItems, insère un nouveau message de réveil s'il reste des tâches dans CustomerWorkItems, et réinitialise IsProcessing = FALSE, ActiveClaimId = NULL et ProcessingExpiresAt = NULL sur Customers.

Ce modèle préserve l'ordre strict par entité et un débit élevé pour les raisons suivantes :

  • Ordre des codes temporels de commit : le stockage des tâches dans CustomerWorkItems avec la clé (CustomerId, CreatedAt, BatchIndex) classe chaque tâche selon le code temporel de commit de sa transaction, même lorsque plusieurs expéditeurs écrivent simultanément.
  • Localité à division unique : l'entrelacement de CustomerWorkItems et CustomerDirtyQueue dans Customers conserve l'état de revendication, les tâches et les messages de réveil d'une entité dans la même division. Laisser CustomerDirtyQueue.Payload vide (b'') permet également de réduire le stockage de la file d'attente et les frais généraux de distribution en mémoire.
  • Verrous de base de données de courte durée : le maintien d'une transaction en lecture-écriture ouverte à l'étape 2 verrouille la ligne Customers et bloque les expéditeurs simultanés. La division de la revendication (transaction 1) et de l'achèvement (transaction 2) en deux transactions courtes garantit qu'un seul nœud de calcul traite une entité à la fois sans maintenir de verrous de base de données pendant l'exécution du code d'application.
  • Récupération après plantage et cloisonnement : l'accusé de réception immédiat du message de réveil initial dans la transaction 1 et la planification d'un message de remplacement (ActiveClaimId) à ProcessingExpiresAt remplace le bail de message fixe de 10 secondes RECEIVE par une revendication d'entité configurable. Si le nœud de calcul plante à l'étape 2, le message de remplacement arrive à échéance et réveille un autre nœud de calcul. Si un nœud de calcul lent se termine après l'expiration de sa revendication et qu'un autre nœud de calcul a déjà pris le relais, la suppression de ActiveClaimId avec ASSERT_ROWS_MODIFIED 1 dans la transaction 2 échoue avec OUT_OF_RANGE. Laisser cette erreur se propager (ou effectuer un rollback explicite) annule la transaction 2 avant que ces écritures ne puissent être validées.

Les instructions suivantes insèrent deux tâches ordonnées et un message de réveil dans une seule transaction d'expéditeur :

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

Les instructions SQL suivantes montrent comment un nœud de calcul reçoit des messages de réveil, revendique l'entité dans la transaction 1 et la libère dans la transaction 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';

Dédupliquer les messages de réveil en rafale avec le traitement par lot temporel

Lorsqu'une entité reçoit de fréquentes rafales de mises à jour en quelques secondes, l'envoi d'un message de réveil distinct pour chaque transaction crée des écritures de file d'attente inutiles et des distributions de réveil redondantes.

Pour regrouper les messages de réveil au moment de l'écriture, combinez le traitement par lot temporel avec un MessageId déterministe :

  • Définissez MessageId sur l'ID de bucket de la période (par exemple, un bucket de 5 secondes).
  • Arrondissez DeliverTime à la période suivante, plus un décalage par entité calculé avec FARM_FINGERPRINT (ou spanner.farm_fingerprint).
  • Insérez le message de réveil à l'aide de INSERT OR IGNORE en GoogleSQL ou de INSERT ... SELECT ... FROM ... WHERE NOT EXISTS en PostgreSQL.

Chaque transaction pour la même entité au cours de cette période de cinq secondes calcule les mêmes valeurs MessageId et DeliverTime. Toutes les transactions insèrent leurs tâches dans CustomerWorkItems, mais seule la première transaction de la fenêtre écrit un message de réveil dans CustomerDirtyQueue. L'ajout d'un décalage par entité répartit les délais de livraison sur l'intervalle de cinq secondes, de sorte que les différentes entités ne se déclenchent pas toutes à la même seconde.

Par exemple, la transaction d'expéditeur suivante regroupe les messages de réveil dans des buckets de cinq secondes :

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

Réduire les conflits de verrouillage dus aux messages de réveil simultanés

Lorsque plusieurs messages de réveil pour la même entité occupée arrivent à échéance en même temps, plusieurs nœuds de calcul peuvent démarrer la transaction 1 simultanément et se disputer les verrous en lecture-écriture sur la même ligne Customers.

Pour réduire les conflits de verrouillage sur les entités actives, effectuez une lecture unique sans verrouillage (client.Single()) avant de démarrer la transaction 1 pour vérifier si IsProcessing = TRUE et ProcessingExpiresAt > CURRENT_TIMESTAMP(). Si l'entité est occupée, attendez un bref délai aléatoire (par exemple, 10 à 50 millisecondes) avant d'exécuter la transaction 1 pour revérifier Customers et accuser réception du message de réveil en double.

Une seule lecture vérifie l'état de la revendication de l'entité sans acquérir de verrous en lecture/écriture, et le délai aléatoire échelonne les transactions de lecture/écriture suivantes afin que les nœuds de calcul ne se disputent pas la ligne Customers à la même milliseconde. Vérifiez toujours à nouveau IsProcessing dans la transaction 1 avant de supprimer le message de réveil. Ainsi, si le nœud de calcul actif se termine juste après la lecture unique, le message de réveil n'est pas supprimé alors que de nouvelles tâches restent non traitées.

Par exemple, la fonction Go suivante applique un délai aléatoire lorsqu'une entité est déjà occupée :

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
}

Gérer les lots de longue durée et les appels externes

Lorsqu'un lot de tâches prend plus de temps à traiter que la fenêtre ProcessingExpiresAt initiale de 10 secondes, ou appelle des API externes (telles que des passerelles de paiement ou des webhooks) qui ne sont pas annulées lorsqu'une transaction de base de données est interrompue, vous devez empêcher les actions externes en double et l'expiration prématurée de la revendication.

Pour protéger les appels externes et étendre les revendications d'entité pour les lots lents :

  1. Transmettez une clé d'idempotence déterministe aux API externes : combinez CustomerId, CreatedAt et BatchIndex (par exemple, 456:2026-05-01T12:00:00.123456Z:0) et transmettez cette clé aux services en aval à l'étape 2.
  2. Prolongez la revendication d'entité avec un signal de pulsation périodique : définissez un ProcessingExpiresAt initial et un DeliverTime de remplacement plus longs (par exemple, 30 ou 60 secondes) dans la transaction 1, ou exécutez une transaction de pulsation en arrière-plan avant l'expiration de la revendication (par exemple, toutes les 3 à 4 secondes sur une fenêtre de revendication de 10 secondes). Chaque transaction de pulsation supprime le message de remplacement actuel (ActiveClaimId) avec ASSERT_ROWS_MODIFIED 1, insère un nouveau message de remplacement avec un DeliverTime futur actualisé, et met à jour ActiveClaimId et ProcessingExpiresAt sur Customers. Arrêtez la pulsation avant de démarrer la transaction 2.

Étant donné que l'étape 2 s'exécute en dehors d'une transaction de base de données et que la livraison de la file d'attente est effectuée au moins une fois, un plantage du nœud de calcul après un appel d'API externe entraîne une nouvelle tentative de la tâche par le nœud de calcul suivant. La transmission d'une clé d'idempotence déterministe permet au service externe d'ignorer les requêtes en double. Pour en savoir plus, consultez Boîte d'envoi transactionnelle. Le remplacement périodique du message de remplacement et l'extension de ProcessingExpiresAt maintiennent la revendication d'entité active tant que le nœud de calcul est opérationnel, tout en permettant à un autre nœud de calcul de prendre le relais en cas de plantage.

Par exemple, la transaction de signal de pulsation suivante prolonge une revendication d'entité active de 10 secondes :

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

Effectuer le scaling d'entités à volume élevé avec la segmentation et les lectures non actualisées

Lorsqu'une seule entité reçoit plus d'écritures qu'une seule division Spanner ne peut en gérer, l'écriture de chaque tâche dans une seule division Customers crée un hotspot d'écriture, même si vous devez toujours traiter les tâches pour cette entité dans l'ordre de commit.

Pour faire évoluer le débit d'écriture d'une entité à volume élevé tout en préservant l'ordre global, répartissez les écritures sur des segments N et fusionnez-les de manière asynchrone avec un nœud de calcul de nettoyage périodique à l'aide de lectures non actualisées :

  • Segmenter les tables de travail et de déduplication : créez une table parente CustomerShards avec PRIMARY KEY (ShardId, CustomerId) (ShardId de 0 à N - 1) et intercalez une table de travail segmentée avec la clé (ShardId, CustomerId, CreatedAt, BatchIndex). En faisant de ShardId la colonne de clé principale, les écritures sont réparties sur N divisions. Pour éviter les lignes de tâches en double lorsqu'une transaction relancée reçoit un nouveau PENDING_COMMIT_TIMESTAMP(), intercalez également une table de déduplication par lot indexée par (ShardId, CustomerId, BatchId) avec une règle TTL.
  • Acheminez chaque lot de producteurs vers un segment sans écritures en file d'attente : dans chaque transaction de producteur, calculez ShardId à partir d'un hachage d'un BatchId unique (tel que FARM_FINGERPRINT) et insérez-le dans la table de déduplication et dans la table de travail segmentée sans l'insérer dans une file d'attente. Le hachage de BatchId conserve chaque transaction de producteur dans une seule division et élimine la surcharge de file d'attente par écriture.
  • Balayez les segments dans l'ordre à l'aide d'une lecture non actualisée et d'un curseur de progression : conservez une revendication active et un curseur (LastSweptAt, LastBatchIndex, LastShardId) dans une table CustomerSweeperState distincte avec une file d'attente de réveil entrelacée contenant un message de balayage récurrent par entité. Lorsqu'il est déclenché, le nœud de calcul revendique l'entité (en utilisant le même modèle de revendication et de message de remplacement que Utiliser une table de travail ordonnée et une file d'attente de réveil), interroge tous les segments N après le curseur à l'aide d'une lecture d'obsolescence exacte de 10 secondes ordonnée par CreatedAt ASC, BatchIndex ASC, ShardId ASC, traite le lot dans l'ordre et valide une transaction d'achèvement qui supprime les lignes traitées, avance le curseur et planifie le prochain balayage. L'utilisation d'une lecture non actualisée évite de bloquer les écritures de producteur en cours sur les divisions, tandis que le curseur ignore les lignes qui ont été traitées et supprimées dans la fenêtre d'obsolescence.

Étapes suivantes