Usar carimbos de data/hora de linha para medir a latência em seus pipelines¶

Os carimbos de data/hora de linha fornecem um registro cronológico preciso de quando cada linha em uma tabela foi atualizada pela última vez. As linhas modificadas na mesma transação compartilham o mesmo carimbo de data/hora, e as linhas modificadas em transações diferentes são ordenadas pela data de confirmação.

Os principais casos de uso incluem o seguinte:

Observabilidade do pipeline: meça a latência de ponta a ponta e a atualização dos dados para ingestão de streaming, CDC e cargas de trabalho ETL com maior precisão do que os carimbos de data/hora do lado do cliente.
Processamento incremental confiável: capture registros atrasados ou preenchidos retroativamente que os carimbos de data/hora de eventos podem ignorar, usando horários de confirmação definitivos.
Trilhas de auditoria definitivas: estabeleça uma ordem cronológica de eventos para conformidade regulatória ou marcos no estilo SCD2.

Para definir carimbos de data/hora de linha em suas tabelas, escolha uma das seguintes opções:

Definir carimbos de data/hora de linha em uma tabela: usando uma função que tenha o privilégio OWNERSHIP na tabela, defina a propriedade ROW_TIMESTAMP como TRUE ao executar o comando CREATE TABLE ou ALTER TABLE.

Por exemplo, CREATE TABLE … ROW_TIMESTAMP = TRUE ou ALTER TABLE … SET ROW_TIMESTAMP = TRUE.
Definir carimbos de data/hora de linha por padrão para novas tabelas em um contêiner: defina a propriedade ROW_TIMESTAMP_DEFAULT como TRUE no contêiner.

Por exemplo, ALTER SCHEMA … SET ROW_TIMESTAMP_DEFAULT = TRUE significa que todas as novas tabelas criadas no esquema após a configuração do parâmetro terão os carimbos de data/hora de linha ativados por padrão.
Habilitar em massa os carimbos de data/hora de linha em tabelas existentes: use a função do sistema SELECT SYSTEM$SET_ROW_TIMESTAMP_ON_ALL_SUPPORTED_TABLES.

Por exemplo, SELECT SYSTEM$SET_ROW_TIMESTAMP_ON_ALL_SUPPORTED_TABLES('schema', '{my_db}.my_schema').
- O primeiro argumento é o nível: um de schema, database ou account.
- O segundo argumento é o nome totalmente qualificado do contêiner.
Essa função adiciona a coluna de carimbo de data/hora da linha a todas as tabelas elegíveis existentes dentro do contêiner e garante que as tabelas recém-criadas tenham automaticamente os carimbos de data/hora de linha ativados.

Para executar a função com sucesso, você precisa de privilégios MODIFY no contêiner em que está invocando a função.

Após a ativação dos carimbos de data/hora de linha, as tabelas expõem a coluna METADATA$ROW_LAST_COMMIT_TIME, que retorna o carimbo de data/hora da última modificação de cada linha. Isso permite o rastreamento de alterações, o processamento incremental e as consultas do Time Travel com base no horário de modificação da linha.

Nota

Em um cenário de compartilhamento de dados, os consumidores não podem selecionar METADATA$ROW_LAST_COMMIT_TIME mesmo que a tabela do produtor tenha o carimbo de data/hora da linha ativado. Os produtores devem criar uma exibição que selecione METADATA$ROW_LAST_COMMIT_TIME e, em seguida, compartilhar a exibição se quiserem compartilhar os carimbos de data/hora de linha com os consumidores.

As instruções a seguir demonstram como criar uma tabela compatível com carimbos de data/hora de linha. As instruções inserem dados na tabela e recuperam o carimbo de data/hora de cada linha.

CREATE OR REPLACE TABLE table1(value1 STRING)
  ROW_TIMESTAMP = TRUE;

INSERT INTO table1 VALUES('some-value-a');

INSERT INTO table1 VALUES('some-value-b');

SELECT METADATA$ROW_LAST_COMMIT_TIME AS row_timestamp, *
  FROM table1
  ORDER BY 1;

Copy

Casos de uso primários¶

A coluna de metadados METADATA$ROW_LAST_COMMIT_TIME ajuda a rastrear a latência. Por exemplo, se você busca uma latência total de cinco segundos, essa coluna ajuda a determinar a contribuição do Snowflake para essa latência.

Os principais casos de uso incluem:

Medição da latência de ingestão: rastreie o tempo entre a criação de uma linha no cliente e a visibilidade dele no Snowflake, permitindo que os usuários calculem o tempo de ingestão de dados.
Medição da latência de ponta a ponta: combine a latência de ingestão e a latência do pipeline para medir o tempo total desde a geração dos dados até seu estado final.
Medição da latência do pipeline: rastreia os carimbos de data/hora à medida que os dados se movem por um pipeline. Ao comparar o carimbo de data/hora da tabela inicial com o da tabela final, os usuários podem medir quanto tempo o pipeline leva para processar os dados.
- Compatível com pipelines baseados em fluxos, tabelas dinâmicas e tarefas.

Exemplo: medir a latência de ingestão¶

Para medir a latência de ingestão usando a coluna de metadados METADATA$ROW_LAST_COMMIT_TIME, faça o seguinte:

Crie um pipeline de ingestão que envie dados para o Snowflake usando um dos seguintes métodos:
- SDK de ingestão do Snowpipe Streaming . Para um exemplo simples que mostra como o cliente SDK poderia ser usado para criar um aplicativo Snowpipe Streaming, consulte este arquivo Java (GitHub).
- Snowpipe
- Comando COPY INTO <tabela>

Execute o seguinte:

ALTER SESSION SET TIMESTAMP_TZ_OUTPUT_FORMAT = 'YYYY-MM-DDTHH:MI:SS.FF3 TZH';

ALTER SESSION SET TIMEZONE = 'UTC';

CREATE OR REPLACE DATABASE mydb;

CREATE OR ALTER SCHEMA myschema;

CREATE OR REPLACE TABLE table1(record_id STRING, client_timestamp TIMESTAMP_LTZ);

-- The rows inserted from server-side-insert-1 up to this point will not have a valid METADATA$ROW_LAST_COMMIT_TIME timestamp.
INSERT INTO table1 VALUES('server-side-insert-1', current_timestamp());

Copy

Modifique a tabela para habilitar o recurso METADATA$ROW_LAST_COMMIT_TIME.
```
ALTER TABLE table1 SET ROW_TIMESTAMP = TRUE;
```
Copy
Faça a ingestão dos dados que incluem as colunas record_id e client_timestamp em sua tabela do Snowflake usando o pipeline de ingestão definido na Etapa 1.
Insira uma nova linha como exemplo imediato, caso não esteja usando um pipeline de ingestão. Ao contrário da inserção na Etapa 2, esta terá um carimbo de data/hora METADATA$ROW_LAST_COMMIT_TIME válido porque a propriedade da tabela está habilitada.
```
INSERT INTO table1 VALUES('server-side-insert-2', current_timestamp());
```
Copy

Execute seu programa do lado do cliente novamente e, em seguida, faça o seguinte:

SELECT *, METADATA$ROW_LAST_COMMIT_TIME AS ROW_TIMESTAMP, TIMESTAMPDIFF(ms, CLIENT_TIMESTAMP, ROW_TIMESTAMP)
  AS INGEST_LATENCY FROM table1 ORDER BY 2;

Copy

Casos de uso secundários¶

Os carimbos de data/hora de linha também podem ser utilizados nos seguintes casos:

Retenção de dados: os carimbos de data/hora de linha podem ajudar a excluir registros antigos para economizar custos de armazenamento.
Ordenação de eventos e rastreamento de alterações: você pode usar os carimbos de data/hora de linha para rastrear alterações. A linha com o carimbo de data/hora mais longo representa a alteração mais recente.
Dados somente de acréscimo: se as linhas forem apenas acrescentadas, os carimbos de data/hora de linha podem ajudar a filtrar os estados da tabela a partir de pontos específicos no tempo, permitindo que você use o Time Travel independentemente da política de retenção de dados.

Limitações e considerações¶

Os carimbos de data/hora de linha só garantem a manutenção da ordem cronológica dentro da mesma tabela, exceto em caso de failover, em que a ordenação não é garantida. A ordenação entre tabelas, regiões diferentes ou outras fontes de tempo não é garantida. Você não deve comparar carimbos de data/hora de linha entre tabelas ou outras fontes, pois isso pode levar a inconsistências.
Os carimbos de data/hora de linha refletem a hora da última atualização, não a hora da criação. Por exemplo, se a linha de dados for atualizada depois de ter sido confirmada, o carimbo de data/hora da linha refletirá a hora da última atualização, não a hora da criação dos dados.
Os carimbos de data/hora de linha criadas antes da ativação dos carimbos para uma tabela são definidos como NULL.
Os carimbos de data/hora de linha são armazenados enquanto as linhas estiverem armazenadas.
Definir a propriedade ROW_TIMESTAMP como FALSE exclui permanentemente todos os valores METADATA$ROW_LAST_COMMIT_TIME armazenados. Reativá-la não os restaurará, e as consultas do Time Travel não retornarão nada.
Os carimbos de data/hora de linha não são compatíveis com tabelas Apache Iceberg™, tabelas externas, tabelas híbridas, fluxos ou exibições.
Não é possível referenciar a coluna de metadados METADATA$ROW_LAST_COMMIT_TIME nos seguintes casos:
- Cláusula CHANGES
- Políticas, incluindo políticas de acesso a linhas ou colunas e políticas de ciclo de vida de armazenamento
- Restrições
- Expressões CLUSTER BY
Não é possível restaurar os carimbos de data/hora de linha pela restauração da tabela de arquivo. Como solução alternativa, você pode materializar METADATA$ROW_LAST_COMMIT_TIME como uma coluna persistente de outra tabela para usar na restauração de arquivos.

Considerações sobre clonagem de carimbos de data/hora de linha¶

A clonagem de uma tabela preserva exatamente os carimbos de data/hora de linha. Operações que criam uma cópia física dos dados, como CREATE TABLE AS SELECT (CTAS) e INSERT INTO … SELECT, atribuem novos carimbos de data/hora de linha que refletem quando a cópia foi feita. Os carimbos de data/hora de linha originais da tabela de origem não são preservados. Se você quiser manter um registro deles, selecione-os explicitamente em uma coluna persistente, como mostrado no exemplo a seguir:

CREATE TABLE my_archive AS
 SELECT *, METADATA$ROW_LAST_COMMIT_TIME AS original_commit_time
 FROM my_source_table;

Copy