Construa uma primeira tabela, de ponta a ponta

Cerca de 23 minutos min de leitura, com 3 exemplos em 10 seções.

Edição 2026.11.10 Exemplos aprovados em 20 de nov de 2026 39 de 39 exemplos passam O que mudou

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

Ao final deste capítulo, você será capaz de gravar lotes de linhas em uma tabela, ler a tabela de volta no DuckDB e conferir os totais. Este livro é para engenheiros de dados e de analytics que escrevem SQL e Python e precisam decidir como as tabelas do seu lakehouse são armazenadas, alteradas, limpas, compartilhadas e movidas entre formatos. Ele constrói um único resultado: uma tabela de pageviews que você armazena, altera, lê como estava em um snapshot anterior, limpa, registra em um catálogo e move entre formatos.

Seis horas de visualizações da Wikimedia, guardadas em uma pasta, ainda não são uma tabela. A pasta não informa quais de seus arquivos pertencem à tabela, e uma carga que para no meio deixa um arquivo que parece igual a todos os outros. A tabela que este livro constrói é horária: cada linha informa quantas vezes um artigo público da Wikipédia foi visualizado em uma hora, em uma edição de idioma. Chamamos essa tabela de tabela de pageviews.

Este capítulo constrói uma versão simples dessa tabela. Ele grava a tabela em três formatos (Apache Iceberg, Delta Lake e DuckLake) e lê cada um de volta no DuckDB, para que você possa comparar os totais. Cada capítulo seguinte torna sólida uma etapa:

  • O capítulo 2 lê a tabela como ela estava em um snapshot anterior.
  • O capítulo 3 adiciona e renomeia colunas sem reescrever arquivos.
  • O capítulo 4 altera o particionamento sem reescrever arquivos antigos.
  • O capítulo 5 corrige linhas com deletes, updates e merges.
  • O capítulo 6 compacta os arquivos pequenos que as inserções horárias deixam.
  • O capítulo 7 expira snapshots e remove arquivos que nenhum snapshot alcança.
  • O capítulo 8 registra tabelas em um catálogo e as consulta a partir do DuckDB.
  • O capítulo 9 move uma tabela entre formatos e confere a cópia.
  • O capítulo 10 escolhe um formato a partir do que as suas ferramentas suportam.

Você conhece SQL, Python e Parquet, e sabe o que é uma partição. Este capítulo não explica esses conceitos.

As linhas da tabela de pageviews cobrem seis horas de 3 de junho de 2024, das 00:00 às 05:59 UTC. Elas vêm dos dumps de visualizações de páginas da Wikimedia, que o projeto Wikimedia disponibiliza sob CC0. O livro mantém os 500 títulos mais visualizados em cada hora, nas edições em inglês, alemão, francês e japonês, depois que as páginas especiais são removidas. O dia é fixo e está no passado, portanto os dumps dele não mudarão, e os dados do repositório não ficarão desatualizados. O README da pasta de dados informa a fonte, a licença e o recorte exato.

Os dados são propositalmente confusos. Os títulos têm sublinhados e escritas não latinas, e as contagens são assimétricas: o título mais visualizado na hora 00 tem muito mais visualizações do que o título na posição 500. Toda linha do recorte tem response_bytes igual a 0, como o README da pasta de dados registra. O livro mantém a coluna como o recorte a entrega, então ela é 0 em todas as linhas. Esses valores permanecem nos dados, porque um formato de tabela precisa armazená-los como são.

O que um formato de tabela acrescenta aos arquivos

Última alteração na edição 2026.11.10

Qualquer coisa que leia a pasta enxerga todos os arquivos dela. Um formato de tabela responde a isso com metadados. Os metadados de uma tabela são um registro do esquema da tabela e dos arquivos de dados que a compõem em cada ponto de seu histórico. Uma alteração na tabela é um commit, que grava novos metadados em uma única etapa. Essa etapa é a única mudança que move a tabela de um estado para o seguinte.

Cada formato de tabela tem seus próprios metadados e seus próprios termos para essas ideias. O Iceberg chama o estado após um commit de snapshot. O Delta Lake numera suas versões. O DuckLake registra seus snapshots em um arquivo de catálogo. Este capítulo escreve os três, para que você veja as mesmas linhas em cada um.

O lugar onde os metadados ficam também difere. Uma tabela Iceberg mantém um arquivo de metadados que indica seu snapshot atual. Na versão 2 do formato, que o pyiceberg grava, cada snapshot aponta para uma lista de manifestos, a lista de manifestos nomeia os manifestos, e cada manifesto nomeia os arquivos de dados junto com suas estatísticas. A especificação do Iceberg define cada uma dessas camadas. Uma tabela Delta Lake mantém um log ordenado de arquivos de commit em uma pasta _delta_log ao lado de seus dados, como descreve o protocolo do Delta Lake. Uma tabela DuckLake mantém seus metadados no arquivo de catálogo que você anexa, e grava seus arquivos de dados em uma pasta ao lado desse arquivo.

Seis horas são inseridas uma de cada vez, nos três formatos, e depois cada tabela é lida novamente e seus totais são comparados.

rough-lakehouse.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Load six hours into Iceberg, Delta Lake and DuckLake, then read each table back.The rows and views lines print each format's totals, and the assert after them checks that the three agree.The titles at the end come from the Iceberg table alone."""from lib.lakehouse import (    format_report,    load_three_formats,    new_warehouse,    print_rows,    safe_error,    sql_rows,    scan_arrow,)# page_title breaks ties in views, so titles with equal views always print in the same order.TOP_THREE = """    SELECT sum(views) AS views, page_title FROM pageviews    GROUP BY page_title ORDER BY views DESC, page_title LIMIT 3"""def main():    try:        with new_warehouse() as wh:            # range(6) is hours 0 to 5, the six hours of the cut, one commit per hour in each format.            iceberg, delta_path, lake = load_three_formats(wh, range(6))            report = format_report(wh, iceberg, delta_path, lake)            for name, (rows, views, files) in report.items():                print(f"{name} rows: {rows}")                print(f"{name} views: {views}")                print(f"{name} data files: {files}")            # A set of (rows, views) pairs has one entry only when all three formats agree.            totals = {(rows, views) for rows, views, _ in report.values()}            assert len(totals) == 1, "the three formats disagree on rows or views"            print("top three page titles over six hours (views, page_title):")            # pageviews names the Arrow table for the SQL; keep_order prints the rows in the SQL's order, not re-sorted.            print_rows(sql_rows(wh.con, TOP_THREE, keep_order=True, pageviews=scan_arrow(iceberg)), keep_order=True)    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython rough-lakehouse.py
iceberg rows: 2999
iceberg views: 1807299
iceberg data files: 6
delta rows: 2999
delta views: 1807299
delta data files: 6
ducklake rows: 2999
ducklake views: 1807299
ducklake data files: 6
top three page titles over six hours (views, page_title):
399885	Main_Page
102089	メインページ
54796	Wikipedia:Hauptseite

Os três formatos informam a mesma contagem de linhas e o mesmo total de visualizações, e cada um gravou um arquivo de dados por hora:

  • Iceberg: 2999 linhas, 1807299 visualizações, 6 arquivos de dados.
  • Delta Lake: 2999 linhas, 1807299 visualizações, 6 arquivos de dados.
  • DuckLake: 2999 linhas, 1807299 visualizações, 6 arquivos de dados.

Uma asserção interrompe a execução se os totais de linhas ou de visualizações dos três formatos forem diferentes. A saída então lista os três títulos mais visualizados nas seis horas, lidos somente da tabela Iceberg: Main_Page, メインページ e Wikipedia:Hauptseite, as páginas principais das edições em inglês, japonês e alemão.

A saída não traz IDs de snapshot, números de versão nem nomes de arquivo, porque esses mudam de uma execução para outra; em vez disso, acrescentar cada hora mostra como os snapshots são identificados.

O DuckLake exige um passo extra na sua própria máquina. Execute INSTALL ducklake e depois LOAD ducklake no DuckDB. As execuções do livro, em vez disso, carregam uma cópia da extensão oficial e assinada ducklake do DuckDB a partir de um arquivo no repositório, de modo que rodam sem conexão de rede. O DuckLake também tem um padrão de inlining que importa para as contagens de arquivos: por padrão, ele mantém inserções de até 10 linhas no catálogo, em vez de em um arquivo Parquet. A página de inlining de dados do DuckLake informa o padrão: "Data inlining is enabled by default with a row limit of 10." O exemplo define o limite como 0, de modo que cada inserção grava um arquivo, e as contagens de arquivos têm o mesmo significado em todos os capítulos.

Um laço de carga, três estilos de commit

Última alteração na edição 2026.11.7

O auxiliar load_three_formats(), em examples/lib/lakehouse.py, contém o laço que rough-lakehouse chama. O laço grava cada hora nas três tabelas, e cada linha que grava é um commit em um formato:

for hour in hours:
    rows = read_cut_hour(hour)
    iceberg.append(rows)
    write_deltalake(delta_path, rows, mode="append")
    lake.register("hour", rows)
    lake.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM hour")
    lake.unregister("hour")

read_cut_hour devolve uma hora do recorte como uma tabela Arrow, com as mesmas cinco colunas em todos os formatos. A adição no Iceberg cria um snapshot. A adição no Delta cria uma nova versão, e cria a tabela na primeira chamada, quando o caminho ainda não contém uma. A inserção no DuckLake grava um arquivo Parquet e registra um snapshot no arquivo de catálogo. As três chamadas diferem, mas a tabela que cada uma grava contém as mesmas seis horas de linhas. O próprio laço não verifica nada. Ele executa as seis cargas em ordem e para se alguma delas levantar um erro. As verificações vêm depois que as seis horas estão carregadas, quando rough-lakehouse relê os totais de cada formato e os compara.

Um commit nomeia os arquivos da tabela

Última alteração na edição 2026.11.10

A especificação de tabelas Apache Iceberg define um snapshot como o estado de uma tabela em algum momento, que um leitor usa para encontrar cada arquivo de dados da tabela. Um snapshot faz, portanto, duas coisas. Ele nomeia os arquivos de dados que a tabela contém naquele ponto e registra a operação que o produziu. A especificação lista os tipos de operação. Para um append, a operação é append, que a especificação do Iceberg descreve como "Somente arquivos de dados foram adicionados e nenhum arquivo foi removido."

A tabela pageviews torna isso concreto. Cada hora que você carrega se torna um arquivo de dados, e cada carga é um commit. Depois do primeiro commit, a tabela contém apenas o arquivo da hora 00. Depois do segundo commit, contém dois arquivos, e assim por diante. Um arquivo de dados nunca é editado. Um commit adiciona arquivos, e o novo snapshot nomeia os arquivos que a tabela contém após o commit.

A contagem de arquivos de dados da tabela vem do seu snapshot, e não da sua pasta. O rough-lakehouse exibe o número de arquivos de dados que cada formato informa para a tabela. Esse número é o que a tabela diz conter, e uma listagem da pasta pode mostrar um número diferente.

Regra prática: Pergunte à tabela o que ela contém, por meio do seu snapshot atual, e não listando a pasta. A pasta contém todos os arquivos que um escritor colocou ali, e o snapshot indica quais desses arquivos a tabela lê.

Por que cada formato é ensinado por meio de uma biblioteca Python

Última alteração na edição 2026.11.10

O exemplo rough-lakehouse gravou cada formato por meio de uma biblioteca diferente, e esta seção explica o motivo. O livro escreve Apache Iceberg e Delta Lake com as bibliotecas Python que você usará para executá-los: pyiceberg, na versão 0.12.0, e deltalake, na versão 1.6.6. O DuckDB, na versão 2.0.0, lê o que essas bibliotecas gravam. Ele lê uma tabela Iceberg como uma tabela Arrow a partir de um scan, e lê uma tabela Delta como uma tabela Arrow a partir de uma consulta que o deltalake executa. O DuckLake é a exceção. O próprio DuckDB executa o DuckLake, por meio de sua extensão ducklake, e anexa o arquivo de catálogo da tabela. O livro não usa as extensões iceberg ou delta do DuckDB, e nenhum exemplo as executa.

Formato Gravado por Lido pelo DuckDB através de
Apache Iceberg pyiceberg, 0.12.0 Tabela Arrow a partir de um scan
Delta Lake deltalake, 1.6.6 Tabela Arrow a partir de QueryBuilder do deltalake
DuckLake Extensão ducklake do DuckDB, na versão 2.0.0 do DuckDB ATTACH para um arquivo de catálogo

A escolha tem um custo. Um leitor que executa Iceberg com Spark ou Trino encontra mais do formato ali, com recursos que este livro não cobre. O livro menciona esses lugares e não ensina esses mecanismos. O ganho são menos partes móveis: a biblioteca própria de cada formato o grava, e o DuckDB lê a saída. A versão de cada biblioteca é fixada, e os capítulos indicam a versão fixada da biblioteca, não a versão da especificação do formato. As versões fixadas estão em examples/requirements.txt, que lista cada pacote com uma versão exata por linha. Um leitor que instala a partir desse arquivo obtém as bibliotecas contra as quais este capítulo foi executado. Use a versão do Python que examples/.python-version indica, porque o pip não a seleciona.

Regra prática: Grave e leia cada tabela com a biblioteca cuja versão você fixa, e indique qual versão suas leituras usam. Recorra à extensão própria de um mecanismo somente quando tiver medido o que a biblioteca não consegue fazer por você.

Carregar três horas em uma tabela

Última alteração na edição 2026.11.7

O exemplo do rough-lakehouse mostrou o ciclo completo, então esta seção o desacelera, usando uma única tabela. Carregar um lote envolve dois passos: criar a tabela e, depois, confirmar cada lote nela. A tabela pageviews é carregada primeiro com as horas 00, 01 e 02, de modo que cada hora corresponde a um commit. Aquele exemplo carrega as horas 03 a 05 da mesma forma, depois das três primeiras. O restante desta seção trabalha somente com a tabela Iceberg, porque ela é a que mais tem a mostrar.

Criar a tabela em um catálogo

Última alteração na edição 2026.11.10

Uma tabela Iceberg precisa de um catálogo, que é o registro que associa o nome de uma tabela aos metadados atuais dela. Uma tabela Delta Lake é encontrada pelo seu caminho, sem catálogo, e uma tabela DuckLake fica no seu arquivo de catálogo. O livro usa o catálogo SQL do pyiceberg sobre SQLite para a tabela Iceberg. O catálogo é um único arquivo, e os arquivos de dados da tabela ficam em uma pasta de armazém ao lado dele. O catálogo guarda ponteiros e metadados, não linhas. Dentro do arquivo de catálogo, um nome de tabela como wiki.pageviews_hourly aponta para a localização do arquivo de metadados atual da tabela. Um commit grava um novo arquivo de metadados e desloca esse ponteiro, de modo que quem pede a tabela ao catálogo recebe os metadados gravados pelo commit mais recente. O auxiliar new_warehouse() em examples/lib/lakehouse.py cria um catálogo e um armazém temporários para cada execução, e os remove ao final dela. Como o SQLite é um arquivo e não precisa de servidor, o catálogo inteiro roda em um notebook com a rede desligada.

A tabela tem cinco colunas, e o seu esquema descreve o que cada uma armazena:

Schema(
    NestedField(1, "hour_utc", TimestampType(), required=False),
    NestedField(2, "domain_code", StringType(), required=False),
    NestedField(3, "page_title", StringType(), required=False),
    NestedField(4, "views", LongType(), required=False),
    NestedField(5, "response_bytes", LongType(), required=False),
)

A coluna hour_utc armazena um timestamp sem fuso horário, em UTC, e as duas contagens são inteiros de 64 bits. O auxiliar create_iceberg_table() cria a tabela no catálogo, sem particionamento. O capítulo 4 acrescenta a ela uma especificação de partição.

Regra prática: escreva o esquema em código, com o tipo que cada coluna realmente tem, antes do primeiro commit. Assim os tipos são decididos de propósito, e não pelo primeiro lote que chegar.

Acrescente cada hora como um commit

Última alteração na edição 2026.11.10

Um acréscimo é um commit. Abaixo, o pyiceberg cria a tabela, acrescenta as horas 00, 01 e 02 em ordem e depois lista os snapshots na ordem dos commits, com a operação de cada um e as linhas que cada commit adicionou:

append-hours.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Create the Iceberg table, append hours 00 to 02 as three commits, then repeat hour 00.The hour 00 point rests on the `snapshot 1 rows added` and `snapshot 2 rows added` lines, and the repeated-load point on the two `repeat of hour 00` lines."""from lib.lakehouse import (    create_iceberg_table,    iceberg_file_count,    new_warehouse,    read_cut_hour,    safe_error,    scan_arrow,    snapshot_labels,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # pyiceberg returns the snapshots in commit order, which the labels below depend on.            snapshots = table.snapshots()            # Snapshot IDs change from run to run, so each one prints as its position in commit order.            labels = snapshot_labels([snap.snapshot_id for snap in snapshots])            for snap in snapshots:                label = labels[snap.snapshot_id]                print(f"{label} operation: {snap.summary.operation.value}")                # The commit's own summary holds the rows it added, not a count of the whole table.                print(f"{label} rows added: {snap.summary['added-records']}")            print(f"rows in table: {scan_arrow(table).num_rows}")            # Counted from the current snapshot, not from the folder.            print(f"data files: {iceberg_file_count(table)}")            # Hour 00 again.            table.append(read_cut_hour(0))            repeat = table.current_snapshot()            print(f"repeat of hour 00 operation: {repeat.summary.operation.value}")            print(f"repeat of hour 00 rows added: {repeat.summary['added-records']}")            print(f"rows in table after the repeat: {scan_arrow(table).num_rows}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython append-hours.py
snapshot 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
rows in table: 1499
data files: 3
repeat of hour 00 operation: append
repeat of hour 00 rows added: 499
rows in table after the repeat: 1998

A hora 00 tem uma linha a menos: o primeiro commit adiciona 499 linhas, e os dois seguintes adicionam 500 cada. A verificação de privacidade removeu uma linha da hora 00, como explica o README dos dados. Os três commits deixam 1499 linhas em 3 arquivos de dados, um arquivo para cada commit.

Cada commit também grava um resumo, e o pyiceberg devolve os snapshots na ordem dos commits, que é de onde vêm a operação e as linhas adicionadas. A operação de cada commit é append, a operação de acréscimo definida pela especificação. O resumo do snapshot é o que a tabela registra sobre os próprios commits, portanto é o primeiro lugar para olhar quando uma contagem estiver errada.

Os rótulos impressos, snapshot 1, snapshot 2 e snapshot 3, substituem os IDs dos snapshots. Um ID de snapshot do Iceberg é um inteiro longo que a especificação exige que seja único, e o pyiceberg o escolhe no momento em que o commit é feito, por isso ele muda de uma execução para outra. Associar cada ID à sua posição na ordem dos commits mantém a saída impressa igual em todas as execuções.

Regra prática: Faça um commit para cada lote que você consiga nomear, e compare as linhas que cada commit adicionou com a contagem esperada a partir da sua origem antes de fazer o próximo commit. Um erro de contagem é mais simples de rastrear enquanto o seu commit for o mais recente, e mais difícil depois que mais commits estiverem sobre ele.

Consulte a tabela com o DuckDB

Última alteração na edição 2026.11.10

Com a tabela pronta, você quer fazer perguntas a ela. O DuckDB executa SQL, mas uma tabela Iceberg não é uma tabela do DuckDB. O livro lê o snapshot atual da tabela como uma tabela Arrow, que o pyiceberg devolve a partir de uma varredura, e registra essa tabela Arrow no DuckDB com o nome pageviews. Então o DuckDB executa SQL comum sobre ela, sem nenhuma extensão Iceberg. Uma varredura é a leitura que a própria tabela faz de um snapshot. Ela lista os arquivos de dados que o snapshot nomeia, lê esses arquivos e entrega apenas as linhas que eles contêm. O DuckDB enxerga exatamente essas linhas e nada que o snapshot não nomeie.

O exemplo a seguir acrescenta as horas 00 a 02 a uma tabela nova e faz a ela duas perguntas: quais são os cinco títulos com mais visualizações na hora 00 e quantas visualizações as três horas somam no total. Ele confere esse total com a soma que a própria varredura fornece.

scan-into-duckdb.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Read the current Iceberg snapshot into DuckDB and check the totals.The point that DuckDB received every row rests on the two total views lines, which the assert compares."""from lib.lakehouse import (    create_iceberg_table,    new_warehouse,    print_rows,    read_cut_hour,    safe_error,    scan_arrow,    sql_rows,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # The current snapshot's rows as one Arrow table, sorted by every column.            arrow = scan_arrow(table)            top = sql_rows(                wh.con,                # hour_utc is UTC, so this is hour 00 of 3 June 2024; page_title breaks ties in views.                """                SELECT views, page_title FROM pageviews                WHERE hour_utc = TIMESTAMP '2024-06-03 00:00:00'                ORDER BY views DESC, page_title LIMIT 5                """,                # keep_order returns the rows in the order the SQL sorted them, not sorted again.                keep_order=True,                pageviews=arrow,            )            print("top five pages for hour 00 (views, page_title):")            print_rows(top, keep_order=True)            # One row with one column: the sum.            duckdb_total = sql_rows(wh.con, "SELECT sum(views) FROM pageviews", pageviews=arrow)[0][0]            # A second route to the same total, summed in Python from the scan's own rows.            pyiceberg_total = sum(arrow["views"].to_pylist())            print(f"total views in DuckDB: {duckdb_total}")            print(f"total views in the scan: {pyiceberg_total}")            assert duckdb_total == pyiceberg_total, "DuckDB and the scan disagree on the total"    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython scan-into-duckdb.py
top five pages for hour 00 (views, page_title):
61107	Main_Page
13791	メインページ
9492	Wikipedia:Hauptseite
7511	Wikipédia:Accueil_principal
3781	笹生優花
total views in DuckDB: 899451
total views in the scan: 899451

A lista traz os cinco títulos com mais visualizações na hora 00, do maior para o menor, usando o título como critério de desempate, e cada linha mostra as visualizações, uma tabulação e então o título. O total no DuckDB é de 899451 visualizações, igual à soma de 899451 dada pela própria varredura, e uma asserção interrompe a execução caso os dois valores sejam diferentes.

Um total igual à soma da varredura mostra que o DuckDB recebeu todas as linhas devolvidas pela varredura. Isso não verifica as linhas em si, e não verifica a consulta dos cinco primeiros. Uma verificação de total custa uma linha, por isso vale a pena executá-la após cada alteração em uma consulta. Verificar as linhas contra a origem é tarefa dos capítulos seguintes, que comparam cada mudança com os dados de onde vieram.

Regra prática: Leia uma tabela Iceberg para o DuckDB como a tabela Arrow de uma varredura e compare um total com a soma da própria varredura, para confirmar que o DuckDB recebeu todas as linhas. Depois, verifique o resultado de cada consulta contra uma origem com que você possa compará-lo.

O que dá errado em produção

Última alteração na edição 2026.11.10

O caminho do primeiro capítulo é curto, e esconde quatro problemas que você vai encontrar em produção.

Uma carga repetida adiciona as mesmas linhas de novo. Um append adiciona os arquivos de dados que recebe e não remove nenhum, como diz a definição da operação na especificação. Nada na tabela impede uma segunda cópia da hora 00 de entrar. Um commit que traz uma segunda cópia da hora 00 parece com qualquer outro commit. append-hours mostra isso: a operação do commit repetido é append, ele adiciona 499 linhas, a mesma contagem da primeira cópia, e a tabela passa a ter 1998 linhas, sem nenhum erro. O único registro de que a carga deveria rodar uma vez só é a contagem que você anotou antes de executá-la. O capítulo 5 mostra como corrigir linhas que foram carregadas de forma errada.

A pasta tem mais do que a tabela. Uma contagem dos arquivos na pasta do warehouse responde a uma pergunta diferente da contagem dos arquivos da tabela. A pasta guarda cada arquivo que um escritor colocou ali, e um snapshot define o que a tabela contém. Uma ferramenta que conta arquivos Parquet na pasta informa um número que a tabela nunca prometeu. Os capítulos 6 e 7 tratam de arquivos que a tabela não alcança mais.

IDs de snapshot, versões e números de snapshot são tipos diferentes de número. Os IDs do Iceberg são valores de 64 bits. As versões do Delta Lake contam a partir de 0, na ordem dos commits. O DuckLake também numera seus snapshots, e registra um snapshot toda vez que cria um schema ou uma tabela, além de cada inserção de linhas. Um script que guarda o número de um formato e o lê como versão de outro formato lê um estado errado.

Um insert pequeno no DuckLake não escreve arquivo. Por padrão, o DuckLake mantém no catálogo inserts de 10 linhas ou menos, então uma contagem de arquivos igual a zero após um insert pequeno é o resultado esperado, não uma falha. Os exemplos de DuckLake deste livro definem o limite de linhas como 0, exceto ducklake-inlined-delete no capítulo 10, que mantém o padrão para mostrar que um delete pequeno não escreve um arquivo de delete. Se você copiar um insert para o seu próprio catálogo, conheça antes esse padrão.

Regra prática: Anote a contagem de linhas que cada commit deve adicionar, ao lado da carga que o gera, e compare essa contagem com o resumo do commit após cada carga. A tabela não verifica cargas repetidas. Uma contagem anotada com antecedência é a verificação que faz esse papel.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.8
  • Três exemplos neste capítulo. rough-lakehouse produz o resultado completo em três formatos, de modo que cada capítulo seguinte altera uma parte de um resultado que você já executou. Os outros dois, append-hours e scan-into-duckdb, constroem a tabela Iceberg um commit por vez e a leem no DuckDB.
  • Horas 00 a 02 primeiro, depois 03 a 05. Os exemplos Iceberg gravam três horas, e o exemplo rough grava seis. Somente rough-lakehouse totaliza as seis horas.
  • Tabelas sem particionamento. O capítulo 1 cria tabelas sem especificação de partição. O capítulo 4 altera o particionamento. O pacote pyiceberg-core é fixado junto ao pyiceberg, porque as transformações de dia e hora do capítulo 4 precisam dele.
  • Inlining desligado nos exemplos. Os exemplos DuckLake definem DATA_INLINING_ROW_LIMIT como 0, de modo que cada inserção grava um arquivo Parquet e as contagens de arquivos têm o mesmo significado onde quer que o livro as mostre. O ducklake-inlined-delete do capítulo 10 mantém o padrão, porque o objetivo ali é mostrar que uma exclusão pequena não grava nenhum arquivo de exclusão.
  • Tabelas Delta são lidas somente pelo QueryBuilder do deltalake. O auxiliar de leitura em examples/lib/lakehouse.py segue esse caminho, e cada capítulo seguinte que lê uma tabela Delta usa o mesmo auxiliar.
  • Dados reais, não substitutos. Cada exemplo deste capítulo lê o recorte dos seis despejos públicos descrito em o README dos dados. O livro não traz dados gerados para este capítulo.
  • SQLite para o catálogo Iceberg. Um arquivo SQLite não precisa de servidor, então os exemplos Iceberg rodam em um notebook com a rede desligada. Essas execuções também desativam o download automático de extensões do DuckDB, de modo que uma execução que precise da rede falha em vez de baixar.
  • Rótulos no lugar de IDs. Os rótulos snapshot 1, snapshot 2 e assim por diante, quando impressos, substituem os IDs de snapshot, de modo que a saída não muda de uma execução para outra.

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.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 1 de 10: Construa uma primeira tabela, de ponta a ponta

  1. O que um formato de tabela acrescenta aos arquivos
  2. Um laço de carga, três estilos de commit
  3. Um commit nomeia os arquivos da tabela
  4. Por que cada formato é ensinado por meio de uma biblioteca Python
  5. Carregar três horas em uma tabela
  6. Criar a tabela em um catálogo
  7. Acrescente cada hora como um commit
  8. Consulte a tabela com o DuckDB
  9. O que dá errado em produção
  10. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos