Ler uma tabela como estava em um snapshot anterior
Cerca de 22 minutos min de leitura, com 3 exemplos em 7 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.10. Leia o original
Este capítulo ensina você a ler uma tabela como ela estava depois de um commit anterior, em cada um dos três formatos: listar os commits dela, ler um commit pelo número que o formato usa e comparar esses números entre os formatos sem misturá-los.
Suponha que um total do painel para wiki.pageviews_hourly, que soma views por hora, mude depois que a terceira hora chega, e que o responsável faça duas perguntas. Qual era o total antes desse commit? E a tabela mudou, ou apenas a consulta? Responder exige o histórico da tabela e um modo de ler um estado antigo dela. A tabela tem cinco colunas: hour_utc, domain_code, page_title, views e response_bytes. Cada exemplo deste capítulo cria a sua própria cópia da tabela, como o capítulo 1 faz: ele cria a tabela e acrescenta as horas 00, 01 e 02 como três commits. A hora 00 tem 499 linhas, e cada uma das outras duas horas tem 500.
Todo commit é um snapshot
Capítulo 1 registra as três horas como três commits. Cada commit deixa um snapshot para trás, e é isso que você lê depois.
Um commit altera os metadados da tabela em uma única etapa atômica, de modo que um leitor vê a tabela ou como estava antes do commit ou como ficou depois, nunca um estado intermediário. No Apache Iceberg, cada commit cria um snapshot. A especificação do Iceberg define um snapshot como "o estado de uma tabela em algum momento", usado para acessar o conjunto completo de arquivos de dados da tabela, e descreve cada mudança como uma troca atômica de arquivos de metadados. Um snapshot tem um ID único, um horário de criação e um resumo. O resumo de um snapshot tem um campo obrigatório, operation, que é um de append, replace, overwrite ou delete. Um append adicionou arquivos de dados e não removeu nenhum. Um commit posterior adiciona um snapshot e deixa os anteriores intactos, o que permite ao dono do painel perguntar sobre um estado que já não é o mais recente.
Antes de qualquer varredura, leia o histórico: o exemplo lista os três commits em ordem, cada um com sua operação e as linhas que adicionou, primeiro para o Iceberg e depois para o Delta Lake.
1"""Commit three hours to an Iceberg table and a Delta Lake table, then list each commit with its operation and rows added.2The prose's point that all three Iceberg commits are appends rests on the operation lines for the snapshots."""34from deltalake import DeltaTable, write_deltalake56from lib.lakehouse import ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, snapshot_labels789def main():10 with new_warehouse() as wh:11 table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)12 delta_path = str(wh.root / "delta" / "pageviews_hourly")13 for hour in range(3): # hours 00, 01 and 02: one commit to each table per hour14 batch = read_cut_hour(hour)15 table.append(batch)16 write_deltalake(delta_path, batch, mode="append")1718 # sequence_number counts commits, so sorting by it puts the labels in commit order.19 snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)20 labels = snapshot_labels([snapshot.snapshot_id for snapshot in snapshots])21 for snapshot in snapshots:22 label = labels[snapshot.snapshot_id]23 operation = snapshot.summary.operation.value24 print(f"{label} operation: {operation}")25 # added-records counts only this commit's rows, not the table's running total.26 print(f"{label} rows added: {snapshot.summary['added-records']}")2728 # Sorted by version, so the lines follow Delta's own numbering whatever order history returns.29 history = sorted(DeltaTable(delta_path).history(), key=lambda entry: entry["version"])30 for entry in history:31 rows = entry["operationMetrics"]["num_added_rows"] # Delta's count of the rows this WRITE added32 print(f"version {entry['version']} operation: {entry['operation']}")33 print(f"version {entry['version']} rows added: {rows}")343536if __name__ == "__main__":37 main()
python snapshot-history.pysnapshot 1 operation: append
snapshot 1 rows added: 499
snapshot 2 operation: append
snapshot 2 rows added: 500
snapshot 3 operation: append
snapshot 3 rows added: 500
version 0 operation: WRITE
version 0 rows added: 499
version 1 operation: WRITE
version 1 rows added: 500
version 2 operation: WRITE
version 2 rows added: 500
Os três commits usaram append, então nenhum deles reescreveu ou removeu um arquivo. A hora 00 adicionou 499 linhas, uma a menos que as outras porque o corte de dados eliminou uma linha dela, como explica o README dos dados. As horas 01 e 02 adicionaram, cada uma, 500. A pergunta do dono começa aqui: a tabela tem três estados para escolher, e o histórico os nomeia.
pyiceberg atribui a cada snapshot um ID inteiro longo. Não imprimimos esses IDs. Em vez disso, snapshot_labels os associa, na ordem dos commits, aos rótulos "snapshot 1", "snapshot 2" e "snapshot 3", e a saída imprime apenas os rótulos.
As mesmas três horas foram gravadas em uma tabela Delta Lake por meio de write_deltalake, uma gravação por hora. O Delta Lake chama cada commit de versão, e seu histórico lista a operação e as linhas gravadas em cada uma. O Delta numera as versões a partir de 0, então a primeira gravação é a versão 0. O livro imprime os números próprios do Delta, então o exemplo ordena o histórico por versão e imprime "version 0", "version 1" e "version 2". Cada gravação Delta é uma operação WRITE que adiciona as mesmas linhas do snapshot Iceberg correspondente: 499 linhas para a versão 0, depois 500 e 500.
O histórico responde à primeira metade da pergunta do dono. Ele diz qual commit alterou a tabela e quantas linhas esse commit adicionou. Um append só adiciona linhas, então não pode alterar um total de horas que já estão na tabela. Se o total de uma hora mudou, o histórico precisa indicar um overwrite, um delete ou um replace como causa, e então você lê os snapshots de cada lado dele. O histórico não diz o que uma consulta fez, e essa parte da pergunta exige as leituras da próxima seção.
Regra prática: Antes de ler ou alterar uma tabela, liste o histórico dela no formato que você usa, e use essa lista como única fonte dos números de commit. Ordene a lista pela ordem dos commits, rotule os snapshots Iceberg com snapshot_labels antes de imprimi-los, e imprima as versões Delta com a numeração do próprio Delta. Leia a operação junto com cada commit. Um append apenas adiciona arquivos, então não pode ter removido linhas, enquanto um overwrite ou um delete pode.
O que um snapshot aponta
Um snapshot não guarda linhas. Ele aponta para os arquivos que as guardam. Nas versões de formato 2 e 3, um snapshot registra uma lista de manifestos, e é ali que os seus arquivos são encontrados. A definição na seção anterior faz do snapshot o caminho de entrada para o conjunto completo de arquivos de dados, de modo que o leitor parte do snapshot e segue até os arquivos.
Isso faz de um snapshot um conjunto de ponteiros, e a consequência importa para todas as seções seguintes. Um snapshot só pode ser lido enquanto os arquivos que ele nomeia ainda existirem. A viagem no tempo, portanto, não é um backup. Ela lê apenas os arquivos que a tabela ainda mantém, e a tabela só mantém um arquivo enquanto algum snapshot o nomear. O Capítulo 7 remove os snapshots antigos e os arquivos que somente eles nomeavam, o que encerra a viagem no tempo até esses estados.
A operação do commit mostra que tipo de compartilhamento é possível. A especificação define append como a operação em que "somente arquivos de dados foram adicionados e nenhum arquivo foi removido". Assim, o snapshot 3 volta a nomear os arquivos da hora 00, porque o terceiro commit não os reescreveu. Vários snapshots podem nomear o mesmo arquivo, e um commit custa apenas os arquivos que ele escreveu mais os ponteiros para eles.
As contagens de linhas em Snapshots no pyiceberg mostram os ponteiros em funcionamento. O snapshot 2 lê 999 linhas, que são as 499 linhas da hora 00 mais as 500 da hora 01, e nada da hora 02. O snapshot 3 lê as três horas. Cada snapshot lê as linhas que os seus commits tinham tornado visíveis até então, e nada além disso. A diferença entre as duas contagens são as linhas que o terceiro commit adicionou, 500 delas, e assim o histórico e as leituras concordam.
Regra prática: Trate um snapshot antigo como legível somente enquanto os seus arquivos existirem. Antes de remover arquivos, decida quais snapshots você mantém e expire primeiro os demais. Uma consulta sobre um snapshot antigo que falha após uma limpeza indica um arquivo ausente. A solução é encontrar esse arquivo em uma cópia da tabela, e não ler outro snapshot em seu lugar.
Ler um snapshot anterior
Ler um snapshot anterior significa indicá-lo ao escanear a tabela. Cada formato tem sua própria forma de nomear um. O Iceberg usa um ID de snapshot. O DuckLake usa um número de snapshot em AT (VERSION => n). O Delta Lake usa um número de versão. Os três números não contam as mesmas coisas.
A primeira pergunta do dono é qual era o total antes de a terceira hora chegar. A resposta é o estado após o segundo commit, snapshot 2.
Snapshots no pyiceberg
No pyiceberg 0.12.0, scan(snapshot_id=...) lê a tabela como ela estava naquele snapshot, e uma leitura sem ID de snapshot lê o snapshot atual. Duas leituras por ID respondem à primeira pergunta do dono a partir do próprio histórico da tabela, e o exemplo também lê a tabela atual e a compara com o snapshot 3.
1"""Read an Iceberg table as of snapshot 2 and snapshot 3, by ID, then compare the current table with snapshot 3.2The prose's answer to the owner's first question rests on the snapshot 2 views line, and the failed read on the last line."""34from lib.lakehouse import (5 ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, safe_error, scan_arrow, snapshot_labels, sql_rows,6)789def main():10 with new_warehouse() as wh:11 table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)12 for hour in range(3):13 table.append(read_cut_hour(hour))1415 snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)16 ids = [snapshot.snapshot_id for snapshot in snapshots]17 labels = snapshot_labels(ids)18 # ids[1] is snapshot 2 and ids[2] is snapshot 3: the list is in commit order, counted from 0.19 for snapshot_id in (ids[1], ids[2]):20 arrow = scan_arrow(table, snapshot_id=snapshot_id)21 # The scan is registered in DuckDB as t, so the SQL can count and sum its rows.22 rows, views = sql_rows(wh.con, "SELECT count(*), sum(views) FROM t", t=arrow)[0]23 print(f"{labels[snapshot_id]} rows: {rows}")24 print(f"{labels[snapshot_id]} views: {views}")2526 current = scan_arrow(table) # no snapshot_id, so this reads the current snapshot27 last = scan_arrow(table, snapshot_id=ids[2])28 print(f"current rows: {current.num_rows}")29 # equals compares every row and column, in order; scan_arrow sorts both tables by every column, so row order cannot differ.30 assert current.equals(last)3132 try:33 scan_arrow(table, snapshot_id=2) # 2 is the label's number, not an ID, so this fails on purpose34 except Exception as exc:35 print(f"read by label: {safe_error(exc, wh)}")363738if __name__ == "__main__":39 main()
python read-as-of-snapshot.pysnapshot 2 rows: 999
snapshot 2 views: 580963
snapshot 3 rows: 1499
snapshot 3 views: 899451
current rows: 1499
read by label: ValueError: Snapshot not found: 2
O snapshot 2 responde à primeira pergunta do dono. Antes do terceiro commit, a tabela tinha 580963 visualizações no total, e o snapshot 3, depois dele, tem 899451. Ler a tabela sem ID dá as mesmas linhas do snapshot 3, e a verificação compara as linhas em si, não apenas a quantidade.
A coluna de visualizações responde à segunda pergunta do dono. O snapshot 3 tem mais visualizações do que o snapshot 2, e a diferença são as visualizações que a hora 02 acrescentou. O total mudou porque o terceiro commit acrescentou linhas, e não porque a consulta do painel mudou. Duas leituras da mesma tabela mostram isso sem qualquer alteração na consulta.
Um leitor que tenha em mente o rótulo "snapshot 2" pode passar o número 2 como ID. Essa chamada falha, e a falha é o resultado seguro:
ValueError: Snapshot not found: 2
O erro informa o número que foi recebido, que não é um ID de snapshot, e nada na tabela foi alterado. Assim, o leitor sabe que deve buscar o ID. O próprio exemplo busca o ID de cada snapshot em table.snapshots() e nunca o calcula a partir de uma contagem. Os rótulos existem para o texto, e os IDs para a leitura.
Regra prática: Obtenha os IDs de snapshot em table.snapshots() e passe o ID que você buscou, nunca o número de um rótulo. Associe os IDs aos rótulos na ordem dos commits antes de imprimir qualquer coisa. Quando a pergunta for sobre o estado após um commit, localize primeiro esse commit no histórico e leia o snapshot que ele criou.
Leia um commit pelo seu número em cada formato
O Delta Lake lê uma versão anterior com DeltaTable(path, version=n). A versão é a posição do commit no histórico da tabela, contada a partir de 0, então a versão 0 é a primeira gravação. O auxiliar read_delta recebe o caminho e uma versão opcional e devolve as linhas como uma tabela Arrow ordenada. Neste livro, toda leitura Delta passa pelo QueryBuilder do deltalake, que o auxiliar chama por você. A seção de decisões explica o motivo.
O DuckLake mantém um snapshot para cada mudança no catálogo, e a mudança inclui criar um schema e criar uma tabela. O DuckLake também numera seus snapshots a partir de 0, então o primeiro insert em um catálogo novo não é o número 1. A página de time travel do DuckLake mostra a cláusula para lê-lo, SELECT * FROM tbl AT (VERSION => 3);, e diz que o snapshot a consultar pode ser especificado por timestamp ou "explicitamente usando um identificador de snapshot". O livro usa o identificador. Você lê o número em ducklake_snapshots, e não na sua própria contagem de inserts.
O exemplo das três versões faz os números divergirem enquanto as contagens de linhas concordam: ele grava as mesmas três horas em uma tabela Delta e em uma tabela DuckLake, com um commit por hora em cada formato. Ele lê cada commit de volta pelo seu número, imprime as duas contagens de linhas, conta os snapshots do DuckLake antes do primeiro insert e mostra uma falha.
1"""Commit the same three hours to Delta Lake and DuckLake, then read each commit back by its own number.2The prose's point that each hour gives the same row count in both formats rests on the paired row-count lines."""34from deltalake import DeltaTable, write_deltalake56from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, TABLE, attach_ducklake, connect_ducklake, new_warehouse,7 read_cut_hour, read_delta, safe_error, snapshot_labels, sql_rows)89LAKE_TABLE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"10CATALOG_SNAPSHOTS = f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"11# Fetches snapshot_time, which turns into Python values through pytz; the pins do not install pytz, so this fails on purpose.12TIME_COLUMN = f"SELECT snapshot_time FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"131415def main():16 with new_warehouse() as wh:17 delta_path = str(wh.root / "delta" / TABLE)18 connect_ducklake(wh.con)19 attach_ducklake(wh.con, DUCKLAKE_ALIAS, wh.root)20 wh.con.execute(f"CREATE SCHEMA {DUCKLAKE_ALIAS}.{NAMESPACE}")21 # A zero-row slice of hour 00: it gives the table its columns and types, and no rows.22 sql_rows(wh.con, f"CREATE TABLE {LAKE_TABLE} AS SELECT * FROM empty", empty=read_cut_hour(0).slice(0, 0))23 for hour in range(3): # hours 00, 01 and 02, one commit to each table per hour24 batch = read_cut_hour(hour)25 write_deltalake(delta_path, batch, mode="append")26 sql_rows(wh.con, f"INSERT INTO {LAKE_TABLE} SELECT * FROM batch", batch=batch)2728 # Keeps only the snapshots that inserted rows, so the schema and table creations are left out.29 inserts = sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS + " WHERE map_contains(changes, 'tables_inserted_into')"))30 # Snapshot IDs count up with each change, so these are the snapshots made before the first insert.31 before = sql_rows(wh.con, CATALOG_SNAPSHOTS + f" WHERE snapshot_id < {inserts[0]}")32 print(f"snapshots before the first insert: {len(before)}")3334 # Labels count every DuckLake snapshot from 1, setup snapshots included, not DuckLake's own numbers.35 lake_labels = snapshot_labels(sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS)))36 delta_versions = list(range(DeltaTable(delta_path).version() + 1)) # Delta versions run from 0 to the latest37 # zip pairs each hour's Delta version with its DuckLake insert, in order; strict fails if the counts differ.38 for hour, (delta_version, snapshot) in enumerate(zip(delta_versions, inserts, strict=True)):39 # DuckLake reads by the snapshot ID from ducklake_snapshots, never by counting the inserts.40 lake = sql_rows(wh.con, f"SELECT count(*) FROM {LAKE_TABLE} AT (VERSION => {snapshot})")[0][0]41 rows = len(read_delta(delta_path, version=delta_version)) # read_delta goes through QueryBuilder, because to_pyarrow_table() aborted at exit in some test runs at these pins.42 print(f"after hour {hour:02d}, Delta version {delta_version} rows: {rows}")43 print(f"after hour {hour:02d}, DuckLake {lake_labels[snapshot]} rows: {lake}")4445 try:46 wh.con.execute(TIME_COLUMN).fetchall()47 except Exception as exc:48 print(f"select time: {safe_error(exc, wh)}")495051if __name__ == "__main__":52 main()
python three-version-numbers.pysnapshots before the first insert: 3
after hour 00, Delta version 0 rows: 499
after hour 00, DuckLake snapshot 4 rows: 499
after hour 01, Delta version 1 rows: 999
after hour 01, DuckLake snapshot 5 rows: 999
after hour 02, Delta version 2 rows: 1499
after hour 02, DuckLake snapshot 6 rows: 1499
select time: InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:
ModuleNotFoundError: No module named 'pytz'
O primeiro insert é o "snapshot 4", e não o "snapshot 1", porque o catálogo DuckLake já contém 3 snapshots antes dele: o schema padrão que o DuckLake cria ao se conectar, o schema wiki e a tabela. Este livro rotula os snapshots do DuckLake a partir de 1, contando a configuração inicial, então o "snapshot 4" é o número 3 do próprio DuckLake mais um. Um leitor que conta os inserts a partir de 1 obtém o rótulo errado.
Após cada hora, os dois formatos têm o mesmo número de linhas, embora numerem seus commits de maneira diferente. A hora é a chave que alinha os dois, porque os formatos não compartilham uma numeração. Após a hora 02, que é a tabela completa, a versão 2 do Delta tem 1499 linhas e o snapshot 6 do DuckLake tem 1499, e as horas anteriores coincidem da mesma forma.
A tabela abaixo coloca os três números lado a lado.
| Formato | Número que identifica um commit | Quais mudanças ele conta | Como você o lê |
|---|---|---|---|
| Iceberg | ID do snapshot, um inteiro longo | Cada commit na tabela | scan(snapshot_id=...) |
| Delta Lake | Versão, contada a partir de 0 | Cada commit na tabela | DeltaTable(path, version=n) |
| DuckLake | Número do snapshot, contado a partir de 0 (o rótulo do livro é um a mais) | Toda mudança no catálogo, incluindo a criação de schema e tabela | AT (VERSION => n) |
Regra prática: Compare formatos pela hora em que cada commit carregou os dados, nunca pelo número bruto. Imprima os snapshots do Iceberg e do DuckLake com seus rótulos, imprima as versões Delta como o Delta as numera e vincule as contagens a elas. Leia o Delta somente por meio de read_delta, e leia o DuckLake somente com números obtidos de ducklake_snapshots. Se uma tabela em um formato recebe commits que o outro não recebe, os rótulos deixam de se alinhar, e o histórico de cada formato passa a ser o único registro confiável.
O que dá errado em produção
As falhas deste capítulo são as que um leitor tem mais probabilidade de encontrar primeiro. As duas primeiras aparecem nos exemplos deste capítulo. A terceira e a quarta são argumentadas a partir da documentação e das regras do livro, e a quinta e a sexta dependem do capítulo 1 e do capítulo 7. A primeira é o número que não é um ID. Uma varredura que falha é uma falha segura, porque o erro diz o que estava errado. Falhas piores vêm de ler um número que é válido em um formato e significa outra coisa em outro, ou de uma consulta que roda e devolve algo inesperado. O exemplo de leitura por snapshot mostra o primeiro tipo: o palpite do ID falha de forma explícita, e o texto do erro informa o valor que foi passado.
Buscar uma coluna de tempo falha por outro motivo, a ausência de um módulo. O exemplo das três versões inclui uma seleção de snapshot_time a partir de ducklake_snapshots, e a chamada falha:
InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:
A mensagem diz que o módulo pytz está ausente. O ambiente fixado não o instala. O cliente Python do DuckDB precisa do pytz para converter uma coluna TIMESTAMPTZ, como snapshot_time, em valores Python. O exemplo das três versões evita o problema selecionando apenas snapshot_id e filtrando por changes, de modo que nunca busca snapshot_time. Para ler o tempo mesmo assim, faça a conversão com snapshot_time::VARCHAR. Deixe a coluna de fora ou faça a conversão; preferimos não acrescentar um pacote que o livro não fixa.
A leitura por timestamp é a terceira armadilha. O DuckLake aceita um timestamp em AT (TIMESTAMP => ...), e os snapshots do Iceberg têm um horário de criação. Um timestamp escolhe um estado pelo relógio, e o relógio é o momento em que cada commit foi executado. Em produção, esse é um bom modo de pedir "a tabela como estava às nove da manhã". Um exemplo precisaria obter um horário da execução, que muda a cada execução, por isso o livro usa IDs e números de versão. Escolha a forma por timestamp quando precisar de um ponto no tempo de relógio e tiver um registro de quando cada commit foi executado. Escolha a forma numérica quando precisar da mesma resposta sempre.
Os números divergem entre formatos. Dois formatos podem conter a mesma tabela, e o mesmo rótulo pode então nomear estados diferentes. O exemplo do livro faz os mesmos commits de horas na mesma ordem, de modo que os rótulos coincidem. Uma tabela de produção que recebe um reparo em um formato e não no outro não terá essa coincidência. Mesmo com históricos idênticos, os números brutos não se alinham entre formatos, porque os números de snapshot do DuckLake também contam a criação de schemas e tabelas. Um painel que lê "versão 4" nos dois formatos mostrará totais diferentes, por isso compare os commits pelos seus rótulos. A verificação consiste em comparar as contagens de linhas do rótulo nos dois formatos antes de confiar em qualquer um dos números. O exemplo das três versões faz isso.
Uma contagem de arquivos também pode sair baixa, porque o DuckLake pode manter uma inserção pequena no catálogo, em vez de gravar um arquivo Parquet, com os nomes padrão do capítulo 1. O primeiro lote horário do exemplo tem sozinho 499 linhas, bem acima desse limite; por isso, com esse padrão, cada uma de suas inserções é gravada como um arquivo. Uma contagem de arquivos de dados só tem significado depois que você conhece o limite de linhas.
A falha sobre a qual este capítulo mais alerta acontece depois, em uma leitura após uma limpeza. O que um snapshot aponta explica o motivo: o erro só aparece quando um leitor pede um snapshot cujos arquivos já não existem. Nada falha na própria limpeza. O capítulo 7 mostra quais arquivos uma limpeza remove.
Regra prática: Leia o texto do erro antes de alterar a consulta. Ele informa o valor, o módulo ou a versão que falhou, e esse é o caminho mais rápido para a correção. Compare cada contagem em um formato com o mesmo rótulo no outro formato antes de confiar em qualquer uma delas. Mantenha legível o snapshot de que sua pergunta precisa até que ela seja respondida, e expire apenas os snapshots que nenhuma pergunta ainda necessite. Registre o rótulo e o nome do formato junto com cada número que você relatar, para que quem ler o relatório possa reproduzi-lo.
Decisões tomadas neste capítulo
- Rótulos, não IDs. As linhas impressas trazem rótulos como "snapshot 2" para Iceberg e DuckLake, contados a partir de 1 sobre todos os snapshots que o formato registra. No caso do DuckLake, isso inclui os três snapshots de configuração, de modo que o número próprio do DuckLake é um a menos. Os IDs do Iceberg e os números de snapshot do DuckLake nunca chegam à saída. O Delta imprime seus números de versão, que começam em 0 e são os números que o leitor passa para
DeltaTable. O leitor pode executar um exemplo novamente e comparar o texto linha por linha, e um diff mostra uma mudança nos dados ou na biblioteca, nunca uma mudança em um ID aleatório. Os rótulos são mapeados na ordem dos commits, de modo que mantêm seu significado quando uma biblioteca devolve o histórico em outra ordem. - IDs e números de versão, não timestamps. Uma leitura por timestamp depende do relógio e do momento em que cada commit foi executado. Lemos por ID ou número, para que o leitor obtenha as mesmas linhas do mesmo commit sempre que o exemplo for executado. Um leitor de produção que precise do horário real deve usar a forma com timestamp e manter um registro de quando cada commit foi executado.
- O Delta é lido somente por
read_delta. O auxiliar lê por meio doQueryBuilderdo deltalake. Com essas versões fixadas, o caminho deto_pyarrow_table()aborta na saída em algumas execuções, como o capítulo 8 mede. Corrigimos o caminho de leitura em vez de contornar o aborto, por isso nenhum exemplo chamaos._exitnem oculta o status de saída. - O DuckLake somente pelos auxiliares. Toda execução do DuckLake carrega o DuckLake com
connect_ducklakee o anexa comattach_ducklake. Nunca definimosallow_unsigned_extensions. As execuções do livro carregam a extensão oficial e assinada do DuckLake, do DuckDB, a partir do arquivo incluído no repositório, depois que o auxiliar verifica os dois hashes emSOURCE.toml, de modo que uma execução offline não precisa de download. Somente na máquina do próprio leitor, quando esse arquivo incluído está ausente, é queconnect_ducklakeexecutaINSTALL ducklake. - Consultas restritas ao catálogo. Consultas sobre
ducklake_snapshotsnomeiam suas colunas e deixam de forasnapshot_time, porque essa coluna precisa de um módulo que as versões fixadas não instalam. Preferimos nomear as colunas de que precisamos a acrescentar uma dependência que as versões fixadas não registram. - O Delta mantém os próprios números. O Delta imprime sua versão real, contada a partir de 0. Cada rótulo indica apenas em qual commit ele está na sua própria tabela, e nunca que dois formatos guardam o mesmo estado. Comparar a contagem de linhas de cada rótulo é o que faz essa verificação.
- Falhas impressas, não propagadas. Dois exemplos terminam com uma chamada que falha de propósito, e cada um captura o erro e o imprime. A falha é mostrada porque o leitor vai encontrá-la, e o texto do erro é impresso por completo para que o leitor possa compará-lo com a própria saída.
- Leia o histórico antes do estado. O código lista os commits de cada formato e só então lê um commit pelo seu número. O leitor do capítulo obtém a operação e a contagem de linhas de cada commit antes de qualquer varredura, de modo que uma contagem que pareça errada pode ser conferida com o commit que a produziu.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 20 de nov de 20263 de 3 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.