Escolha um formato a partir do que as suas ferramentas suportam
Cerca de 23 minutos min de leitura, com 5 exemplos em 11 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
Nesta página
- Meça o suporte antes de escolher
- Veja o que as ferramentas fixadas fizeram
- Escrita e leitura de versões
- Alterações e limpeza
- Catálogos e DuckDB
- pyiceberg não grava tabela da versão 3
- Vetores de exclusão exigem uma atualização de protocolo
- Uma lista de verificação para uma nova tabela
- Escolha um formato a partir dos seus leitores
- O que dá errado em produção
- Decisões tomadas neste capítulo
Depois de ler este capítulo, você será capaz de listar todas as ferramentas que leem ou escrevem as suas tabelas, medir o que cada uma suporta na sua versão fixada e escolher um formato e os seus recursos a partir dessas medições.
Ao longo dos capítulos 1 a 9, uma tabela, wiki.pageviews_hourly, passou por toda a sua vida em três formatos: Apache Iceberg, Delta Lake e DuckLake. Cada formato realizou as mesmas tarefas de um jeito diferente, e cada biblioteca suportou um subconjunto diferente dessas tarefas. A escolha que você enfrenta não é qual formato é o melhor em geral. É qual formato todas as ferramentas da sua equipe conseguem abrir, alterar e limpar, nas versões que você executa. Este capítulo mostra como medir isso, apresenta as medições para as versões fixadas neste livro e oferece um guia breve para a escolha.
A escolha depende dos leitores, e o caso que acompanhamos, wiki.pageviews_hourly, tem três deles: um painel que consulta por meio do duckdb, um pipeline que acrescenta dados por meio do pyiceberg e um job de arquivo que lê uma cópia Delta Lake por meio do deltalake. Cada leitor tem a sua própria versão fixada, e cada um precisa abrir os dados que os outros escrevem. É essa a situação para a qual o restante deste capítulo prepara você.
Três fatores tornam a escolha mais difícil do que parece. Os recursos que mais diferem entre os formatos, como exclusões de linhas, renomeações e mudanças de partição, são justamente os que a equipe precisa primeiro. Cada biblioteca muda no seu próprio ritmo, e uma tabela que uma ferramenta lê em uma versão pode não abrir em outra. E uma verificação que passa em uma máquina não diz nada sobre as versões que as suas outras ferramentas executam. As seções deste capítulo tratam de cada um desses pontos, um de cada vez.
Meça o suporte antes de escolher
Um nome de formato não diz o que uma ferramenta suporta. O suporte pertence a uma ferramenta em uma versão específica: um escritor pode criar um recurso que um leitor não consegue abrir, e uma página do fornecedor descreve o motor do fornecedor, não a biblioteca instalada no seu notebook. Por isso, comece pelos leitores, não pelo formato. Anote todas as ferramentas que vão ler a tabela, com a sua versão, e depois teste cada recurso que você planeja usar em cada uma dessas versões.
Cada medição abaixo parte de um leitor e depois testa um recurso nele. O pyiceberg recebe uma exclusão em uma tabela de formato versão 2 e, em seguida, um pedido de versão 3 (iceberg-format-versions). O deltalake recebe vetores de exclusão, ativados e lidos de volta (feature-check). O exemplo ducklake-catalog-version imprime a versão de um catálogo DuckLake, e os exemplos ducklake-delete-files e ducklake-inlined-delete contam os arquivos de exclusão depois de uma exclusão pequena e de uma grande. Cada exemplo imprime uma linha rotulada por resultado, para que você possa comparar a saída com as tabelas da matriz de suporte e com os seus próprios leitores.
A pessoa responsável pela tabela deve executar as medições nas máquinas que rodam os leitores, e não em um notebook de desenvolvedor com versões diferentes. Registre o resultado em uma pequena tabela, com uma linha por leitor. As colunas são o leitor, a sua versão fixada, os recursos de que suas tabelas precisam e a data em que você os mediu. Um recurso sem medição conta como não suportado, e essa regra é a que evita a maioria das falhas adiante neste capítulo.
| Leitor | Versão fixada | Recursos de que você precisa | Medido em |
|---|---|---|---|
| pyiceberg | 0.12.0 | Escritas no formato versão 2, exclusões | Data da sua execução |
Leia cada linha impressa como uma afirmação válida para uma versão de uma ferramenta. Uma linha que diz que uma escrita foi recusada é tão útil quanto uma que diz que ela funcionou, porque a recusa indica qual versão de formato você deve descartar. Um exemplo que captura um erro nomeia a classe do erro, não a sua mensagem, para que a saída continue igual quando uma biblioteca reescrever o texto do erro.
Regra prática: Meça cada leitor na sua própria versão fixada antes de escolher uma versão de formato ou um recurso. Anote cada resultado junto com a versão em que foi medido. Repita a medição sempre que a versão de qualquer leitor mudar, e não reutilize uma tabela de suporte de uma página do fornecedor.
Veja o que as ferramentas fixadas fizeram
Estas tabelas mostram o que as ferramentas fixadas fizeram nas execuções deste livro. Cada coluna corresponde a uma ferramenta: pyiceberg para Iceberg, deltalake para Delta Lake e a extensão DuckLake no DuckDB para DuckLake. As versões fixadas são pyiceberg 0.12.0, deltalake 1.6.6 e DuckDB 2.0.0. A versão 2.0.0 do DuckDB é uma versão de suporte de longo prazo, com data de 21 de outubro de 2026 (calendário de lançamentos do DuckDB). O DuckLake 1.0 foi lançado em 13 de abril de 2026 (calendário de lançamentos do DuckLake). O catálogo nessas versões fixadas informa a versão 1.1, e essa é a versão que você deve abrir. A extensão tem versão própria: o DuckDB informa a sua build como 417a9117f5, e a extensão acompanha o DuckDB 2.0.0, portanto a sua versão segue a do DuckDB. A última coluna indica o exemplo ou a fonte de cada célula. Não aparecer aqui significa uma lacuna neste livro, não uma funcionalidade ausente.
1"""Attach a DuckLake catalog and print its catalog version, which readers must open, and the build of the DuckLake extension that DuckDB loaded. The point rests on the first printed line."""23from lib.lakehouse import attach_ducklake, connect_ducklake, new_warehouse456def main():7 with new_warehouse() as wh:8 con = connect_ducklake(wh.con)9 # the alias also names the catalog's metadata schema, which the next line reads10 attach_ducklake(con, "probe", wh.root)11 # the version is stored as a key and value row in the metadata table; the one row, first column12 version = con.execute("SELECT value FROM __ducklake_metadata_probe.ducklake_metadata WHERE key = 'version'").fetchall()[0][0]13 print("ducklake catalog version:", version)14 # a build hash, not a release number15 extension = con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name = 'ducklake'").fetchall()[0][0]16 print("ducklake extension version:", extension)171819if __name__ == "__main__":20 main()
python ducklake-catalog-version.pyducklake catalog version: 1.1
ducklake extension version: 417a9117f5
Escrita e leitura de versões
| Versões e leituras | pyiceberg | deltalake | DuckLake | Mostrado em |
|---|---|---|---|---|
| Gravar linhas como commits | Sim | Sim | Sim | Gravar três horas |
| Ler um commit anterior pelo número | Sim, por snapshot | Sim, por versão | Sim, por snapshot | Iceberg, Delta e DuckLake |
| Criar a versão 3 do formato | Não, gera um erro | — | — | Exemplo |
| Renomear uma coluna | Sim, por ID de campo | Não, um no-op silencioso | Não mostrado aqui | Iceberg, deltalake |
| Mapeamento de colunas na criação | — | Sim | — | deltalake |
Alterações e limpeza
| Alterações e limpeza | pyiceberg | deltalake | DuckLake | Mostrado em |
|---|---|---|---|---|
| Excluir linhas | Reescreve arquivos | Reescreve arquivos | Grava arquivos de exclusão | Capítulo 5 |
| Arquivos de exclusão gravados | Nenhum | Nenhum | Sim, a menos que estejam embutidos | Versões de formato, verificação de recursos, DuckLake, embutidos |
| Upsert ou merge | Upsert, vários snapshots | Não mostrado aqui | MERGE INTO |
Upserts, MERGE |
| Alterar particionamento | Arquivos antigos mantêm a especificação antiga | Sobrescrever com modo de schema | Alterar com ALTER TABLE |
Capítulo 4, outros formatos |
| Compactar arquivos pequenos | Nenhum método; sobrescrever a tabela | optimize.compact() |
Mesclar arquivos adjacentes | Iceberg, deltalake, DuckLake |
| Expirar snapshots | Por ID ou older_than; não exclui arquivos |
Vacuum por retenção | Expirar e depois limpar | Iceberg, deltalake, DuckLake |
1"""Load six hours into a DuckLake table with data inlining off, then count the delete files that a small and a large delete write. The point rests on the delete-file line after the small delete."""23from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hour45LOW_VIEWS = 180 # few rows of hour 02 fall below this6VERY_LOW_VIEWS = 1000 # most of the table's rows fall below this789def delete_files(con):10 # one row per data file, so the rows with a delete file count the files a delete touched11 return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "12 "WHERE delete_file IS NOT NULL").fetchall()[0][0]131415def main():16 with new_warehouse() as wh:17 con = connect_ducklake(wh.con)18 # 0 turns inlining off, so a delete is written as a delete file rather than kept in the catalog19 create_ducklake_table(con, wh.root, inlining_row_limit=0)20 table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"21 for hour in range(6):22 con.register("hour", read_cut_hour(hour))23 con.execute(f"INSERT INTO {table} SELECT * FROM hour")24 con.unregister("hour")2526 con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")27 print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])28 print("delete files after the small delete:", delete_files(con))2930 # no hour filter, so this delete reaches all six hours31 con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")32 print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])33 print("delete files after the large delete:", delete_files(con))343536if __name__ == "__main__":37 main()
python ducklake-delete-files.pyrows left after the small delete: 2995
delete files after the small delete: 1
rows left after the large delete: 195
delete files after the large delete: 6
1"""Repeat `ducklake-delete-files` with DuckLake's default inlining, to show that the small delete writes no delete file. The point rests on the delete-file line after the small delete."""23from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hour45LOW_VIEWS = 180 # few rows of hour 02 fall below this6VERY_LOW_VIEWS = 1000 # most of the table's rows fall below this789def delete_files(con):10 # one row per data file, so the rows with a delete file count the files a delete touched11 return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "12 "WHERE delete_file IS NOT NULL").fetchall()[0][0]131415def main():16 with new_warehouse() as wh:17 con = connect_ducklake(wh.con)18 # None keeps DuckLake's default inlining; ducklake-delete-files passes 0 to turn it off19 create_ducklake_table(con, wh.root, inlining_row_limit=None)20 table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"21 for hour in range(6):22 con.register("hour", read_cut_hour(hour))23 con.execute(f"INSERT INTO {table} SELECT * FROM hour")24 con.unregister("hour")2526 con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")27 print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])28 print("delete files after the small delete:", delete_files(con))2930 # no hour filter, so this delete reaches all six hours31 con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")32 print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])33 print("delete files after the large delete:", delete_files(con))343536if __name__ == "__main__":37 main()
python ducklake-inlined-delete.pyrows left after the small delete: 2995
delete files after the small delete: 0
rows left after the large delete: 195
delete files after the large delete: 6
Catálogos e DuckDB
| Catálogos e DuckDB | pyiceberg | deltalake | DuckLake | Apresentado em |
|---|---|---|---|---|
| Catálogo necessário | Sim, um catálogo SQL | Não, localizado pelo caminho | Sim, o arquivo de catálogo | Capítulo 8, pelo caminho, arquivo de catálogo |
| O DuckDB lê | Por meio do Arrow | Por meio do Arrow, a partir de QueryBuilder |
Nativamente | Capítulo 1, Capítulo 9, Capítulo 8 |
| O DuckDB grava | — | — | Nativamente, por meio de SQL | Capítulo 8 |
A extensão delta própria do DuckDB é um caminho separado do deltalake. Ela pode gravar tabelas Delta Lake, assunto abordado no guia de decisão abaixo.
Regra prática: Leia cada célula em relação ao exemplo ou à fonte que ela cita. Uma célula sem exemplo por trás dela é uma afirmação a ser testada com seus próprios leitores, e não uma na qual se deva confiar.
pyiceberg não grava tabela da versão 3
A seção da versão 3 da especificação do Iceberg torna os vetores de exclusão binários o formato de exclusão em nível de linha. Ela diz que "os gravadores não podem adicionar novos arquivos de exclusão por posição em tabelas v3" (especificação do Iceberg). A mesma seção acrescenta a linhagem de linhas para novas linhas, os valores padrão de colunas, o tipo variant e os timestamps em nanossegundos.
1"""Create a format version 2 Iceberg table, delete rows from it, then ask pyiceberg for format version 3. The point rests on the last printed line, which shows the refusal."""23from pyiceberg.expressions import LessThan45from lib.lakehouse import create_iceberg_table, new_warehouse, read_cut_hour, scan_arrow67LOW_VIEWS = 180 # about one row in six of hour 00 falls below this8910def main():11 with new_warehouse() as wh:12 table = create_iceberg_table(wh, properties={"format-version": "2"}) # table properties are strings, so the version is quoted13 table.append(read_cut_hour(0))14 print("format version:", table.metadata.format_version)1516 # scan_arrow reads the current snapshot, so the count moves with each commit17 before = scan_arrow(table).num_rows18 table.delete(LessThan("views", LOW_VIEWS))19 print("rows deleted:", before - scan_arrow(table).num_rows)20 # content 0 marks a data file; any other value marks a delete file21 contents = table.inspect.files().column("content").to_pylist()22 print("delete files after the delete:", sum(1 for content in contents if content != 0))23 for number, snapshot in enumerate(table.metadata.snapshots, start=1):24 print(f"snapshot {number} operation:", snapshot.summary.operation.value)2526 # pyiceberg refuses version 3 by raising, so the refusal is caught here and its class printed27 try:28 create_iceberg_table(wh, identifier="wiki.format_three", properties={"format-version": "3"})29 except NotImplementedError as exc:30 print("format version 3 create:", type(exc).__name__)31 else:32 print("format version 3 create: created")333435if __name__ == "__main__":36 main()
python iceberg-format-versions.pyformat version: 2
rows deleted: 82
delete files after the delete: 0
snapshot 1 operation: append
snapshot 2 operation: overwrite
format version 3 create: NotImplementedError
O pyiceberg, nestas versões fixadas, grava a versão de formato 2. O exemplo pede a versão 2 e imprime a versão da sua tabela, que é 2. Um pedido de versão de formato 3 gera NotImplementedError, de modo que nenhum dos recursos da versão 3 está disponível neste gravador.
O pyiceberg exclui dados reescrevendo os arquivos de dados que toca, nestas versões fixadas, embora a versão de formato 2 também permita arquivos de exclusão (capítulo 5). A tabela perdeu 82 linhas e contém 0 arquivos de exclusão. Seus dois snapshots são append e, para a exclusão, overwrite. Meça essa reescrita em uma cópia da sua própria tabela antes de decidir.
| Recurso | Especificação do Iceberg v3 | pyiceberg nestas versões fixadas |
|---|---|---|
| Vetores de exclusão binários | Formato de exclusão em nível de linha | Não gravado |
| Arquivos de exclusão por posição | Legado, apenas em tabelas de versão de formato 2 | Não gravado |
| Linhagem de linhas, valores padrão, variant, timestamps em nanossegundos | Parte da versão 3 | Não disponível: nenhuma tabela da versão 3 |
Regra prática: Grave a versão de formato 2 com o pyiceberg nestas versões fixadas, e não prometa um recurso da versão 3 a nenhum leitor. Escolha a versão 3 somente quando o gravador que você usa a criar e todos os leitores do seu conjunto a abrirem, e verifique ambos em suas próprias versões fixadas.
Vetores de exclusão exigem uma atualização de protocolo
O protocolo do Delta Lake, na versão marcada pelo link que ele indica, diz que uma tabela com vetores de exclusão precisa da versão 3 de leitura e da versão 7 de escrita, com a funcionalidade deletionVectors presente nas duas listas de funcionalidades. Ele também diz que um leitor deve implementar toda funcionalidade da lista de leitura antes de ler a tabela (protocolo Delta). Uma funcionalidade de leitura no protocolo de uma tabela Delta é uma promessa de que todo leitor a trata, então um leitor sem ela não consegue ler a tabela corretamente.
1"""Turn on deletion vectors in a Delta Lake table, delete the rows below 180 views, and print the protocol the table declares. The point rests on the reader features line, which lists what a reader must implement."""23from deltalake import DeltaTable, write_deltalake45from lib.lakehouse import new_warehouse, read_cut_hour, read_delta67LOW_VIEWS = 180 # about one row in six of hour 00 falls below this8910def deletion_vector_files(path):11 """Count files under the table folder that are not Parquet or the Delta log."""12 # the log holds JSON commits and checkpoints, not deletion vectors, so it is skipped13 return sum(1 for item in path.rglob("*")14 if item.is_file() and item.suffix != ".parquet" and "_delta_log" not in item.parts)151617def main():18 with new_warehouse() as wh:19 path = wh.root / "dv_table"20 # delta.enableDeletionVectors is the table property that turns deletion vectors on, set when the table is written21 write_deltalake(str(path), read_cut_hour(0), configuration={"delta.enableDeletionVectors": "true"})22 table = DeltaTable(str(path))23 protocol = table.protocol()24 print("minimum reader version:", protocol.min_reader_version)25 print("minimum writer version:", protocol.min_writer_version)26 # sorted so the printed list reads the same on every run27 print("reader features:", ", ".join(sorted(protocol.reader_features)))2829 # read_delta reads through deltalake's QueryBuilder, the only Delta read path in this book30 before = read_delta(str(path)).num_rows31 metrics = table.delete(f"views < {LOW_VIEWS}")32 print("rows deleted:", before - read_delta(str(path)).num_rows)33 # the delete's num_removed_files metric, which counts the data files it replaced34 print("data files rewritten:", metrics["num_removed_files"])35 print("rows through QueryBuilder:", read_delta(str(path)).num_rows)36 print("deletion vector files:", deletion_vector_files(path))373839if __name__ == "__main__":40 main()
python feature-check.pyminimum reader version: 3
minimum writer version: 7
reader features: deletionVectors, timestampNtz, variantType
rows deleted: 82
data files rewritten: 1
rows through QueryBuilder: 417
deletion vector files: 0
Ativar a configuração muda o que os leitores precisam suportar. Depois de ativada, a tabela declara versão mínima de leitura 3 e versão mínima de escrita 7. Suas funcionalidades de leitura são deletionVectors, timestampNtz, variantType, e um leitor deve implementar cada uma delas. Nós definimos apenas a configuração de vetores de exclusão, então o deltalake adicionou as outras duas funcionalidades por conta própria.
Nesta versão fixada, o deltalake declara a funcionalidade, mas ainda exclui reescrevendo o arquivo. A exclusão das linhas com visualizações abaixo de 180 removeu 82 linhas e reescreveu 1 arquivo de dados, e a tabela contém 0 arquivos de vetores de exclusão. Depois disso, QueryBuilder lê 417 linhas. O livro lê tabelas Delta apenas por meio de QueryBuilder, como mostra o capítulo 8.
Cada funcionalidade da lista importa, não apenas o vetor de exclusão. Um leitor que não tenha timestampNtz ou variantType enfrenta o mesmo problema que um que não tenha deletionVectors. Compare as listas de funcionalidades impressas com a lista de cada leitor depois de cada mudança.
Assim, uma configuração de vetores de exclusão é uma mudança de protocolo para todo leitor da tabela, e a escrita tem sucesso antes que qualquer leitor seja testado. Ative-a somente quando todo leitor do seu conjunto implementar a funcionalidade deletionVectors. Caso contrário, mantenha a cópia na escrita.
Uma verificação de leitor, no sentido usado aqui, abre a tabela pela interface própria do leitor, antes da primeira escrita em produção. Para a cópia do Delta Lake do caso, essa verificação é uma leitura por meio de QueryBuilder e uma leitura do protocolo, ambas no exemplo de verificação de funcionalidades.
Regra prática: Ative vetores de exclusão somente depois de verificar o suporte a funcionalidades de cada leitor na sua própria versão. Leia o protocolo da tabela de volta após cada mudança, e mantenha a cópia na escrita para qualquer tabela que um leitor fora do seu conjunto testado vá abrir.
Uma lista de verificação para uma nova tabela
Use esta lista antes de criar uma tabela que mais de uma ferramenta vai abrir. Cada item fecha um risco que a matriz de suporte e a seção sobre vetores de exclusão mostraram.
- Liste cada leitor e cada escritor, com a respectiva versão. Uma ferramenta que você deixa fora da lista é um leitor que você não testou, e será justamente ele que vai falhar.
- Para cada recurso que a tabela precisa, meça o suporte em cada ferramenta, como os exemplos deste capítulo fazem. Meça o leitor, e não apenas o escritor, porque uma escrita bem-sucedida prova apenas que o escritor consegue produzir os arquivos.
- Defina a versão do formato e o protocolo de forma intencional. Imprima-os de volta e leia a tabela a partir de cada leitor. Não aceite um padrão que você não escolheu.
- Recuse qualquer versão de formato ou recurso que um dos leitores do conjunto não suporte. Uma tabela que um leitor não consegue abrir é uma interrupção, por melhores que sejam os recursos para os demais leitores.
- Prometa renomear uma coluna apenas quando o suporte medido permitir. O Iceberg renomeia por ID de campo. O deltalake não tem renomeação nessas versões fixadas, então planeje uma reescrita e verifique os nomes das colunas depois.
- Mantenha um caminho simples de copy-on-write para as exclusões, a menos que todos os leitores tenham sido testados com vetores de exclusão. O copy-on-write custa arquivos reescritos, mas abre em todos os lugares.
- Planeje qualquer atualização nesta ordem: primeiro os leitores, depois os escritores, por fim o protocolo. Leia a tabela após cada etapa e pare se algum leitor falhar.
- Execute as medições novamente a cada mudança de versão fixada e registre as novas versões na tabela de leitores.
Regra prática: Mantenha a lista junto da nota de projeto da tabela, para que a próxima pessoa que adicionar um leitor parta do mesmo registro. Uma lista mantida atualizada custa menos do que uma refeita depois de uma leitura que falhou.
Escolha um formato a partir dos seus leitores
Use este guia depois de ter medido os seus leitores. A primeira coluna descreve a situação, não o formato. Ele associa um conjunto de leitores medido a um formato, mas não substitui as medições.
| Se a sua situação for | Escolha | Motivo |
|---|---|---|
| pyiceberg e DuckDB leem a tabela | Iceberg, versão de formato 2 | pyiceberg a lê, e o DuckDB consulta a saída dele |
| Vários leitores, e você precisa de renomeações no próprio lugar | Iceberg | Renomeações mantêm o ID do campo, como o capítulo 3 mostra |
| DuckDB é o único motor, e você quer alterações em SQL | DuckLake | Exclusões, merges e mudanças de partição são executados como SQL |
| Tabelas Delta já existem e o deltalake as lê | Manter Delta Lake, sem promessa de renomeação | Altere as partições por sobrescrita e leia de volta após cada mudança |
| Você quer que o DuckDB altere uma tabela Delta | Não nestas versões fixadas | O DuckDB só consegue acrescentar dados; use deltalake para atualizações e exclusões |
A extensão delta do DuckDB pode gravar tabelas Delta Lake. A documentação do DuckDB para a versão fixada, 2.0.0, diz que ela pode criar tabelas e acrescentar dados a elas, e lista UPDATE, DELETE, MERGE INTO, ALTER TABLE e DROP TABLE como não suportados (Documentação do DuckDB sobre delta, Limitations). Nenhum exemplo deste livro executa a extensão. Os exemplos não instalam nada em tempo de execução e usam a biblioteca de cada formato, para que você veja a mesma biblioteca que grava a tabela, e nada é baixado enquanto um exemplo roda.
Leia a tabela linha por linha. Quando duas linhas apontam em direções diferentes, os leitores decidem. Primeiro escolha o formato que todos os leitores do seu conjunto medido abrem e, depois, escolha os recursos que todos esses leitores suportam.
Aplique o guia ao caso contínuo do livro. O painel e o pipeline abrem a tabela pageviews com pyiceberg ou DuckDB, o que aponta para Iceberg, versão de formato 2. O job de arquivamento lê uma cópia em Delta Lake, então a linha Delta se aplica somente a essa cópia, e a cópia mantém suas exclusões como copy-on-write.
Recomendamos Iceberg, versão de formato 2, como padrão para uma tabela que várias ferramentas leem, porque o pyiceberg a grava, o DuckDB lê a saída dele, e os exemplos medem os dois. Seus custos nestas versões fixadas: cada exclusão reescreve os arquivos de dados que toca, a tabela precisa de um catálogo, e o pyiceberg não oferece chamada de compactação nem de limpeza de arquivos órfãos. Recomendamos DuckLake quando o DuckDB é o único motor, porque o leitor e o escritor compartilham a mesma superfície SQL. Seus custos: os leitores ficam limitados ao DuckDB, a versão do catálogo está atrelada à versão do DuckDB, e exclusões pequenas são gravadas em linha (inlined) no catálogo, a menos que você desative esse recurso. Escolha de outra forma quando as verificações deste capítulo mostrarem que um leitor não consegue fazer o que você precisa.
Regra prática: Escolha o formato que todos os leitores do seu conjunto medido abrem e, depois, escolha apenas os recursos que esse conjunto suporta. Se nenhum formato atender a todas as necessidades, divida a tabela ou altere os leitores. Não prometa a um leitor um recurso que as medições não cobrem.
O que dá errado em produção
A maioria das falhas de formato em um lakehouse compartilhado vem de uma ferramenta que o autor não testou, e não de um bug no formato. Cada falha aqui é uma que uma seção anterior mediu ou citou, então você pode verificá-la nas suas próprias tabelas.
Escolher pelas afirmações do fornecedor. Uma página de suporte descreve um motor, muitas vezes em uma versão diferente da sua. Use-a para descobrir o que testar, não como a resposta. Confira a afirmação contra as suas próprias versões fixadas.
Testar apenas um motor. Uma tabela pode ser escrita por uma biblioteca e lida por outra que não oferece suporte ao mesmo recurso. A escrita tem sucesso em uma ferramenta, e a falha aparece quando uma segunda ferramenta abre a tabela. Execute a verificação de leitura para cada ferramenta do conjunto antes da primeira escrita.
Um recurso que o leitor não implementa. A configuração de vetor de exclusão adiciona um recurso de leitura à tabela, e o protocolo exige que os leitores o implementem. Um leitor fora do seu conjunto pode abrir a tabela e falhar nela. Descubra isso pelo registro do protocolo, que o exemplo de verificação de recursos imprime, e não por um erro de consulta posterior.
Uma renomeação que não faz nada. Nessas versões fixadas, a chamada set_column_metadata do deltalake retorna sem erro e incrementa a versão, mas os nomes das colunas permanecem os mesmos. O Capítulo 3 mostra essa armadilha. A verificação consiste em ler os nomes das colunas após a mudança.
Atualizar na ordem errada. Um escritor que avança antes dos seus leitores pode produzir uma tabela que os leitores não conseguem abrir, e o primeiro sinal é uma leitura com falha no job de outra equipe. A ordem da lista de verificação mantém todos os leitores capazes de abrir a tabela em cada etapa.
Julgar uma tabela pela escrita. Uma escrita bem-sucedida mostra que o escritor consegue produzir os arquivos. Ela não mostra que outra ferramenta consegue lê-los. A verificação de vetor de exclusão deste capítulo escreve, exclui e depois conta os recursos do leitor justamente por esse motivo.
Contar linhas em uma exclusão no DuckLake. Com o inlining padrão do DuckLake, uma exclusão pequena de poucas linhas não grava nenhum arquivo de exclusão, enquanto a mesma exclusão com o inlining desativado grava um. Uma verificação que conta linhas diz que a exclusão funcionou nos dois casos. Conte também os arquivos de exclusão, como faz o exemplo de exclusão do DuckLake.
Uma versão do catálogo que muda com o DuckDB. O catálogo do DuckLake nessas versões fixadas informa a versão 1.1, e a extensão que o abre informa a build 417a9117f5. A documentação do DuckLake indica a versão do DuckDB que a versão 1.1 exige (documentação do DuckLake). Um DuckDB mais antigo pode não conseguir abrir esse catálogo, e assim uma atualização pode quebrar um leitor que não mudou.
Regra prática: Meça cada leitor na sua própria versão fixada antes de escrever, atualizar ou confiar em uma afirmação do fornecedor. Ao atualizar um escritor ou um catálogo, mantenha a versão anterior instalada até que todos os leitores tenham aberto o resultado.
Decisões tomadas neste capítulo
- Recomendamos o Iceberg, versão de formato 2, com pyiceberg nestas versões fixadas. Não prometemos a nenhum leitor a versão de formato 3, e não definimos data para essa mudança. A versão fixada decide, e a medição a comprova.
- Apresentamos a matriz como medida nestas versões fixadas, e cada célula aponta para um exemplo ou para uma fonte citada.
- Mantemos os vetores de exclusão fora das tabelas que um leitor fora do conjunto testado vai abrir.
- Não prometemos renomear uma tabela deltalake nestas versões fixadas.
- Contamos os arquivos de exclusão do DuckLake, além das linhas.
- Tratamos como não suportado um recurso que não foi medido, porque todas as falhas deste capítulo vieram de um recurso que alguém presumiu.
- Informamos a versão do catálogo DuckLake separadamente da versão da extensão. A versão do catálogo decide quais leitores podem abrir o catálogo, e a versão da extensão acompanha o DuckDB.
- Escolhemos uma matriz medida em vez da página de suporte de um fornecedor, porque as versões fixadas decidem o que pode ser aberto.
- O padrão do Iceberg, versão de formato 2, é uma decisão de julgamento, e assim está identificado. As medições que o sustentam são os exemplos, e são a parte que você deve executar novamente.
- O livro não executa nenhuma extensão
deltaouicebergdo DuckDB. Seus exemplos não instalam nada em tempo de execução e usam a biblioteca própria de cada formato. A extensãodeltado DuckDB pode gravar tabelas Delta Lake, como descreve a sua documentação.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 20 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.