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:
- Inserta tareas ordenadas y un mensaje de activación: En la transacción del remitente,
inserta las tareas en
CustomerWorkItems(conPENDING_COMMIT_TIMESTAMP()y unBatchIndexbasado 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'') enCustomerDirtyQueue. - 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:- Verifica
Customersy 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 = TRUEyProcessingExpiresAt > CURRENT_TIMESTAMP()), confirma la transacción 1 y sal. El trabajador activo verifica si hay tareas restantes antes de liberar su reclamo. - De lo contrario, lee el lote de tareas más antiguo (por ejemplo,
LIMIT 25) deCustomerWorkItemsordenado porCreatedAt ASC, BatchIndex ASCy borra cualquier mensaje de resguardo vencido restante (cuyoMessageIdsea elActiveClaimIdanterior). - Si se devuelven tareas, establece
IsProcessing = TRUE,ActiveClaimIdyProcessingExpiresAt(como 10 segundos en el futuro) enCustomers, y, luego, inserta un mensaje de resguardo (MessageId = ActiveClaimId) enCustomerDirtyQueueprogramado paraProcessingExpiresAt. Si no quedan tareas, restableceIsProcessing = FALSE,ActiveClaimId = NULLyProcessingExpiresAt = NULL.
- Verifica
- 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) deCustomerDirtyQueueconASSERT_ROWS_MODIFIED 1, borra las tareas completadas deCustomerWorkItems, inserta un mensaje de activación nuevo si quedan más tareas enCustomerWorkItemsy restableceIsProcessing = FALSE,ActiveClaimId = NULLyProcessingExpiresAt = NULLenCustomers.
- Paso 1 (Reclama la entidad en la transacción 1): Cuando un trabajador recibe un
mensaje de activación de
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
CustomerWorkItemscon 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
CustomerWorkItemsyCustomerDirtyQueueenCustomersmantiene el estado de reclamo, las tareas y los mensajes de activación de una entidad en la misma división. MantenerCustomerDirtyQueue.Payloadvací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
Customersy 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) enProcessingExpiresAtreemplaza la concesión fija de mensajes de 10 segundos deRECEIVEpor 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, borrarActiveClaimIdconASSERT_ROWS_MODIFIED 1en la transacción 2 falla conOUT_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
MessageIden el ID de bucket del período (por ejemplo, un bucket de 5 segundos). - Redondea
DeliverTimehacia arriba hasta el siguiente período más un desplazamiento por entidad calculado conFARM_FINGERPRINT(ospanner.farm_fingerprint). - Inserta el mensaje de activación con
INSERT OR IGNOREen GoogleSQL oINSERT ... SELECT ... FROM ... WHERE NOT EXISTSen 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:
- Pasa una clave de idempotencia determinística a las APIs externas: Combina
CustomerId,CreatedAtyBatchIndex(por ejemplo,456:2026-05-01T12:00:00.123456Z:0) y pasa esa clave a los servicios descendentes durante el paso 2. - Extiende la reclamación de la entidad con un latido periódico: Establece un
ProcessingExpiresAtinicial y unDeliverTimede 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) conASSERT_ROWS_MODIFIED 1, inserta un mensaje de resguardo nuevo con unDeliverTimefuturo actualizado y actualizaActiveClaimIdyProcessingExpiresAtenCustomers. 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
CustomerShardsconPRIMARY KEY (ShardId, CustomerId)(ShardIdde0aN - 1) y, luego, intercala una tabla de trabajo dividida con clave por(ShardId, CustomerId, CreatedAt, BatchIndex). Hacer queShardIdsea la columna de clave principal distribuye las escrituras enNdivisiones. Para evitar filas de tareas duplicadas cuando una transacción reintentada recibe unPENDING_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
ShardIda partir de un hash de unBatchIdúnico (comoFARM_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 hashBatchIdmantiene 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 tablaCustomerSweeperStateseparada 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 deNdespués del cursor con una lectura de antigüedad exacta de 10 segundos ordenada porCreatedAt 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?
- Aprende a usar las colas de Spanner, incluidas las prácticas recomendadas y la supervisión.
- Explora más situaciones y ejemplos de colas de Spanner.
- Obtén más información sobre el procesamiento de tipo exactamente una vez y el acuse de recibo de tipo como máximo una vez.
- Configura el control de acceso con el control de acceso detallado para las colas.