Registre tabelas em um catálogo e consulte-as a partir do DuckDB
Cerca de 21 minutos min de leitura, com 5 exemplos em 8 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
Neste capítulo, você registra uma tabela Iceberg em um catálogo SQL, conecta um catálogo DuckLake, abre uma tabela Delta Lake pelo seu caminho e executa uma instrução do DuckDB que une uma tabela do Iceberg com uma tabela do DuckLake. Você também aprende o que cada catálogo armazena e o que acontece com uma tabela quando o catálogo e os seus arquivos de dados não concordam.
Os capítulos anteriores abriram cada tabela por meio do seu próprio caminho: um objeto de catálogo para o Iceberg, um arquivo para o DuckLake, uma pasta para o Delta Lake. A primeira tabela registrou wiki.pageviews_hourly em um catálogo SQL do Iceberg sob o nome local. Este capítulo explica o que esse nome faz e o que cada formato usa no lugar dele. Ela também acrescenta uma segunda tabela, wiki.domains. Trata-se de uma lista de 4 linhas com códigos de domínio e o idioma de cada um. Essa tabela fica no catálogo DuckLake, e a seção de junção a une às visualizações de página do Iceberg.
O que um catálogo guarda
Pergunte onde wiki.pageviews_hourly está, e a resposta depende do formato. Por baixo, todo formato guarda uma tabela como arquivos de dados mais arquivos de metadados. Os metadados informam o estado atual da tabela: seu esquema, sua especificação de partições e, diretamente ou por meio de arquivos de manifesto, os arquivos de dados do snapshot ou da versão atual. Cada commit grava novos metadados e move a tabela para eles. O catálogo é o registro que associa o nome de uma tabela ao lugar onde estão seus metadados atuais. Um leitor que pede ao catálogo wiki.pageviews_hourly recebe um ponteiro para os metadados e, em seguida, lê os arquivos de dados que esses metadados listam.
O catálogo guarda ponteiros, não as linhas. Os arquivos Parquet permanecem na pasta do warehouse, e o catálogo indica por onde começar a leitura. Os nomes também têm um segundo nível: wiki é um namespace, e todo nome de tabela Iceberg neste livro é um namespace e um nome de tabela unidos por um ponto.
Escolher um catálogo se resume a duas perguntas: quem escreve a tabela e quem a lê. Uma tabela que um único job escreve e um único engine lê pode morar em um catálogo baseado em arquivos e ser encontrada pelo seu caminho. Uma tabela que vários engines leem precisa de um nome que cada um deles consiga resolver, o que é oferecido por um catálogo SQL ou por um serviço. Recomendamos um catálogo para cada tabela, além de um registro ao lado da tabela que indique seu catálogo e seu responsável. Uma junção entre catálogos, como mostra a seção de junções, funciona em uma única sessão. Ela não transforma os dois catálogos em um só.
Os três formatos deste livro usam três catálogos diferentes:
| Formato | O que nomeia a tabela | Onde estão os metadados atuais |
|---|---|---|
| Iceberg | Um objeto de catálogo SQL, aqui chamado local |
O banco de dados do catálogo, que aponta para o arquivo de metadados |
| DuckLake | O arquivo de catálogo, anexado pelo caminho | Dentro do arquivo de catálogo |
| Delta Lake | Nada; o caminho da pasta da tabela | Na pasta da tabela |
O catálogo REST do Iceberg é um catálogo de outro tipo, um serviço em vez de um arquivo. Sua página sobre o catálogo REST descreve uma API comum, especificada com OpenAPI, para interagir com qualquer catálogo Iceberg, de modo que os clientes precisem de uma única implementação para todos eles. A mesma página diz que o protocolo usa commits baseados em mudanças, de modo que o serviço pode resolver conflitos e tentar novamente do seu lado, e que o serviço de catálogo grava os metadados raiz. Este capítulo não executa um catálogo REST. Cada um precisa de um serviço em execução, e os exemplos aqui rodam offline, sem nenhum serviço. O livro não compara os produtos que implementam o protocolo.
Um catálogo pode guardar mais do que nomes. Classificações e regras de retenção também são metadados de tabela. Data Governance as Code trata deles, e este livro não os ensina.
Regra prática: Antes de escrever em uma tabela, descubra qual catálogo ou caminho a nomeia, e faça backup desse catálogo junto com a pasta de dados. Arquivos Parquet não nomeiam uma tabela. O catálogo nomeia, como mostra a seção sobre falhas.
Registrar uma tabela em um catálogo SQL
O catálogo pyiceberg SqlCatalog mantém suas tabelas em um banco de dados. Você informa a ele um uri para esse banco de dados e um warehouse para a pasta onde ele grava os arquivos de dados e de metadados. Este livro usa um arquivo SQLite para o banco de dados e uma pasta local para o warehouse.
A página de configuração do pyiceberg diz que o catálogo SQL precisa de um banco de dados por trás dele, e alerta que o SQLite não foi feito para concorrência e se adequa a usos exploratórios ou de desenvolvimento. Os exemplos são para desenvolvimento, de modo que essa limitação não altera nada neles. Um catálogo de produção precisa de um banco de dados que vários escritores possam usar.
O próximo exemplo abre o mesmo arquivo de catálogo uma segunda vez, com o mesmo nome, e lê a tabela por meio desse segundo objeto. Em seguida, registra um segundo nome para os metadados da tabela e mostra o que um objeto de catálogo com outro nome consegue enxergar.
1"""Register an Iceberg table in a SQL catalog, then reach it through a second catalog object, a stale object and a2second name. The point rests on the 'loaded object' and 'after a reload' lines, and the last line shows what an3object under another catalog name can see."""45from lib.lakehouse import (ICEBERG_ID, NAMESPACE, create_iceberg_table, new_warehouse,6 open_catalog, read_cut_hour, safe_error, scan_arrow)78with new_warehouse() as wh:9 table = create_iceberg_table(wh)10 for hour in range(3): # hours 0, 1 and 2 of the cut, one commit each11 table.append(read_cut_hour(hour))1213 # A second object with the same catalog name sees the same tables.14 same = open_catalog(wh) # the default name, local, as the first object had15 loaded = same.load_table(ICEBERG_ID)16 print("rows read through the second object:", scan_arrow(loaded).num_rows)1718 # A loaded table is a snapshot of the catalog as it was when loaded.19 stale = same.load_table(ICEBERG_ID)20 table.append(read_cut_hour(3)) # the fourth hour, committed after stale was loaded21 print("rows in the loaded object after another append:", scan_arrow(stale).num_rows)22 print("rows after a reload:", scan_arrow(same.load_table(ICEBERG_ID)).num_rows)2324 # Register the same metadata file under a new name: a pointer, not a copy.25 same.create_namespace("archive")26 same.register_table("archive.pageviews_copy", table.metadata_location)27 print("rows in archive copy:", scan_arrow(same.load_table("archive.pageviews_copy")).num_rows)2829 # An object with another name does not see the namespace: the SQL catalog keeps tables apart by catalog name.30 try:31 open_catalog(wh, name="other").list_tables(NAMESPACE)32 except Exception as exc:33 print("other name:", safe_error(exc, wh))
python register-iceberg-table.pyrows read through the second object: 1499
rows in the loaded object after another append: 1499
rows after a reload: 1999
rows in archive copy: 1999
other name: NoSuchNamespaceError: Namespace does not exist: wiki
O segundo objeto lê 1499 linhas de wiki.pageviews_hourly, as três horas que o capítulo 1 carregou. O pyiceberg armazena cada tabela sob o nome de catálogo que você passa para SqlCatalog. Um objeto com o mesmo nome encontra as mesmas tabelas.
O catálogo e a pasta do warehouse formam um par. O catálogo guarda a localização dos arquivos de metadados, e essas localizações ficam dentro da pasta que a propriedade warehouse indica. Uma cópia do arquivo de catálogo sem a pasta do warehouse, ou a pasta sem o arquivo, deixa você com ponteiros para arquivos que não existem. Faça backup dos dois e mova os dois juntos.
Cada processo abre seu próprio objeto de catálogo, e nenhum compartilha estado com outro. Aqui, dois objetos em um mesmo processo fazem o papel de dois processos.
Uma tabela carregada mantém o estado que tinha no momento do carregamento. Um objeto anterior à inserção da quarta hora ainda lê 1499 linhas, enquanto um recarregamento lê 1999. Um processo que carrega uma tabela no início e a lê no fim lê o estado do início. Ele precisa recarregar para ver os commits feitos nesse intervalo.
Regra prática: Abra um arquivo de catálogo SQL com um único nome em todo o seu código, e recarregue uma tabela antes de lê-la quando outro escritor puder ter feito commit desde que você a carregou. Use SQLite para um escritor por vez, e use um banco de dados feito para escritores concorrentes antes de executar vários.
Registre uma tabela a partir do seu arquivo de metadados
register_table(identifier, metadata_location) adiciona um nome para um arquivo de metadados existente. A página da API do pyiceberg apresenta esse método como a forma de registrar uma tabela a partir de seus metadados, e diz que passar overwrite=True substitui uma entrada que já existe. O exemplo registra os metadados da tabela sob archive.pageviews_copy, em um namespace que ele cria antes. O nome em archive lê as mesmas linhas da tabela original, 1999 delas. Os dois nomes apontam para os mesmos metadados, e o registro não grava nenhum arquivo de dados.
Um nome registrado é uma segunda rota para a mesma tabela, e não uma segunda tabela. Os commits feitos por um nome são os commits de ambos, porque os dois leem os mesmos metadados. Trate um segundo nome como uma rota de leitura, e não como uma cópia de segurança.
Regra prática: Mantenha um único nome de escrita para cada tabela. Registre um arquivo de metadados sob um segundo nome apenas para uma leitura que você vai remover depois, e passe overwrite=True somente quando quiser substituir essa entrada.
Anexar um catálogo do DuckLake
O catálogo do DuckLake é um arquivo de banco de dados, e o DuckDB o anexa com uma instrução ATTACH que começa com ducklake: e informa o caminho do arquivo. O caminho dos dados, a pasta onde o DuckLake grava os arquivos Parquet, fica armazenado no catálogo. A página do DuckLake sobre conexão diz que a localização do armazenamento dos dados só precisa ser informada quando um novo DuckLake é criado, e que essa localização é carregada do banco de dados do catálogo depois disso. O auxiliar connect_ducklake carrega o DuckLake na sessão do DuckDB com os downloads desativados, e attach_ducklake executa o ATTACH para um arquivo de catálogo localizado em uma pasta.
O próximo exemplo cria wiki.domains em um catálogo novo do DuckLake, desanexa o catálogo e anexa o arquivo novamente, sem caminho de dados. Em seguida, lista as tabelas do esquema wiki do arquivo.
1"""Attach a DuckLake catalog file, detach it, and attach it again from the file alone. The point rests on the2'rows after re-attach' line, and the table list shows what the catalog holds, not what the data folder holds."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, attach_ducklake, connect_ducklake,5 create_ducklake_domains, new_warehouse, print_rows, sql_rows)67with new_warehouse() as wh:8 con = connect_ducklake(wh.con)9 create_ducklake_domains(con, wh.root) # inlining is off, so the rows become Parquet files10 print("rows written:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])1112 # Detach, then attach with no DATA_PATH: the catalog file stores the data path.13 con.execute(f"DETACH {DUCKLAKE_ALIAS}")14 attach_ducklake(con, DUCKLAKE_ALIAS, wh.root)15 print("tables in the catalog:")16 print_rows(sql_rows(con, f"""SELECT schema_name, table_name FROM duckdb_tables()17 WHERE database_name = '{DUCKLAKE_ALIAS}' AND schema_name = '{NAMESPACE}'"""))18 print("rows after re-attach:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])
python attach-ducklake.pyrows written: 4
tables in the catalog:
wiki domains
rows after re-attach: 4
São gravadas 4 linhas de wiki.domains, e 4 linhas são lidas de volta após a nova anexação. A lista de tabelas mostra uma tabela no esquema wiki, domains. A segunda anexação não precisou de caminho de dados, porque o arquivo já o continha. A listagem vem do catálogo, não da pasta de dados. O arquivo de catálogo guarda a lista de tabelas, e a pasta de dados guarda os bytes. Perder o primeiro significa perder os nomes, mesmo que o segundo esteja íntegro, como mostra a seção sobre falhas.
A mesma página sobre conexão diz que o DuckLake embute pequenas inserções no banco de dados do catálogo, com limite padrão de 10 linhas. O auxiliar usado neste capítulo define o limite de embutimento como 0, de modo que cada inserção nestes exemplos se torna um arquivo Parquet na pasta de dados, como explica a configuração do capítulo 1. Sem essa configuração, uma tabela pequena fica no arquivo de catálogo, e uma cópia da pasta de dados não conteria as suas linhas. Esse é um dos motivos pelos quais o arquivo de catálogo precisa de um backup próprio.
Regra prática: Faça backup de um arquivo de catálogo do DuckLake junto com a pasta de dados, e copie o arquivo enquanto nenhuma sessão o tiver anexado. Informe o caminho dos dados ao criar um catálogo, e anexe depois usando somente o arquivo de catálogo.
Encontre uma tabela pelo caminho, sem catálogo
Uma tabela Delta Lake neste livro é uma pasta. Ela não tem catálogo, e nada na configuração deste livro a identifica além do seu caminho. O pacote deltalake abre a pasta com DeltaTable(path), e toda leitura passa por esse caminho. As três inclusões do próximo exemplo são as versões 0, 1 e 2.
1"""Open a Delta Lake table by its path, with no catalog, and read its first version and its current one. The point2rests on the 'rows at that version' and 'rows at version 0' lines, and the missing-path line shows the error."""34from deltalake import DeltaTable, write_deltalake56from lib.lakehouse import new_warehouse, read_cut_hour, read_delta78with new_warehouse() as wh:9 path = str(wh.root / "delta" / "pageviews_hourly")10 for hour in range(3):11 write_deltalake(path, read_cut_hour(hour), mode="append") # each append is one version, counted from 01213 table = DeltaTable(path)14 print("delta version:", table.version())15 print("rows at that version:", read_delta(path).num_rows)16 print("rows at version 0:", read_delta(path, version=0).num_rows)1718 # The path is the only name a Delta table has here: a wrong path is a missing table.19 try:20 DeltaTable(str(wh.root / "delta" / "pageviews_typo")) # a path never written, so no log to open21 print("missing path: opened")22 except Exception as exc:23 print("missing path:", type(exc).__name__)
python open-delta-by-path.pydelta version: 2
rows at that version: 1499
rows at version 0: 499
missing path: TableNotFoundError
A versão atual da tabela é 2, e ela lê 1499 linhas. A versão 0 contém 499 linhas, apenas a primeira hora. As linhas aqui são obtidas com read_delta, que devolve uma tabela Arrow. As decisões no fim deste capítulo explicam por que o livro lê tabelas Delta dessa forma.
O caminho é o nome completo, então um erro de digitação nele equivale a uma tabela inexistente. O exemplo abre uma pasta que não existe, e DeltaTable lança TableNotFoundError. O erro indica o caminho que tentou usar, mas somente depois que o caminho errado foi usado; por isso, a verificação pertence ao código que monta o caminho.
Um caminho é um bom nome para uma tabela que um job escreve e poucos jobs leem. Não exige serviço nem configuração. Ele tem custos, porém. Um caminho não indica em qual namespace a tabela está, então duas tabelas com o mesmo nome de pasta em lugares diferentes parecem idênticas para quem lê. Um motor que queira encontrar a tabela pelo nome não tem o que consultar. As tabelas Delta deste livro são pequenas e locais, e o caminho basta para elas. Um data lake compartilhado, lido por vários motores, precisa de um catálogo para suas tabelas Delta Lake, e este livro não ensina um.
Regra prática: Mantenha o caminho de cada tabela Delta em um único lugar que o seu código leia, como um valor de configuração, e abra a tabela uma vez, no início de um job, para confirmar o caminho. Um caminho que não existe é um erro, não uma tabela vazia.
Juntar tabelas de dois catálogos
O DuckDB pode consultar, em uma única instrução, uma tabela Arrow que uma biblioteca lhe entrega e uma tabela DuckLake anexada à mesma sessão. A tabela Iceberg sai do pyiceberg como uma tabela Arrow por meio de scan_arrow. O DuckDB registra essa tabela sob um nome, e o join lê wiki.domains pelo catálogo anexado. O livro não carrega a extensão iceberg do DuckDB para isso, de modo que o lado Iceberg é apenas a tabela Arrow.
1"""Join an Iceberg table, read through Arrow, with a DuckLake table in one DuckDB statement. The point rests on the2'rows with no language' line, and the top-three block shows which rows the join returns first."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_iceberg_table,5 create_ducklake_domains, new_warehouse, print_rows, read_cut_hour,6 scan_arrow, sql_rows)78with new_warehouse() as wh:9 table = create_iceberg_table(wh)10 for hour in range(3): # hours 0, 1 and 2 of the cut11 table.append(read_cut_hour(hour))12 con = connect_ducklake(wh.con)13 create_ducklake_domains(con, wh.root)1415 pageviews = scan_arrow(table) # read now: the join sees the table as it is at this line16 # sql_rows registers pageviews under that keyword name, so the SQL can refer to it as pageviews17 joined = f"FROM pageviews p JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code"18 print("joined rows:", sql_rows(con, f"SELECT count(*) {joined}", pageviews=pageviews)[0][0])19 # the left join keeps every pageview, and this condition counts the ones that found no domain row20 print("rows with no language:", sql_rows(con, f"""SELECT count(*) FROM pageviews p21 LEFT JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code22 WHERE d.domain_code IS NULL""", pageviews=pageviews)[0][0])23 print("top three by views:")24 print_rows(sql_rows(con, f"""SELECT p.domain_code, d.language, p.page_title, p.views {joined}25 ORDER BY p.views DESC, p.domain_code, p.page_title, p.hour_utc LIMIT 3""", pageviews=pageviews, keep_order=True),26 keep_order=True)
python join-pageviews-and-domains.pyjoined rows: 1499
rows with no language: 0
top three by views:
en English Main_Page 64859
en English Main_Page 64564
en English Main_Page 61107
Todo código de domínio nas visualizações de página está na dimensão de 4 linhas. O join associa 1499 linhas de visualizações de página a um idioma e deixa 0 sem um. As três primeiras linhas por visualizações são a mesma página, Main_Page no domínio em inglês.
A chave do join é domain_code, uma string nos dois lados. Um join em uma chave que difere em maiúsculas e minúsculas ou em espaços no final não associa nada: a contagem de linhas unidas cairia para 0, e a contagem de linhas sem idioma seria igual ao número de linhas da tabela. Verifique a chave nos dois lados, na mesma sessão, antes de confiar em um join.
A consulta funciona porque os dois lados se encontram em uma única sessão do DuckDB. Ela não transforma as duas tabelas em uma só. Cada uma mantém os próprios commits, e a tabela Arrow é um instantâneo da tabela Iceberg no momento em que scan_arrow foi executado. Um join sobre uma tabela que outro escritor está alterando lê o estado que estava vigente naquele momento.
Recomendamos um join entre catálogos para consultas de referência (lookups) como esta: uma pequena tabela de dimensão que permanece no próprio catálogo, lida por uma consulta sobre uma tabela grande. Quando uma tabela aparece em quase todas as consultas que leem outra, copie-a para o catálogo que essas consultas usam. O Capítulo 9 copia uma tabela entre formatos e verifica cada cópia, e essa verificação é o passo a dar antes de mover uma tabela para qualquer lugar.
Regra prática: Faça join entre catálogos em uma única sessão somente quando o lado que você lê como Arrow couber na memória. Escolha o estado dele antes de lê-lo, e conte as linhas que não encontram correspondência, que devem ser zero.
O que dá errado em produção
Os sintomas costumam ser pequenos: uma contagem que deixa de mudar, um namespace que some, ou um erro de leitura em uma tabela que antes era lida sem problemas. Cada caso aqui parte de um desses sintomas.
Somente a última falha abaixo não tem exemplo.
O nome errado do catálogo. A última linha de register-iceberg-table abre o mesmo arquivo sob o nome other. Listar o namespace então falha com NoSuchNamespaceError: Namespace does not exist: wiki. A tabela continua no arquivo. O catálogo SQL delimita suas tabelas pelo nome do catálogo, então o segundo nome enxerga um catálogo vazio. A mensagem cita o namespace, não o nome, e por isso o erro parece um schema inexistente. Um job que monta o nome do catálogo a partir de configuração pode falhar assim depois de uma pequena edição. Você percebe o problema na primeira leitura, não na escrita, então registre o nome do catálogo no início do job.
O ponteiro desatualizado. Um processo que carrega uma tabela e a lê muito depois lê o estado do momento em que foi carregada. register-iceberg-table mostrou 1499 linhas no objeto carregado, onde um recarregamento mostra 1999. Nada falha. O job roda e informa menos linhas do que a tabela tem. Você percebe quando dois jobs discordam de uma contagem, então mantenha o carregamento junto da leitura.
O arquivo de catálogo substituído por um vazio. O exemplo seguinte anexa um arquivo de catálogo novo e vazio à pasta de dados de um catálogo ativo, e depois executa ducklake_delete_orphaned_files com cleanup_all => true. A página de limpeza do DuckLake mostra cleanup_all apagando todos os arquivos órfãos, e dry_run listando-os em vez de apagá-los. Ela define um órfão como um arquivo que o catálogo em que você executa a limpeza não rastreia. Um catálogo novo não rastreia nada, então todo arquivo Parquet da pasta é um órfão para ele.
1"""Run cleanup_all against a fresh, empty DuckLake catalog that shares a data folder with a live one. The point rests2on the 'parquet files after cleanup_all' line and the 'reading the live catalog' line."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_ducklake_domains,5 new_warehouse, sql_rows)67# One statement, run twice: first with dry_run => true, then for real. {dry} holds the dry-run argument or nothing.8CLEANUP = "CALL ducklake_delete_orphaned_files('fresh', cleanup_all => true{dry})"910def parquet_count(root):11 # the data folder that attach_ducklake gives the catalog with the live alias; rglob searches it at any depth12 return len(list((root / f"{DUCKLAKE_ALIAS}_data").rglob("*.parquet")))1314with new_warehouse() as wh:15 con = connect_ducklake(wh.con)16 create_ducklake_domains(con, wh.root)17 print("parquet files, live catalog:", parquet_count(wh.root))1819 # A replacement catalog: a new, empty file that points at the same data folder.20 con.execute(f"DETACH {DUCKLAKE_ALIAS}")21 # Attached by hand: attach_ducklake would give fresh its own data folder, not the live one.22 con.execute(f"ATTACH 'ducklake:{wh.root}/fresh.ducklake' AS fresh (DATA_PATH '{wh.root}/{DUCKLAKE_ALIAS}_data/')")23 print("files the dry run lists:", len(sql_rows(con, CLEANUP.format(dry=", dry_run => true"))))24 con.execute(CLEANUP.format(dry=""))25 print("parquet files after cleanup_all:", parquet_count(wh.root))2627 # The live catalog still names the table, and its data files are gone.28 con.execute(f"ATTACH 'ducklake:{wh.root}/{DUCKLAKE_ALIAS}.ducklake' AS live")29 print("count through the live catalog:", sql_rows(con, f"SELECT count(*) FROM live.{NAMESPACE}.domains")[0][0])30 try:31 print("reading the live catalog:", len(sql_rows(con, f"SELECT domain_code, language FROM live.{NAMESPACE}.domains")))32 except Exception as exc:33 print("reading the live catalog:", type(exc).__name__)
python ducklake-orphan-cleanup-hazard.pyparquet files, live catalog: 1
files the dry run lists: 1
parquet files after cleanup_all: 0
count through the live catalog: 4
reading the live catalog: IOException
Um catálogo novo basta para apagar os dados ativos. Antes da limpeza, os dados do catálogo ativo estão em 1 arquivo Parquet. A execução de teste com cleanup_all lista 1 arquivo, que a execução real apaga, e depois a pasta fica com 0 arquivos Parquet.
Uma verificação de contagem passa aqui, e essa é a armadilha: ela não revela arquivos ausentes. O catálogo ativo ainda nomeia a tabela e responde count(*) com 4, a partir das estatísticas do catálogo. Ler as colunas falha com IOException.
A ordem segura começa pelo que o exemplo pulou. Faça primeiro uma cópia de segurança do arquivo de catálogo. Execute a limpeza com dry_run => true no catálogo que é dono da pasta de dados e leia a lista. Execute-a de verdade somente quando cada arquivo listado for um que você sabe ser órfão. Nunca execute cleanup_all => true contra um catálogo que você não confirmou.
Dois escritores em um mesmo catálogo SQLite. A documentação do pyiceberg diz que o SQLite não foi feito para concorrência. Este capítulo não mostra o que dois escritores causam no catálogo SQL, então o livro não afirma que sejam seguros. O exemplo do ponteiro desatualizado é o caso mais próximo que ele mostra: um objeto carregado antes de um commit lê o estado mais antigo, e nenhum erro é lançado. Um escritor que segura um objeto antigo não escreve sobre esse estado antigo. Na versão fixada do pyiceberg, um append feito por meio desse objeto é repetido contra os metadados novos e é confirmado sobre o estado mais recente. O livro não faz afirmações sobre outras operações, nem sobre dois processos em um mesmo catálogo SQLite. A regra de recarregamento da seção do catálogo SQL vale para leituras.
Regra prática: Execute uma limpeza de órfãos com dry_run => true primeiro, no catálogo que é dono da pasta de dados, e leia a lista antes de qualquer execução real. Se o arquivo de catálogo estiver ausente ou vazio, restaure-o antes de executar qualquer coisa que apague arquivos.
Decisões tomadas neste capítulo
- O Iceberg está registrado em um catálogo SQL do pyiceberg, sobre SQLite, com um warehouse local. O livro tem um único nome de catálogo,
local, e todos os exemplos o usam. A documentação do pyiceberg descreve o SQLite para desenvolvimento, e os exemplos são exemplos de desenvolvimento. - As tabelas Iceberg chegam ao DuckDB como tabelas Arrow. O livro não usa a extensão
icebergdo DuckDB, então os exemplos leem os dados Iceberg por meio descan_arrow. - As tabelas Delta Lake são encontradas pelo caminho, e o livro não ensina nenhum catálogo Delta. Todo exemplo Delta abre uma pasta, e uma pasta ausente é um erro.
- As tabelas Delta são lidas somente por meio de
QueryBuilder. Esta é uma medição do build do livro, não uma fonte primária. Nas versões fixadas, os outros métodos de conversão para Arrow abortaram o processo na saída em cerca de 17 de 20 execuções. O caminho comQueryBuildernão abortou em nenhuma das 24 execuções, incluindo leituras de versões anteriores. - O DuckLake é carregado por
connect_ducklake, com downloads desativados. Todos os exemplos são executados offline nas versões fixadas do DuckDB. - O risco de limpeza é executado em uma pasta temporária e imprime apenas contagens. O livro mostra a falha para que a ordem dos passos seguros fique clara. Ele não imprime nomes de arquivos, que mudam a cada execução.
- Cada exemplo imprime apenas contagens e valores rotulados, pelo motivo indicado no capítulo 1: assim a saída é igual em todas as execuções e em todas as máquinas.
- Os catálogos REST não têm exemplo executável. Eles precisam de rede, então o capítulo descreve o protocolo a partir da página do protocolo e não faz nenhuma afirmação sobre qualquer produto.
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.