Procesa mensajes en orden por entidad

Las colas de Spanner entregan mensajes al menos una vez y están diseñadas para el procesamiento paralelo en varios receptores. Cuando se envían varios mensajes para la misma entidad (como una cuenta de cliente, un pedido o un dispositivo) a una cola, diferentes trabajadores pueden extraerlos y procesarlos al mismo tiempo. Incluso si se envía un mensaje primero, una demora o un reintento de red puede ralentizar al primer trabajador mientras un segundo trabajador finaliza un mensaje posterior.

Si todos los mensajes de toda la cola se procesaran en un orden global estricto, un trabajador lento podría detener toda la cola (un fenómeno conocido como bloqueo de encabezado de línea). Sin embargo, la mayoría de las aplicaciones no necesitan que todos los mensajes de la base de datos esperen en una sola línea global. En cambio, solo necesitas que las tareas de la misma entidad se ejecuten en orden, mientras que las tareas de diferentes entidades se ejecutan en paralelo. Puedes usar los siguientes patrones para procesar mensajes en orden por entidad según tu carga de trabajo.

Encadena mensajes para flujos de trabajo secuenciales

Cuando un trabajo en segundo plano para una entidad consiste en pasos secuenciales dependientes (por ejemplo, step-1 seguido de step-2 y step-3), y las solicitudes externas no agregan tareas en competencia a ese flujo de trabajo en paralelo, querrás que cada paso comience solo después de que se complete el paso anterior.

Para aplicar el orden paso a paso, pon en cola solo el primer paso inicialmente. Cuando un trabajador termina de procesar el paso actual, confirma el mensaje actual (DELETE ... ASSERT_ROWS_MODIFIED 1) y, luego, inserta el mensaje para el siguiente paso en la misma transacción de lectura y escritura.

Debido a que el mensaje para el siguiente paso no se crea hasta que el paso actual se completa y se confirma en la misma transacción, nunca existen dos pasos para el mismo flujo de trabajo en la cola al mismo tiempo y los trabajadores simultáneos no pueden procesarlos de forma desordenada.

Por ejemplo, cuando un trabajador finaliza step-1 de un flujo de trabajo de incorporación y programa 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));

Usa una tabla de trabajo ordenada y una cola de activación

Sin embargo, cuando necesitas que todas las tareas de una entidad en particular se ejecuten en orden de confirmación, incluso mientras las solicitudes externas, los webhooks o las acciones del usuario agregan tareas nuevas mientras las tareas anteriores aún se están procesando, este patrón admite cargas de trabajo que se ajustan a la capacidad de escritura de una sola división.

Para procesar tareas simultáneas en orden por entidad, extiende el patrón de marca de modificación almacenando tareas ordenadas en una tabla intercalada y usando la cola solo para notificaciones de activación ligeras.

Primero, intercala una tabla de trabajo ordenada (con marcas de tiempo de confirmación) y una cola de activación en una tabla de entidad principal que haga un seguimiento de la reclamación activa. Para evitar hotspots en las divisiones, elige una clave primaria (como un UUID o una secuencia de bits invertidos) que distribuya las entidades de manera 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 este esquema implementado, los remitentes y los trabajadores se coordinan con el siguiente flujo de trabajo:

  1. Inserta tareas ordenadas y un mensaje de activación: En la transacción del remitente, inserta las tareas en CustomerWorkItems (con PENDING_COMMIT_TIMESTAMP() y un BatchIndex basado en cero para ordenar varias tareas dentro de la misma transacción) y, luego, inserta un solo mensaje de activación con una carga útil vacía (b'') en CustomerDirtyQueue.
  2. Reclama, procesa y libera la entidad en tres pasos:
    • Paso 1 (Reclama la entidad en la transacción 1): Cuando un trabajador recibe un mensaje de activación de RECEIVE_CustomerDirtyQueue, ejecuta una transacción breve de lectura y escritura:
      1. Verifica Customers y confirma la recepción del mensaje de activación entrante (DELETE ... ASSERT_ROWS_MODIFIED 1). Si otro trabajador ya tiene una reclamación activa (IsProcessing = TRUE y ProcessingExpiresAt > CURRENT_TIMESTAMP()), confirma la transacción 1 y sal. El trabajador activo verifica si hay tareas restantes antes de liberar su reclamo.
      2. De lo contrario, lee el lote de tareas más antiguo (por ejemplo, LIMIT 25) de CustomerWorkItems ordenado por CreatedAt ASC, BatchIndex ASC y borra cualquier mensaje de resguardo vencido restante (cuyo MessageId sea el ActiveClaimId anterior).
      3. Si se devuelven tareas, establece IsProcessing = TRUE, ActiveClaimId y ProcessingExpiresAt (como 10 segundos en el futuro) en Customers, y, luego, inserta un mensaje de resguardo (MessageId = ActiveClaimId) en CustomerDirtyQueue programado para ProcessingExpiresAt. Si no quedan tareas, restablece IsProcessing = FALSE, ActiveClaimId = NULL y ProcessingExpiresAt = NULL.
    • Paso 2 (Procesa tareas fuera de una transacción): Después de que se confirma la transacción 1, el trabajador ejecuta las tareas de forma secuencial en el código de la aplicación. Si una tarea falla, el trabajador detiene el lote antes de tiempo y ejecuta el paso 3 para que las tareas completadas se borren antes de volver a intentar la tarea con errores.
    • Paso 3 (borra las tareas completadas y libera la entidad en la transacción 2): El trabajador abre una segunda transacción corta de lectura y escritura, borra su mensaje de resguardo (ActiveClaimId) de CustomerDirtyQueue con ASSERT_ROWS_MODIFIED 1, borra las tareas completadas de CustomerWorkItems, inserta un mensaje de activación nuevo si quedan más tareas en CustomerWorkItems y restablece IsProcessing = FALSE, ActiveClaimId = NULL y ProcessingExpiresAt = NULL en Customers.

Este patrón conserva el orden estricto por entidad y la alta capacidad de procesamiento por los siguientes motivos:

  • Orden de marca de tiempo de confirmación: Almacenar tareas en CustomerWorkItems con clave de (CustomerId, CreatedAt, BatchIndex) ordena cada tarea según su marca de tiempo de confirmación de transacción, incluso cuando varios remitentes escriben de forma simultánea.
  • Localidad de división única: La intercalación de CustomerWorkItems y CustomerDirtyQueue en Customers mantiene el estado de reclamo, las tareas y los mensajes de activación de una entidad en la misma división. Mantener CustomerDirtyQueue.Payload vacío (b'') también minimiza el almacenamiento de la cola y la sobrecarga de entrega en memoria.
  • Bloqueos de bases de datos de corta duración: Mantener abierta una transacción de lectura y escritura durante el paso 2 bloquea la fila Customers y los remitentes simultáneos. Dividir la reclamación (transacción 1) y la finalización (transacción 2) en dos transacciones cortas garantiza que solo un trabajador procese una entidad a la vez sin mantener bloqueos de la base de datos mientras se ejecuta el código de la aplicación.
  • Recuperación ante fallas y aislamiento: Confirmar de inmediato el mensaje de activación inicial en la transacción 1 y programar un mensaje de resguardo (ActiveClaimId) en ProcessingExpiresAt reemplaza la concesión fija de mensajes de 10 segundos de RECEIVE por un reclamo de entidad configurable. Si el trabajador falla durante el paso 2, el mensaje de resguardo madura y activa a otro trabajador. Si un trabajador lento finaliza después de que venció su reclamo y otro trabajador ya se hizo cargo, borrar ActiveClaimId con ASSERT_ROWS_MODIFIED 1 en la transacción 2 falla con OUT_OF_RANGE. Permitir que ese error se propague (o revertir de forma explícita) anula la transacción 2 antes de que se puedan confirmar esas escrituras.

Las siguientes declaraciones insertan dos tareas ordenadas y un mensaje de activación en una sola transacción del remitente:

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

Las siguientes sentencias de SQL muestran cómo un trabajador recibe mensajes de activación, reclama la entidad en la transacción 1 y la libera en la transacción 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';

Anula la duplicación de mensajes de activación en ráfagas con la organización por lotes temporal

Cuando una entidad recibe ráfagas frecuentes de actualizaciones en pocos segundos, el envío de un mensaje de activación independiente en cada transacción genera escrituras de cola innecesarias y entregas de activación redundantes.

Para fusionar los mensajes de activación en el momento de la escritura, combina el procesamiento por lotes temporal con un MessageId determinístico:

  • Establece MessageId en el ID de bucket del período (por ejemplo, un bucket de 5 segundos).
  • Redondea DeliverTime hacia arriba hasta el siguiente período más un desplazamiento por entidad calculado con FARM_FINGERPRINT (o spanner.farm_fingerprint).
  • Inserta el mensaje de activación con INSERT OR IGNORE en GoogleSQL o INSERT ... SELECT ... FROM ... WHERE NOT EXISTS en PostgreSQL.

Cada transacción para la misma entidad dentro de esa ventana de 5 segundos calcula los mismos MessageId y DeliverTime. Todas las transacciones insertan sus tareas en CustomerWorkItems, pero solo la primera transacción de la ventana escribe un mensaje de activación en CustomerDirtyQueue. Agregar un desplazamiento por entidad distribuye los tiempos de entrega en el intervalo de 5 segundos para que las diferentes entidades no se activen en el mismo segundo.

Por ejemplo, la siguiente transacción del remitente fusiona los mensajes de activación en buckets de 5 segundos:

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

Reduce la contención de bloqueos de los mensajes de activación simultáneos

Cuando vencen al mismo tiempo varios mensajes de activación para la misma entidad ocupada, varios trabajadores pueden iniciar la transacción 1 de forma simultánea y competir por los bloqueos de lectura y escritura en la misma fila de Customers.

Para reducir la contención de bloqueos en entidades activas, realiza una lectura única sin bloqueo (client.Single()) antes de iniciar la transacción 1 para verificar si IsProcessing = TRUE y ProcessingExpiresAt > CURRENT_TIMESTAMP(). Si la entidad está ocupada, suspende la ejecución durante un breve retraso aleatorio (como de 10 a 50 milisegundos) antes de ejecutar la transacción 1 para volver a verificar Customers y confirmar el mensaje de activación duplicado.

Una sola lectura verifica el estado de reclamo de la entidad sin adquirir bloqueos de lectura y escritura, y la demora aleatoria escalona las transacciones de lectura y escritura posteriores para que los trabajadores no compitan en la fila Customers en el mismo milisegundo. Siempre vuelve a verificar IsProcessing dentro de la transacción 1 antes de borrar el mensaje de activación para que, si el trabajador activo finaliza justo después de la lectura única, el mensaje de activación no se borre mientras las tareas nuevas permanezcan sin procesar.

Por ejemplo, la siguiente función de Go aplica una demora aleatoria cuando una entidad ya está ocupada:

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
}

Controla lotes de larga duración y llamadas externas

Cuando un lote de tareas tarda más en procesarse que la ventana inicial de 10 segundos de ProcessingExpiresAt o llama a APIs externas (como pasarelas de pago o webhooks) que no se revierten cuando se anula una transacción de base de datos, debes evitar las acciones externas duplicadas y el vencimiento prematuro de la reclamación.

Para proteger las llamadas externas y extender las reclamaciones de entidades para los lotes lentos, haz lo siguiente:

  1. Pasa una clave de idempotencia determinística a las APIs externas: Combina CustomerId, CreatedAt y BatchIndex (por ejemplo, 456:2026-05-01T12:00:00.123456Z:0) y pasa esa clave a los servicios descendentes durante el paso 2.
  2. Extiende la reclamación de la entidad con un latido periódico: Establece un ProcessingExpiresAt inicial y un DeliverTime de resguardo más largos (como 30 o 60 segundos) en la transacción 1, o ejecuta una transacción de latido en segundo plano antes de que venza la reclamación (por ejemplo, cada 3 o 4 segundos en un período de reclamación de 10 segundos). Cada transacción de latido borra el mensaje de resguardo actual (ActiveClaimId) con ASSERT_ROWS_MODIFIED 1, inserta un mensaje de resguardo nuevo con un DeliverTime futuro actualizado y actualiza ActiveClaimId y ProcessingExpiresAt en Customers. Detén el latido antes de iniciar la transacción 2.

Debido a que el paso 2 se ejecuta fuera de una transacción de base de datos y la entrega de la cola es al menos una vez, una falla del trabajador después de una llamada a la API externa hace que el siguiente trabajador vuelva a intentar la tarea. Pasar una clave de idempotencia determinística permite que el servicio externo ignore las solicitudes duplicadas. Para obtener más información, consulta Bandeja de salida transaccional. Reemplazar periódicamente el mensaje de resguardo y extender ProcessingExpiresAt mantiene activo el reclamo de la entidad mientras el trabajador está en buen estado, a la vez que permite que otro trabajador asuma el control si el trabajador falla.

Por ejemplo, la siguiente transacción de latido extiende un reclamo de entidad activo por 10 segundos:

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

Escala entidades de gran volumen con fragmentación y lecturas inactivas

Cuando una sola entidad recibe más escrituras de las que puede controlar una sola división de Spanner, escribir cada tarea en una sola división de Customers crea un hotspot de escritura, incluso si aún necesitas procesar tareas para esa entidad en orden de confirmación.

Para escalar la capacidad de procesamiento de escritura de una entidad de gran volumen y, al mismo tiempo, preservar el orden global, distribuye las escrituras en N fragmentos y combínalas de forma asíncrona con un trabajador de limpieza periódico usando lecturas inactivas:

  • Divide las tablas de trabajo y de anulación de duplicación: Crea una tabla superior CustomerShards con PRIMARY KEY (ShardId, CustomerId) (ShardId de 0 a N - 1) y, luego, intercala una tabla de trabajo dividida con clave por (ShardId, CustomerId, CreatedAt, BatchIndex). Hacer que ShardId sea la columna de clave principal distribuye las escrituras en N divisiones. Para evitar filas de tareas duplicadas cuando una transacción reintentada recibe un PENDING_COMMIT_TIMESTAMP() nuevo, también intercala una tabla de anulación de duplicación por lotes con clave de (ShardId, CustomerId, BatchId) con una política de TTL.
  • Enruta cada lote de productores a un fragmento sin escrituras en la cola: En cada transacción del productor, calcula ShardId a partir de un hash de un BatchId único (como FARM_FINGERPRINT) y, luego, insértalo en la tabla de anulación de duplicación y en la tabla de trabajo fragmentada sin insertarlo en una cola. La asignación de hash BatchId mantiene cada transacción del productor dentro de una sola división y elimina la sobrecarga de la cola por escritura.
  • Borra fragmentos en orden con una lectura inactiva y un cursor de progreso: Mantén un reclamo activo y un cursor (LastSweptAt, LastBatchIndex, LastShardId) en una tabla CustomerSweeperState separada con una cola de activación intercalada que contenga un mensaje de borrado recurrente por entidad. Cuando se activa, el trabajador reclama la entidad (con el mismo patrón de reclamo y mensaje de resguardo que Usa una tabla de trabajo ordenada y una cola de activación), consulta todos los fragmentos de N después del cursor con una lectura de antigüedad exacta de 10 segundos ordenada por CreatedAt ASC, BatchIndex ASC, ShardId ASC, procesa el lote en orden y confirma una transacción de finalización que borra las filas procesadas, avanza el cursor y programa el siguiente barrido. El uso de una lectura inactiva evita el bloqueo de las escrituras del productor en curso en las divisiones, mientras que el cursor omite las filas que se procesaron y borraron dentro de la ventana de inactividad.

¿Qué sigue?