Processar mensagens em ordem por entidade

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:

  1. Inserir tarefas ordenadas e uma mensagem de ativação: na transação do remetente, insira as tarefas em CustomerWorkItems (usando PENDING_COMMIT_TIMESTAMP() e um BatchIndex baseado em zero para ordenar várias tarefas na mesma transação) e insira uma única mensagem de ativação com um payload vazio (b'') em CustomerDirtyQueue.
  2. 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:
      1. Verifique Customers e confirme a mensagem de ativação recebida (DELETE ... ASSERT_ROWS_MODIFIED 1). Se outro worker já tiver uma reivindicação ativa (IsProcessing = TRUE e ProcessingExpiresAt > CURRENT_TIMESTAMP()), confirme a Transação 1 e saia. O worker ativo verifica se há tarefas restantes antes de liberar a declaração.
      2. Caso contrário, leia o lote mais antigo de tarefas (por exemplo, LIMIT 25) de CustomerWorkItems ordenado por CreatedAt ASC, BatchIndex ASC e exclua qualquer mensagem de fallback expirada restante (em que MessageId é o ActiveClaimId anterior).
      3. Se as tarefas forem retornadas, defina IsProcessing = TRUE, ActiveClaimId e ProcessingExpiresAt (por exemplo, 10 segundos no futuro) em Customers e insira uma mensagem substituta (MessageId = ActiveClaimId) em CustomerDirtyQueue programada para ProcessingExpiresAt. Se não houver mais tarefas, redefina IsProcessing = FALSE, ActiveClaimId = NULL e ProcessingExpiresAt = NULL.
    • 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) de CustomerDirtyQueue com ASSERT_ROWS_MODIFIED 1, exclui as tarefas concluídas de CustomerWorkItems, insere uma nova mensagem de ativação se houver mais tarefas em CustomerWorkItems e redefine IsProcessing = FALSE, ActiveClaimId = NULL e ProcessingExpiresAt = NULL em Customers.

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 CustomerWorkItems com 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 CustomerWorkItems e CustomerDirtyQueue em Customers mantém o estado de declaração, as tarefas e as mensagens de ativação de uma entidade na mesma divisão. Manter CustomerDirtyQueue.Payload vazio (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 Customers e 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) em ProcessingExpiresAt substitui o lease de mensagem RECEIVE fixo 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 de ActiveClaimId com ASSERT_ROWS_MODIFIED 1 na Transação 2 vai falhar com OUT_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 MessageId como o ID do bucket da janela de tempo (por exemplo, um bucket de 5 segundos).
  • Arredonde DeliverTime para a próxima janela de tempo mais um deslocamento por entidade calculado com FARM_FINGERPRINT (ou spanner.farm_fingerprint).
  • Insira a mensagem de ativação usando INSERT OR IGNORE no GoogleSQL ou INSERT ... SELECT ... FROM ... WHERE NOT EXISTS no 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:

  1. Transmita uma chave de idempotência determinista para APIs externas: combine CustomerId, CreatedAt e BatchIndex (por exemplo, 456:2026-05-01T12:00:00.123456Z:0) e transmita essa chave para serviços downstream durante a Etapa 2.
  2. Estenda a declaração de entidade com um sinal de funcionamento periódico: defina um ProcessingExpiresAt inicial e um DeliverTime de 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) com ASSERT_ROWS_MODIFIED 1, insere uma nova mensagem de fallback com um DeliverTime futuro atualizado e atualiza ActiveClaimId e ProcessingExpiresAt em Customers. 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 CustomerShards com PRIMARY KEY (ShardId, CustomerId) (ShardId de 0 a N - 1) e intercale uma tabela de trabalho fragmentada com chave de (ShardId, CustomerId, CreatedAt, BatchIndex). Tornar ShardId a coluna de chave principal distribui as gravações em N divisões. Para evitar linhas de tarefas duplicadas quando uma transação repetida recebe um novo PENDING_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 ShardId com base em um hash de um BatchId exclusivo (como FARM_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 de BatchId manté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 tabela CustomerSweeperState separada 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 fragmentos N após o cursor usando uma leitura de desatualização exata de 10 segundos ordenada por CreatedAt 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