Alterar o particionamento sem reescrever os arquivos antigos
Cerca de 23 minutos min de leitura, com 4 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
Aqui você altera o particionamento de uma tabela no Iceberg, no Delta Lake e no DuckLake, e conta os arquivos que uma consulta planeja antes e depois da mudança. O particionamento decide quais arquivos uma consulta abre, então uma alteração nele muda o que cada leitor paga. O que ela faz com os arquivos já gravados depende do formato.
wiki.pageviews_hourly, cujos painéis leem uma hora por vez, é particionada por dia, e a pergunta é como reagrupá-la por hora sem reescrever o que já foi carregado. As três cargas horárias desde o início já estão em disco. Assim, a equipe quer partições por hora para cada carga posterior à hora 02, e precisa saber o que a mudança faz com as três cargas existentes, sem copiá-las.
A mudança tem dois custos. O primeiro é o trabalho para fazê-la, que depende de o formato deixar ou não os arquivos antigos intactos. O segundo é o que cada consulta posterior paga, já que uma consulta que atravessa a mudança planeja arquivos das duas eras. Este capítulo mede os dois com contagens de cada biblioteca, para que a decisão se apoie no que as tabelas fazem, e não em uma descrição do formato.
As especificações de particionamento também são versionadas
Uma especificação de particionamento define como uma tabela agrupa as suas linhas, por exemplo, um grupo por dia de hour_utc. No Iceberg, a especificação faz parte dos metadados da tabela, e o manifesto que lista cada arquivo de dados registra a especificação com que aquele arquivo foi gravado. Ao mudar a especificação, cria-se uma segunda especificação, com ID próprio. As gravações seguintes usam a segunda especificação, e os arquivos já existentes mantêm a especificação com que foram gravados. A especificação do Iceberg afirma que uma especificação alterada é adicionada à lista de especificações de particionamento da tabela sob um ID de especificação único, e que cada manifesto registra o ID da especificação usada para gravá-lo (partition_spec_id).
Isso dá à tabela duas épocas de particionamento lado a lado. Uma consulta lê a especificação de cada arquivo que abre, de modo que uma mesma leitura pode cobrir arquivos sob várias especificações. O planejador faz isso por você, então o custo da mudança aparece no plano e na contagem de arquivos, não nas linhas que a consulta devolve. Uma consulta escrita para hour_utc mantém o seu texto quando a especificação muda, que é o objetivo do desenho. O que muda é o conjunto de arquivos que o planejador abre. O restante deste capítulo mostra os dois casos.
A mudança de especificação afeta apenas os metadados. O Iceberg grava uma especificação com ID próprio e deixa os arquivos de dados intactos, como mostram as contagens de arquivos em a próxima seção.
A especificação antiga também permanece como histórico. A tabela guarda um registro de todas as especificações que já teve, então um leitor sempre consegue descobrir com quais campos um arquivo foi gravado. Isso importa para uma equipe que muda o particionamento mais de uma vez: cada arquivo responde à pergunta "como fui dividido?" com a sua própria especificação, e ninguém precisa lembrar a ordem das mudanças. O registro é metadado, por isso custa pouco, mas a lista de especificações da tabela cresce a cada mudança.
Os outros dois formatos tratam o particionamento de outra maneira, e essas diferenças determinam o custo de uma mudança. O Delta Lake recebe as colunas de partição pelo nome, então quem grava as cria como colunas. O DuckLake mantém as chaves de particionamento no seu catálogo. Cada um tem sua parte em a seção sobre os outros formatos, depois dos passos do Iceberg de que o restante do capítulo depende.
Regra prática: Altere uma especificação de particionamento do Iceberg quando os filtros dos seus leitores mudarem e a especificação atual planejar arquivos demais para eles. Se a especificação atual já planeja poucos arquivos para esses filtros, deixe-a como está. Ao fazer a mudança, deixe os arquivos antigos onde estão. Registre a mudança no runbook da tabela, com a data, os campos antigos e os substitutos, e os filtros dos leitores que a motivaram. Guarde junto dela as contagens do plano antes e depois da mudança, como mostra a seção sobre o que uma consulta lê.
Mudar de partições diárias para horárias
Cada exemplo constrói sua tabela a partir de o recorte mais uma vez, com as colunas originais e não com as que o capítulo 3 acrescentou. Para passar a tabela para horas, você troca uma transformação de hour_utc por outra. O Iceberg particiona por uma transformação de uma coluna: a transformação de dia coloca cada linha no seu dia do calendário, e a transformação de hora coloca cada linha na sua hora. A biblioteca pyiceberg calcula essas transformações com o pacote pyiceberg-core, e a transformação de dia importa esse pacote quando escreve. Uma instalação só com pyiceberg portanto falha na primeira inserção sob uma partição de dia ou de hora (código-fonte do pyiceberg 0.12.0, pyiceberg/transforms.py, DayTransform.pyarrow_transform). As versões fixadas neste livro incluem pyiceberg-core em 0.11.0, ao lado de pyiceberg em 0.12.0.
A tabela começa com uma especificação de dia. As horas 00 a 02 são carregadas sob ela. Depois a especificação muda, e as horas 03 a 05 são carregadas sob a especificação de hora. A mudança é um único bloco update_spec() que remove o campo de dia e adiciona o campo de hora:
with table.update_spec() as update:
update.remove_field("ts_day")
update.add_field("hour_utc", HourTransform(), "ts_hour")
Ambas as chamadas vão em um só bloco, de modo que a tabela recebe uma única mudança de especificação com o campo de dia removido. A lista de especificações, impressa em ordem com a transformação de cada campo, mostra o que a mudança fez. Os nomes dos campos são os que este livro usa, ts_day e ts_hour, para que um rótulo de especificação diga qual transformação cada campo aplica. A coluna de origem continua hour_utc. O campo de dia e o campo de hora são duas transformações dessa coluna, então o filtro de um leitor sobre a coluna continua funcionando nas duas eras.
1"""Partition an Iceberg table by day, change its spec to hour, and load more hours under the new spec.23The two `data files` lines carry the point, one count for each spec.4"""56from collections import Counter78from pyiceberg.partitioning import PartitionField, PartitionSpec9from pyiceberg.transforms import DayTransform, HourTransform1011from lib.lakehouse import create_iceberg_table, new_warehouse, read_cut_hour, safe_error, scan_arrow121314def main():15 try:16 with new_warehouse() as wh:17 # source_id 1 is hour_utc, the table's first column: the day transform reads that column18 day_spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name="ts_day"))19 table = create_iceberg_table(wh, partition_spec=day_spec)20 for hour in range(3): # hours 00 to 02, written under the day spec21 table.append(read_cut_hour(hour))2223 # hour_utc is the source of the hour field too, as it was of the day field24 with table.update_spec() as update:25 update.remove_field("ts_day")26 update.add_field("hour_utc", HourTransform(), "ts_hour")27 for hour in range(3, 6): # hours 03 to 05, written under the hour spec28 table.append(read_cut_hour(hour))2930 # the labels number the specs in the order they were made, so the output names no spec ID31 specs = sorted(table.specs())32 labels = {spec_id: f"spec {number}" for number, spec_id in enumerate(specs, start=1)}33 for spec_id in specs:34 for field in table.specs()[spec_id].fields:35 print(f"{labels[spec_id]} field {field.name}: transform {field.transform}")3637 # group the data files by the spec_id each one carries38 files = Counter(table.inspect.data_files().column("spec_id").to_pylist())39 for spec_id in specs:40 print(f"{labels[spec_id]} data files: {files[spec_id]}")41 print(f"rows in table: {scan_arrow(table).num_rows}")42 except Exception as exc:43 print(safe_error(exc))44 raise SystemExit(1)454647if __name__ == "__main__":48 main()
python day-then-hour-spec.pyspec 1 field ts_day: transform day
spec 2 field ts_hour: transform hour
spec 1 data files: 3
spec 2 data files: 3
rows in table: 2999
Leia a saída de cima para baixo. A especificação 1 tem um campo, ts_day, com a transformação de dia. A especificação 2 tem um campo, ts_hour, com a transformação de hora. As linhas da tabela estão todas presentes depois da mudança: 2999 linhas, que são as três horas antes da mudança e as três depois dela.
A mudança de especificação é o único passo que toca apenas os metadados. As cargas de cada lado dela escrevem arquivos de dados como de costume, e a próxima subseção mostra a qual especificação cada arquivo pertence.
Um erro aqui aparece depois, e não na própria mudança. Se a lista de especificações estiver errada, toda carga após a mudança grava arquivos com o particionamento incorreto, e as contagens na próxima seção são o primeiro lugar onde você percebe isso. Verificar a lista de especificações logo após a mudança custa uma linha de saída e poupa uma reescrita.
Regra prática: No Iceberg, faça a mudança de especificação em um único bloco update_spec(), de modo que o campo antigo seja removido na mesma alteração que adiciona o substituto. Separe as duas edições apenas se um passo tiver de rodar entre elas; este capítulo não tem tal passo. Verifique a lista de especificações após a mudança, e confirme que os nomes dos campos e as transformações são os que você pretendia antes de carregar qualquer dado sob a segunda especificação.
Arquivos gravados em cada spec
Cada arquivo de dados pertence à spec sob a qual foi gravado, de modo que contar os arquivos por spec informa a qual época cada arquivo pertence. A listagem dos arquivos de dados traz o ID da spec de cada arquivo, então a contagem pode agrupar os arquivos por spec, com uma contagem por spec sob os rótulos "spec 1" e "spec 2". Os rótulos numeram as specs na ordem em que foram criadas, então a saída não menciona nenhum ID de spec.
As três cargas particionadas por dia mantiveram seus arquivos ao longo da mudança. A saída mostra 3 arquivos de dados sob a spec 1 e 3 sob a spec 2, o que significa que as três cargas particionadas por hora gravaram os seus próprios, e que a mudança de spec em si não gravou nada. Se a contagem sob a spec 1 tivesse caído após a mudança, algo teria reescrito esses arquivos, e você precisaria descobrir o que foi antes de confiar nos dados da época antiga.
Regra prática: Após qualquer mudança de spec, conte os arquivos de dados sob cada spec e compare as contagens com as cargas que você fez. Uma contagem que se altera quando nenhuma reescrita estava prevista significa que a mudança fez mais do que você queria, então pare e verifique antes da próxima carga.
Verifique o que uma consulta varre
Uma especificação de partição é uma forma de pular arquivos. Antes que uma consulta leia um arquivo, o planejador observa os valores de partição do arquivo e os limites de suas colunas, e descarta os arquivos que não podem corresponder ao filtro. Sua consulta só é tão barata quanto os arquivos que ela não planeja. Por isso, a forma de verificar uma mudança é contar os arquivos que um filtro típico planeja, antes e depois da mudança, em vez de comparar as linhas. Planejar uma leitura devolve a lista de arquivos sem ler suas linhas, então a contagem é barata o bastante para ser feita antes de qualquer mudança.
A poda é onde a mudança compensa, então planeje três leituras duas vezes: uma vez sob a especificação diária (veja migrando para partições por hora), e de novo depois das três cargas particionadas por hora. Dois filtros pedem cada um uma hora: a hora 01, que foi carregada antes da mudança, e a hora 04, que foi carregada depois dela. O terceiro não tem filtro e é uma leitura completa.
1"""Count the files an Iceberg scan plans for one hour, for another hour and for the whole table, before and after a spec change.23The filtered counts are the lines to compare, one pair for each filter.4"""56from pyiceberg.partitioning import PartitionField, PartitionSpec7from pyiceberg.transforms import DayTransform, HourTransform89from lib.lakehouse import create_iceberg_table, hour_filter, new_warehouse, read_cut_hour, safe_error101112def plan_counts(table):13 """Return the files planned for hour 01, for hour 04 and for no filter, in that order."""14 # plan_files gives the planned files as a list; each printed count is that list's length15 one_hour = len(table.scan(row_filter=hour_filter(1)).plan_files())16 # hour 04 is loaded only after the change, so the filter can match only an hour-partitioned file17 hour_four = len(table.scan(row_filter=hour_filter(4)).plan_files())18 everything = len(table.scan().plan_files())19 return one_hour, hour_four, everything202122def main():23 try:24 with new_warehouse() as wh:25 day_spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name="ts_day"))26 table = create_iceberg_table(wh, partition_spec=day_spec)27 for hour in range(3): # hours 00 to 02, under the day spec28 table.append(read_cut_hour(hour))29 one_hour, hour_four, everything = plan_counts(table)30 print(f"before the change, one-hour filter plans: {one_hour}")31 print(f"before the change, hour 04 filter plans: {hour_four}")32 print(f"before the change, no filter plans: {everything}")3334 with table.update_spec() as update:35 update.remove_field("ts_day")36 update.add_field("hour_utc", HourTransform(), "ts_hour")37 for hour in range(3, 6): # hours 03 to 05, under the hour spec38 table.append(read_cut_hour(hour))39 one_hour, hour_four, everything = plan_counts(table)40 print(f"after the change, one-hour filter plans: {one_hour}")41 print(f"after the change, hour 04 filter plans: {hour_four}")42 print(f"after the change, no filter plans: {everything}")43 except Exception as exc:44 print(safe_error(exc))45 raise SystemExit(1)464748if __name__ == "__main__":49 main()
python plan-files-by-partition.pybefore the change, one-hour filter plans: 1
before the change, hour 04 filter plans: 0
before the change, no filter plans: 3
after the change, one-hour filter plans: 1
after the change, hour 04 filter plans: 1
after the change, no filter plans: 6
| Etapa | Filtro de uma hora | Filtro da hora 04 | Sem filtro |
|---|---|---|---|
| Antes da mudança, três cargas particionadas por dia | 1 | 0 | 3 |
| Depois da mudança, três cargas particionadas por hora adicionadas | 1 | 1 | 6 |
Cada filtro alcança o arquivo da sua própria hora, na era em que essa hora foi carregada. O filtro de uma hora planeja 1 arquivo antes da mudança e 1 arquivo depois dela, e o filtro da hora 04 planeja 0 arquivos antes e 1 arquivo depois. A hora 01 foi carregada antes da mudança, então o único arquivo presente nos dois planos é o arquivo particionado por dia dessa hora. Antes da mudança, os três arquivos compartilham um mesmo dia, então o planejador só pode pular os outros dois pelos limites de hour_utc. Depois da mudança, os três arquivos particionados por hora também podem ser pulados. A hora 04 funciona ao contrário. Nenhum arquivo particionado por dia a contém, então sua única correspondência é o arquivo particionado por hora que guarda essa hora. As contagens não mostram se o planejador pulou um arquivo pelos valores de partição ou pelos limites de suas colunas; mostram apenas o que o plano manteve.
A contagem de planos é uma contagem de arquivos, não de bytes. Dois planos com a mesma contagem podem ler quantidades diferentes de dados, porque os arquivos têm tamanhos diferentes. Mesmo assim, a contagem é a primeira verificação certa, porque é o número com base no qual o planejador decide. Quando as contagens coincidem e a consulta continua lenta, observe os tamanhos dos arquivos e a própria consulta.
A leitura completa paga por cada arquivo que a tabela já gravou. Seu plano cresce de 3 arquivos para 6, os arquivos particionados por dia somados aos particionados por hora. Esse crescimento é o custo de manter os arquivos antigos no lugar, e é a razão para contar a leitura completa além das filtradas.
Regra prática: Planeje os filtros que seus leitores usam, e a leitura completa, antes e depois de cada mudança de partição, e guarde as contagens junto ao registro do runbook. Se um filtro que planejava um arquivo passar a planejar muitos, a mudança quebrou a poda desse filtro, e você deve alterar a especificação ou o filtro antes da próxima carga sob ela.
Particionamento nos outros formatos
Nos outros dois formatos, a mesma mudança tem um custo diferente, embora as linhas lidas de volta sejam as mesmas nos três. O que muda são os arquivos e o plano. A tabela abaixo resume os três.
| Formato | Como a mudança é feita | Arquivos já escritos | O que verificar depois |
|---|---|---|---|
| Iceberg | Um bloco update_spec() |
Mantidos, e ainda sob a especificação antiga | Contagem de arquivos por especificação; contagens do plano |
| Delta Lake | Sobrescrita completa com schema_mode="overwrite" |
Escritos novamente em uma versão posterior; versão antiga mantida | Contagem de linhas; contagem de arquivos; colunas de partição da versão antiga |
| DuckLake | ALTER TABLE ... SET PARTITIONED BY |
Mantidos; a configuração se aplica às cargas seguintes | Contagem de arquivos após uma carga; a chave de partição |
Delta Lake particiona por colunas simples, e sua opção de partição recebe nomes de colunas, não expressões. O protocolo Delta Lake define partitionColumns como um array contendo os nomes das colunas pelas quais os dados são particionados. Uma coluna gerada pode calcular day ou hour dentro da tabela, mas isso eleva a versão do protocolo de escrita da tabela, por isso este livro calcula ambos no escritor. Um auxiliar, with_partition_columns, adiciona as duas colunas de texto a partir de hour_utc antes de cada escrita. A tabela começa particionada por day, e uma mudança para hour é recusada, a menos que a escrita seja uma sobrescrita completa que também substitua o esquema:
DeltaError: Generic error: Specified table partitioning does not match table partitioning: expected: ["day"], got: ["hour"]. To change partition columns, use full table overwrite with schema overwrite and no replaceWhere predicate.
Tente primeiro a mudança com um mode="overwrite" simples, e a biblioteca a recusa com esse erro. A mesma escrita com schema_mode="overwrite" então passa. Essa é a configuração que a API da biblioteca nas versões fixadas usa no lugar do antigo indicador overwrite_schema. As linhas são lidas para a memória antes de a sobrescrita começar, porque uma sobrescrita substitui todas as linhas que a tabela contém. Escrever as linhas de volta é a única forma de preservá-las.
1"""Change a Delta Lake table's partition columns from day to hour, which rewrites the table.23Read the error line from the plain overwrite first, then the version and row lines after the rewrite.4"""56import pyarrow.compute as pc7from deltalake import DeltaTable, write_deltalake89from lib.lakehouse import delta_file_count, new_warehouse, read_cut_hour, read_delta, safe_error101112def with_partition_columns(rows):13 """Add the day and hour columns that Delta partitions by. Delta partitions only by plain columns."""14 rows = rows.append_column("day", pc.strftime(rows["hour_utc"], format="%Y-%m-%d"))15 # %H is the 24-hour clock, zero-padded, so hour 04 is the string "04"16 return rows.append_column("hour", pc.strftime(rows["hour_utc"], format="%H"))171819def main():20 try:21 with new_warehouse() as wh:22 path = f"{wh.root}/delta/pageviews_hourly"23 for hour in range(3):24 write_deltalake(path, with_partition_columns(read_cut_hour(hour)), partition_by=["day"], mode="append")25 table = DeltaTable(path)26 print(f"partition columns before: {table.metadata().partition_columns}")27 print(f"version before: {table.version()}")28 print(f"data files before: {delta_file_count(table)}")2930 # read first, so the rows are in memory before the overwrite below writes them back31 rows = read_delta(path)32 try:33 # no schema_mode here, so the library refuses the change and the error is printed34 write_deltalake(path, rows, partition_by=["hour"], mode="overwrite")35 except Exception as exc:36 print(f"change without schema mode: {safe_error(exc, wh)}")3738 # schema_mode is what lets the partition columns change in a full overwrite39 write_deltalake(path, rows, partition_by=["hour"], mode="overwrite", schema_mode="overwrite")40 table = DeltaTable(path)41 print(f"partition columns after: {table.metadata().partition_columns}")42 print(f"version after: {table.version()}")43 print(f"data files after: {delta_file_count(table)}")44 print(f"rows after: {read_delta(path).num_rows}")4546 # version 2 is the last version before the rewrite; Delta counts versions from 047 old = DeltaTable(path, version=2)48 print(f"partition columns in version 2: {old.metadata().partition_columns}")49 print(f"rows in version 2: {read_delta(path, version=2).num_rows}")50 except Exception as exc:51 print(safe_error(exc))52 raise SystemExit(1)535455if __name__ == "__main__":56 main()
python delta-partition-overwrite.pypartition columns before: ['day']
version before: 2
data files before: 3
change without schema mode: DeltaError: Generic error: Specified table partitioning does not match table partitioning: expected: ["day"], got: ["hour"]. To change partition columns, use full table overwrite with schema overwrite and no replaceWhere predicate.
partition columns after: ['hour']
version after: 3
data files after: 3
rows after: 1499
partition columns in version 2: ['day']
rows in version 2: 1499
A reescrita move a tabela para uma nova versão e mantém suas linhas. As três cargas são as versões 0 a 2, então a tabela está na versão 2 antes da mudança e 3 depois da reescrita.
A nova versão contém as mesmas 1499 linhas em 3 arquivos, um para cada partição de hora, o que corresponde às três horas. A versão 2 ainda pode ser lida com read_delta, com sua partição day e 1499 linhas.
A mudança no Delta é uma reescrita dos arquivos atuais da tabela, não uma edição de metadados. A tabela aqui é pequena. Uma tabela grande precisa da mesma reescrita com custo próprio, então planeje-a como uma tarefa de manutenção com uma janela de leitura. Cada linha também é lida para a memória antes da escrita, então a reescrita precisa de espaço para a tabela inteira de uma só vez. Para uma tabela que não cabe, uma cópia para um novo local é o caminho mais seguro, e o capítulo 9 mostra como verificar essa cópia.
DuckLake armazena o particionamento como uma configuração da tabela em seu catálogo, e uma mudança se aplica apenas às cargas seguintes. A documentação do DuckLake diz que as chaves de particionamento de uma tabela afetam apenas os dados escritos após a mudança. Configure a tabela para particionar por hour(hour_utc), carregue mais uma hora e as contagens de arquivos antes e depois dessa carga mostram a regra em ação. O auxiliar anexa o catálogo com o inlining desativado, então cada carga escreve um arquivo de dados, e a contagem mostra o que cada carga fez.
1"""Set a DuckLake table's partitioning to hour, then load one more hour and count the files before and after it.23The files-kept line is the one to check: it counts the earlier files still listed after the hour load.4"""56from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, ducklake_file_count,7 ducklake_file_paths, new_warehouse, read_cut_hour, safe_error)8910def load(con, hour):11 con.register("batch", read_cut_hour(hour))12 con.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM batch")13 con.unregister("batch")141516def main():17 try:18 with new_warehouse() as wh:19 con = connect_ducklake(wh.con)20 # the helper leaves inlining off by default, so every load below writes one data file21 create_ducklake_table(con, wh.root)22 for hour in range(3): # hours 00 to 02, before the change23 load(con, hour)24 print(f"data files before the change: {ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE)}")25 before = ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE)2627 con.execute(f"ALTER TABLE {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SET PARTITIONED BY (hour(hour_utc))")28 load(con, 3) # hour 03, the first load after the change29 print(f"data files after one load under hour: {ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE)}")30 after = ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE)31 # the intersection is the earlier files still listed after the hour load32 print(f"files kept from before the change: {len(before & after)}")3334 # ordered by key index, so the keys print in a fixed order35 for key, transform in con.execute(36 "SELECT partition_key_index, transform FROM __ducklake_metadata_lake.ducklake_partition_column ORDER BY 1"37 ).fetchall():38 print(f"partition key {key}: transform {transform}")39 rows = con.execute(f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}").fetchall()40 print(f"rows in table: {rows[0][0]}") # count(*) returns one row with one value41 except Exception as exc:42 print(safe_error(exc))43 raise SystemExit(1)444546if __name__ == "__main__":47 main()
python ducklake-partition-alter.pydata files before the change: 3
data files after one load under hour: 4
files kept from before the change: 3
partition key 0: transform hour
rows in table: 1999
A tabela tinha 3 arquivos de dados antes da carga da hora e 4 depois dela, então a carga da hora escreveu um arquivo. Dos arquivos listados após essa carga, 3 já estavam listados antes dela. As três cargas anteriores não foram reescritas, o que é, na prática, o que a regra da documentação quer dizer. O catálogo lista uma chave de partição, com a transformação hour, e a tabela contém 1999 linhas.
Regra prática: No Iceberg e no DuckLake, uma mudança de partição é uma mudança de metadados. Os arquivos antigos permanecem no lugar e as cargas seguintes usam o particionamento definido pela mudança, então verifique as contagens de arquivos após a primeira carga. No Delta Lake, uma mudança de partição é uma sobrescrita completa que reescreve os arquivos atuais da tabela, então planeje-a como uma reescrita e verifique a contagem de linhas e a contagem de arquivos depois dela.
O que dá errado em produção
Uma mudança de partição raramente falha na própria mudança; o problema aparece nas cargas e nos planos posteriores.
Comece por um pacote ausente. Nas versões fixadas em a seção sobre a migração para partições por hora, as transformações de dia e de hora precisam de pyiceberg-core, e as transformações o importam quando gravam. Um ambiente que instala apenas pyiceberg pode criar a tabela e depois falha na primeira inserção sob uma transformação de tempo. O erro aparece na primeira carga agendada, não quando a especificação é alterada, e por isso a versão fixada deve estar no arquivo de requisitos, e não na memória de alguém sobre a instalação.
Em seguida, vem o excesso de partições. Um grão de partição mais fino do que os filtros precisam dá a cada consulta mais arquivos para abrir, e cada arquivo contém menos linhas. Cargas por hora de algumas centenas de linhas cada geram arquivos pequenos em termos absolutos. Isto é uma regra prática, não uma medição: o custo depende do seu armazenamento e do seu motor. A contagem de planos em a seção sobre o que uma consulta lê mostra quantos arquivos uma consulta abre em cada especificação. O sinal é a contagem de leituras completas que continua crescendo a cada carga enquanto as linhas por arquivo permanecem pequenas, e a correção é a compactação, que o capítulo 6 aborda, ou um grão mais grosso para as cargas seguintes.
A terceira é a chave de alta cardinalidade. Uma partição de identidade sobre page_title cria uma partição para cada título, e cada carga grava um arquivo para cada título que contém. A tabela aqui tem alguns milhares de linhas, mas uma tabela real de páginas tem muito mais títulos do que isso, e a quantidade de arquivos acompanharia os títulos, não o tempo. Particione por tempo, que os filtros usam, e deixe os títulos como uma coluna sobre a qual as consultas filtram.
Depois, há o julgamento da mudança pelo resultado. As linhas são as mesmas antes e depois de uma mudança de partição, por isso uma verificação que compara as linhas passa quer a mudança tenha feito algo útil, quer não. Os exemplos deste capítulo imprimem as linhas apenas para confirmar que nada foi perdido. São as contagens que mostram a mudança.
Por último, uma reescrita executada sobre uma tabela que os leitores usam. O exemplo de Delta deste capítulo roda isolado e não testa os leitores durante a gravação. Para uma tabela da qual os leitores dependem, recomendamos gravar a reescrita em uma cópia, verificar as contagens e as linhas da cópia e só então apontar os leitores para ela. O capítulo 9 usa a mesma verificação entre formatos. Recomendamos isto por critério; nenhum exemplo a mede.
Regra prática: Escolha o grão de partição a partir dos filtros que os seus leitores usam e do tamanho dos arquivos que você espera, não da frequência com que os dados chegam. Antes de executar uma mudança de partição em uma tabela que atende leitores, execute-a em uma cópia e compare as contagens de planos e o número de linhas dos dois lados.
Decisões tomadas neste capítulo
- Particionamos a tabela Iceberg pelas transformações day e hour de
hour_utc, e fixamospyiceberg-corejunto depyiceberg. As transformações mantêm a coluna de tempo como fonte da partição, de modo que um filtro sobre o tempo lê o mesmo campo que o gravador usou. Recomendamos isso para qualquer tabela que filtre por tempo. - Alteramos a tabela Delta Lake por uma sobrescrita completa com
schema_mode="overwrite", e gravamos suas colunas de partição como colunas de string simples,dayehour, calculadas pelo gravador. Aceitamos a reescrita, porque, nesta biblioteca, uma mudança de partição exige uma sobrescrita completa. - Contamos arquivos e planos pela listagem própria de cada biblioteca:
plan_files()para Iceberg,file_uris()para Delta Lake educklake_list_filespara DuckLake. Nenhum exemplo imprime um nome de arquivo, porque os nomes contêm um ID aleatório que muda a cada execução. - Desligamos a incorporação de dados em linha (inlining) do DuckLake em todos os exemplos que contam arquivos, como o capítulo 1 explica, para que uma contagem de arquivos seja uma contagem de arquivos de dados.
- Escolhemos a granularidade de hora a partir dos filtros dos painéis, que leem uma hora por vez, e não a partir da frequência com que as cargas chegam.
- Mostramos primeiro a falha do Delta e depois a correção, para que a configuração de schema seja explicada pelo erro que a exige.
- Imprimimos a chave de partição do DuckLake a partir da tabela de partições do catálogo, e não dos nomes de arquivo, para que a saída não mude quando os nomes mudarem.
- Mantemos os rótulos de campo e de especificação na saída e nunca imprimimos um ID de especificação, um ID de snapshot ou um nome de arquivo. IDs de snapshot e nomes de arquivo mudam de uma execução para outra, e um rótulo indica a qual época uma especificação pertence sem que o leitor precise decodificar o ID.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 20 de nov de 20264 de 4 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.