As filas do Spanner entregam mensagens pelo menos uma vez e são projetadas para processamento paralelo em vários receptores. Quando várias mensagens para a mesma entidade (como uma conta de cliente, um pedido ou um dispositivo) são enviadas para uma fila, diferentes workers podem extraí-las e processá-las ao mesmo tempo. Mesmo que uma mensagem seja enviada primeiro, um atraso na rede ou uma nova tentativa pode atrasar o primeiro worker enquanto um segundo worker conclui uma mensagem posterior.
Se todas as mensagens em toda a fila fossem processadas em ordem global estrita, um worker lento poderia paralisar toda a fila (um fenômeno conhecido como bloqueio de início de linha). No entanto, a maioria dos aplicativos não precisa que todas as mensagens do banco de dados esperem em uma única fila global. Em vez disso, você só precisa que as tarefas da mesma entidade sejam executadas em ordem, enquanto as tarefas de entidades diferentes são executadas em paralelo. É possível usar os padrões a seguir para processar mensagens em ordem por entidade com base na carga de trabalho.
Encadear mensagens para fluxos de trabalho sequenciais
Quando um job em segundo plano para uma entidade consiste em etapas sequenciais dependentes (por
exemplo, step-1 seguido por step-2 e step-3) e as solicitações externas
não adicionam tarefas concorrentes a esse fluxo de trabalho em paralelo, você quer que cada etapa
comece somente após a conclusão da etapa anterior.
Para aplicar a ordem passo a passo, coloque apenas a primeira etapa na fila inicialmente. Quando um
worker termina de processar a etapa atual, ele confirma a mensagem atual
(DELETE ...
ASSERT_ROWS_MODIFIED
1) e insere a mensagem para a próxima etapa na mesma
transação de leitura e gravação.
Como a mensagem para a próxima etapa só é criada depois que a etapa atual é concluída e confirmada na mesma transação, duas etapas para o mesmo fluxo de trabalho nunca existem na fila ao mesmo tempo e não podem ser processadas fora de ordem por workers simultâneos.
Por exemplo, quando um worker conclui step-1 de um fluxo de trabalho de integração e
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));
Usar uma tabela de trabalho ordenada e uma fila de ativação
No entanto, quando você precisa que todas as tarefas de uma determinada entidade sejam executadas na ordem de confirmação, mesmo que solicitações externas, webhooks ou ações do usuário adicionem novas tarefas enquanto as anteriores ainda estão sendo processadas, esse padrão é compatível com cargas de trabalho que se encaixam na capacidade de gravação de uma única divisão.
Para processar tarefas simultâneas em ordem por entidade, estenda o padrão de flag suja armazenando tarefas ordenadas em uma tabela intercalada e usando a fila apenas para notificações de ativação leves.
Primeiro, intercale uma tabela de trabalho ordenada (usando carimbos de data/hora de confirmação) e uma fila de ativação em uma tabela de entidade pai que rastreia a reivindicação ativa. Para evitar pontos de acesso em divisões, escolha uma chave primária (como um UUID ou uma sequência de bits invertidos) que distribua as entidades de maneira 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;
Com esse esquema, os remetentes e os workers se coordenam usando o seguinte fluxo de trabalho:
- Inserir tarefas ordenadas e uma mensagem de ativação: na transação do remetente,
insira as tarefas em
CustomerWorkItems(usandoPENDING_COMMIT_TIMESTAMP()e umBatchIndexbaseado em zero para ordenar várias tarefas na mesma transação) e insira uma única mensagem de ativação com um payload vazio (b'') emCustomerDirtyQueue. - Reivindique, processe e libere a entidade em três etapas:
- Etapa 1 (reivindicar a entidade na Transação 1): quando um worker recebe uma
mensagem de ativação de
RECEIVE_CustomerDirtyQueue, ele executa uma transação curta de leitura e gravação:- Verifique
Customerse confirme a mensagem de ativação recebida (DELETE ... ASSERT_ROWS_MODIFIED 1). Se outro worker já tiver uma reivindicação ativa (IsProcessing = TRUEeProcessingExpiresAt > CURRENT_TIMESTAMP()), confirme a Transação 1 e saia. O worker ativo verifica se há tarefas restantes antes de liberar a declaração. - Caso contrário, leia o lote mais antigo de tarefas (por exemplo,
LIMIT 25) deCustomerWorkItemsordenado porCreatedAt ASC, BatchIndex ASCe exclua qualquer mensagem de fallback expirada restante (em queMessageIdé oActiveClaimIdanterior). - Se as tarefas forem retornadas, defina
IsProcessing = TRUE,ActiveClaimIdeProcessingExpiresAt(por exemplo, 10 segundos no futuro) emCustomerse insira uma mensagem substituta (MessageId = ActiveClaimId) emCustomerDirtyQueueprogramada paraProcessingExpiresAt. Se não houver mais tarefas, redefinaIsProcessing = FALSE,ActiveClaimId = NULLeProcessingExpiresAt = NULL.
- Verifique
- Etapa 2 (processar tarefas fora de uma transação): depois que a Transação 1 é confirmada, o worker executa as tarefas sequencialmente no código do aplicativo. Se uma tarefa falhar, o worker interromperá o lote antes do tempo e ainda executará a Etapa 3 para que as tarefas concluídas sejam excluídas antes de tentar novamente a tarefa com falha.
- Etapa 3 (excluir tarefas concluídas e liberar a entidade na
Transação 2): o worker abre uma segunda transação curta de leitura e gravação,
exclui a mensagem de fallback (
ActiveClaimId) deCustomerDirtyQueuecomASSERT_ROWS_MODIFIED 1, exclui as tarefas concluídas deCustomerWorkItems, insere uma nova mensagem de ativação se houver mais tarefas emCustomerWorkItemse redefineIsProcessing = FALSE,ActiveClaimId = NULLeProcessingExpiresAt = NULLemCustomers.
- Etapa 1 (reivindicar a entidade na Transação 1): quando um worker recebe uma
mensagem de ativação de
Esse padrão preserva a ordenação estrita por entidade e a alta capacidade de processamento pelos seguintes motivos:
- Ordenação de carimbo de data/hora de confirmação: o armazenamento de tarefas em
CustomerWorkItemscom chave por(CustomerId, CreatedAt, BatchIndex)ordena cada tarefa pelo carimbo de data/hora de confirmação da transação, mesmo quando vários remetentes gravam simultaneamente. - Localidade de divisão única:
intercalar
CustomerWorkItemseCustomerDirtyQueueemCustomersmantém o estado de declaração, as tarefas e as mensagens de ativação de uma entidade na mesma divisão. ManterCustomerDirtyQueue.Payloadvazio (b'') também minimiza o armazenamento em fila e a sobrecarga de entrega na memória. - Bloqueios de banco de dados de curta duração: manter uma transação de leitura/gravação aberta durante
a Etapa 2 bloqueia a linha
Customerse os remetentes simultâneos. Dividir a reivindicação (Transação 1) e a conclusão (Transação 2) em duas transações curtas garante que apenas um worker processe uma entidade por vez, sem manter bloqueios de banco de dados enquanto o código do aplicativo é executado. - Recuperação de falhas e isolamento: confirmar imediatamente a mensagem de ativação inicial na Transação 1 e programar uma mensagem de fallback (
ActiveClaimId) emProcessingExpiresAtsubstitui o lease de mensagemRECEIVEfixo de 10 segundos por uma declaração de entidade configurável. Se o worker falhar durante a Etapa 2, a mensagem de fallback vai amadurecer e ativar outro worker. Se um worker lento terminar depois que a declaração expirar e outro worker já tiver assumido, a exclusão deActiveClaimIdcomASSERT_ROWS_MODIFIED 1na Transação 2 vai falhar comOUT_OF_RANGE. Permitir que esse erro se propague (ou reverter explicitamente) cancela a Transação 2 antes que essas gravações possam ser confirmadas.
As instruções a seguir inserem duas tarefas ordenadas e uma mensagem de ativação em uma única transação de remetente:
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));
As instruções SQL a seguir mostram como um worker recebe mensagens de ativação, reivindica a entidade na Transação 1 e a libera na Transação 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';
Eliminar a duplicação de mensagens de ativação em lote com o agrupamento temporal
Quando uma entidade recebe picos frequentes de atualizações em poucos segundos, o envio de uma mensagem de ativação separada em cada transação cria gravações de fila desnecessárias e entregas de ativação redundantes.
Para agrupar mensagens de ativação no momento da gravação, combine o
agrupamento temporal
com um MessageId determinista:
- Defina
MessageIdcomo o ID do bucket da janela de tempo (por exemplo, um bucket de 5 segundos). - Arredonde
DeliverTimepara a próxima janela de tempo mais um deslocamento por entidade calculado comFARM_FINGERPRINT(ouspanner.farm_fingerprint). - Insira a mensagem de ativação usando
INSERT OR IGNOREno GoogleSQL ouINSERT ... SELECT ... FROM ... WHERE NOT EXISTSno PostgreSQL.
Cada transação para a mesma entidade nessa janela de 5 segundos calcula os mesmos MessageId e DeliverTime. Todas as transações inserem as tarefas em
CustomerWorkItems, mas apenas a primeira transação na janela grava uma
mensagem de ativação em CustomerDirtyQueue. Adicionar um deslocamento por entidade distribui
os tempos de entrega no intervalo de 5 segundos para que entidades diferentes não sejam
acionadas no mesmo segundo.
Por exemplo, a transação de remetente a seguir agrupa as mensagens de ativação em 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
);
Reduzir a contenção de bloqueio de mensagens de ativação simultâneas
Quando várias mensagens de ativação para a mesma entidade ocupada vencem ao mesmo tempo,
vários workers podem iniciar a Transação 1 simultaneamente e disputar
bloqueios de leitura e gravação na mesma linha Customers.
Para reduzir a disputa por bloqueio em entidades quentes, realize uma
leitura única (client.Single()) sem bloqueio
antes de iniciar a Transação 1 para verificar se IsProcessing = TRUE e
ProcessingExpiresAt > CURRENT_TIMESTAMP(). Se a entidade estiver ocupada, aguarde um
breve atraso aleatório (como 10 a 50 milissegundos) antes de executar a Transação 1
para verificar novamente Customers e confirmar a mensagem de ativação duplicada.
Uma única leitura verifica o status de declaração da entidade sem adquirir bloqueios de leitura e gravação, e o atraso aleatório escalona as transações de leitura e gravação subsequentes para que os workers não disputem a linha Customers no mesmo milissegundo. Sempre
verifique novamente IsProcessing na Transação 1 antes de excluir a mensagem de ativação.
Assim, se o worker ativo terminar logo após a leitura única, a mensagem de ativação
não será excluída enquanto novas tarefas permanecerem não processadas.
Por exemplo, a função Go a seguir aplica um atraso aleatório quando uma entidade já 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
}
Processar lotes de longa duração e chamadas externas
Quando um lote de tarefas leva mais tempo para ser processado do que a janela inicial de 10 segundos do ProcessingExpiresAt ou chama APIs externas (como gateways de pagamento ou webhooks) que não são revertidas quando uma transação de banco de dados é cancelada, é necessário evitar ações externas duplicadas e a expiração prematura da reivindicação.
Para proteger chamadas externas e estender declarações de entidade para lotes lentos:
- Transmita uma chave de idempotência determinista para APIs externas: combine
CustomerId,CreatedAteBatchIndex(por exemplo,456:2026-05-01T12:00:00.123456Z:0) e transmita essa chave para serviços downstream durante a Etapa 2. - Estenda a declaração de entidade com um sinal de funcionamento periódico: defina um
ProcessingExpiresAtinicial e umDeliverTimede fallback mais longos (como 30 ou 60 segundos) na Transação 1 ou execute uma transação de sinal de funcionamento em segundo plano antes que a declaração expire (por exemplo, a cada 3 a 4 segundos em uma janela de declaração de 10 segundos). Cada transação de heartbeat exclui a mensagem de fallback atual (ActiveClaimId) comASSERT_ROWS_MODIFIED 1, insere uma nova mensagem de fallback com umDeliverTimefuturo atualizado e atualizaActiveClaimIdeProcessingExpiresAtemCustomers. Interrompa o heartbeat antes de iniciar a Transação 2.
Como a etapa 2 é executada fora de uma transação de banco de dados e a entrega da fila é
pelo menos uma vez, uma falha do worker após uma chamada de API externa faz com que o próximo worker
tente realizar a tarefa novamente. Transmitir uma chave de idempotência determinista permite que o serviço externo ignore solicitações duplicadas. Para mais informações, consulte
Caixa de saída transacional.
Substituir periodicamente a mensagem substituta e estender ProcessingExpiresAt
mantém a declaração de entidade ativa enquanto o worker está íntegro, permitindo que
outro worker assuma o controle se o worker falhar.
Por exemplo, a transação de heartbeat a seguir estende uma reivindicação de entidade ativa 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';
Escalonar entidades de alto volume com fragmentação e leituras desatualizadas
Quando uma única entidade recebe mais gravações do que uma divisão do Spanner
pode processar, gravar cada tarefa em uma única divisão Customers cria um
ponto de acesso de gravação, mesmo que você
ainda precise processar tarefas para essa entidade na ordem de confirmação.
Para escalonar a capacidade de gravação de uma entidade de alto volume e preservar a ordenação global, distribua as gravações em N fragmentos e mescle-as de forma assíncrona com um worker de limpeza periódica usando leituras desatualizadas:
- Divida as tabelas de trabalho e de eliminação de duplicação: crie uma tabela pai
CustomerShardscomPRIMARY KEY (ShardId, CustomerId)(ShardIdde0aN - 1) e intercale uma tabela de trabalho fragmentada com chave de(ShardId, CustomerId, CreatedAt, BatchIndex). TornarShardIda coluna de chave principal distribui as gravações emNdivisões. Para evitar linhas de tarefas duplicadas quando uma transação repetida recebe um novoPENDING_COMMIT_TIMESTAMP(), também intercale uma tabela de eliminação de duplicação em lote com chave por(ShardId, CustomerId, BatchId)com uma política de TTL. - Encaminhe cada lote do produtor para um fragmento sem gravações na fila: em cada
transação do produtor, calcule
ShardIdcom base em um hash de umBatchIdexclusivo (comoFARM_FINGERPRINT) e insira na tabela de eliminação de duplicação e na tabela de trabalho fragmentada sem inserir em uma fila. A geração de hash deBatchIdmantém cada transação do produtor em uma única divisão e elimina a sobrecarga da fila por gravação. - Varra os fragmentos em ordem usando uma leitura desatualizada e um cursor de progresso: mantenha
uma declaração ativa e um cursor
(LastSweptAt, LastBatchIndex, LastShardId)em uma tabelaCustomerSweeperStateseparada com uma fila de ativação intercalada contendo uma mensagem de varredura recorrente por entidade. Quando acionado, o worker reivindica a entidade (usando o mesmo padrão de reivindicação e mensagem de fallback de Usar uma tabela de trabalho ordenada e uma fila de ativação), consulta todos os fragmentosNapós o cursor usando uma leitura de desatualização exata de 10 segundos ordenada porCreatedAt ASC, BatchIndex ASC, ShardId ASC, processa o lote em ordem e confirma uma transação de conclusão que exclui as linhas processadas, avança o cursor e programa a próxima verificação. O uso de uma leitura desatualizada evita o bloqueio de gravações de produtores em andamento em divisões, enquanto o cursor pula as linhas que foram processadas e excluídas na janela de desatualização.
A seguir
- Saiba como usar as filas do Spanner, incluindo práticas recomendadas e monitoramento.
- Confira mais cenários e exemplos de filas do Spanner.
- Aprenda mais sobre o processamento único e a confirmação no máximo uma vez.
- Configure o controle de acesso com o controle de acesso refinado para filas.