Adicionar e renomear colunas sem reescrever arquivos

Cerca de 22 minutos min de leitura, com 4 exemplos em 8 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 terminar este capítulo, você será capaz de adicionar uma coluna a uma tabela que já contém dados, renomear uma coluna no Iceberg sem reescrever seus arquivos de dados e explicar por que renomear uma coluna no Delta Lake é uma reescrita de toda a tabela.

Dois pedidos chegam a wiki.pageviews_hourly depois que as primeiras três horas são gravadas. A tabela guarda contagens horárias de visualizações de página de seis horas da Wikimedia, que o primeiro capítulo carrega, então cada mudança acontece em uma tabela que já contém dados. O primeiro pedido é uma coluna de linhagem: cada linha deve registrar qual carga horária a gravou, para que uma carga defeituosa possa ser rastreada até as suas linhas. A tabela precisa dessa coluna, e as linhas que ela já contém foram gravadas antes de a coluna existir. O segundo é uma correção de nome. Os painéis chamam a coluna de título article_title, enquanto a tabela a chama de page_title, o nome usado pelo dump. Para cada mudança, a pergunta é a mesma: o que acontece com os arquivos gravados antes dela?

Em princípio, uma mudança de esquema é uma mudança de metadados. Os arquivos de dados permanecem onde estão, e o formato registra as colunas adicionadas ou renomeadas em seus metadados. Se os arquivos antigos ainda são lidos corretamente depende de como o formato encontra uma coluna dentro de um arquivo. Um formato que encontra colunas pelo nome tem dificuldades quando um nome muda. Um formato que as encontra por algo que não muda não tem essa dificuldade. Este capítulo mostra qual dos dois tipos é cada formato, o que custa cada mudança e qual mudança a biblioteca Delta Lake fixada não consegue fazer.

As colunas são rastreadas por ID

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

Um arquivo de dados guarda valores para algumas colunas, e o esquema da tabela informa a qual coluna cada valor pertence. A forma simples de associá-los é pelo nome. Isso funciona até que um nome mude. O esquema passa então a citar uma coluna que o arquivo antigo não tem com esse nome, e o leitor precisa adivinhar a que pertencem os valores antigos.

Um leitor que associa pelo nome e não encontra coluna com o nome antigo tem duas opções ruins: falhar a consulta ou preencher a coluna com nulo sem avisar. A segunda é a falha mais silenciosa, e um painel pode exibi-la por semanas antes que alguém perceba. Consideramos o nulo silencioso a pior falha, o que é um juízo, não um resultado medido. Associar por identidade evita as duas, porque a coluna mantém sua identidade qualquer que seja o seu nome.

O Iceberg atribui a cada coluna um ID de campo inteiro no momento em que a coluna é criada, e associa as colunas por esse ID. O nome é um rótulo que pode mudar, e a especificação do Iceberg afirma que renomear um campo "deve mudar o nome, mas não o ID do campo" [1]. Quando um leitor abre um arquivo antigo, associa cada coluna pelo ID do campo. Se o arquivo não tiver valor para um campo, a regra de projeção da especificação verifica primeiro dois casos que não se aplicam aqui, um valor de partição por identidade e um mapeamento de nomes. Depois retorna o initial-default do campo, quando ele está definido, e nulo em todos os outros casos [1]. A especificação define initial-default para uma coluna adicionada com um valor padrão. Este capítulo não define nenhum, e assim uma coluna acrescentada é lida como nula em todas as linhas antigas.

Você pode ver os IDs por conta própria. O esquema de uma tabela Iceberg lista cada campo com o seu ID, e o exemplo da seção sobre renomeação mostra o ID de uma coluna antes e depois de uma renomeação. O ID é o valor a verificar quando você quer saber se uma renomeação manteve a identidade da coluna.

O Delta Lake parte de outro ponto. O esquema de sua tabela nomeia cada coluna, e o leitor associa pelo nome. O protocolo do Delta Lake define um recurso opcional de mapeamento de colunas que separa o nome nos arquivos do nome que o leitor vê: cada coluna recebe um nome físico guardado nos arquivos, e o nome usado pelo leitor é um nome de exibição que pode mudar sem tocar nos arquivos. O protocolo afirma que o mapeamento de colunas oferece suporte à "renomeação e remoção de colunas sem precisar reescrever todos os dados" [2]. Se uma determinada versão da biblioteca faz isso é outra questão. A seção sobre o Delta Lake responde a ela para a versão fixada.

Regra prática: espere que uma coluna Iceberg mantenha os seus dados após uma renomeação, porque o leitor associa pelo ID do campo. Espere que uma coluna do Delta Lake seja associada pelo nome, a menos que o mapeamento de colunas esteja ativado. Teste uma renomeação em uma cópia da tabela antes de depender dela, e leia os nomes das colunas depois.

Adicione load_batch depois de três horas

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

A primeira mudança é a que o caso exige primeiro: uma coluna que não existe nos arquivos já gravados. Em um pipeline, isso acontece em um dia comum. O pipeline passa a carimbar cada carga com o seu número, e a tabela já contém linhas anteriores ao carimbo. A configuração grava as três primeiras horas, cada uma como um commit próprio, de modo que a tabela tem três snapshots e três arquivos de dados. Um snapshot do Iceberg é o estado da tabela após um commit que altera dados. Cada append neste capítulo adiciona um, e uma mudança de schema não adiciona nenhum.

No pyiceberg 0.12.0, você adiciona uma coluna dentro de uma atualização de schema. A chamada recebe o nome e o tipo, e a tabela atribui o ID do campo:

with table.update_schema() as update:
    update.add_column("load_batch", IntegerType())

Para ver o que a adição faz com as linhas já gravadas em disco, faça o commit das horas 00 a 02, adicione a coluna e anexe as horas 03 a 05, cada uma carimbada com o seu número de hora em load_batch. Contar as linhas por hora do dia divide a tabela no momento da adição: as horas 00 a 02 foram gravadas antes dela, e as horas 03 a 05 depois. Cada hora é uma gravação, de modo que a divisão também é a divisão por carga.

add-column-to-existing-files.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Adds load_batch to a table that already holds three hours, in Iceberg and then in Delta Lake, and counts the nulls on each side of the add.Read the four "with load_batch null" lines, which show the rows before the add and the rows after it in each format."""import pyarrow as pafrom deltalake import DeltaTable, write_deltalakefrom deltalake.schema import Field, PrimitiveTypefrom pyiceberg.types import IntegerTypefrom lib.lakehouse import ICEBERG_ID, delta_file_count, iceberg_file_count, new_warehouse, read_cut_hour, read_delta, split_nullsdef stamp(rows, hour):    """Return one hourly load with load_batch set to that load's hour number."""    # int32 is the width IntegerType stores, so the Arrow column matches the Iceberg field    return rows.append_column("load_batch", pa.array([hour] * rows.num_rows, type=pa.int32()))with new_warehouse() as wh:    # the schema comes from hour 0, which has no load_batch yet    table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)    for hour in range(3):  # hours 00 to 02, each one commit, all written before the add        table.append(read_cut_hour(hour))    print(f"iceberg snapshots before the add: {len(table.snapshots())}")    print(f"iceberg data files before the add: {iceberg_file_count(table)}")    with table.update_schema() as update:        update.add_column("load_batch", IntegerType())    print(f"iceberg snapshots after the add: {len(table.snapshots())}")    print(f"iceberg data files after the add: {iceberg_file_count(table)}")    for hour in range(3, 6):  # hours 03 to 05, written after the add        table.append(stamp(read_cut_hour(hour), hour))    iceberg_rows = table.scan().to_arrow()    print(f"iceberg rows in the table: {iceberg_rows.num_rows}")    # the split is at 3, the first hour written after the add    split_nulls(wh.con, iceberg_rows, "iceberg", "load_batch", 3, sides=("written before the add", "written after the add"))    path = f"{wh.root}/delta/pageviews_hourly"    for hour in range(3):  # hours 00 to 02, appended as three versions before the add        write_deltalake(path, read_cut_hour(hour), mode="append")    print(f"delta version before the add: {DeltaTable(path).version()}")    print(f"delta data files before the add: {delta_file_count(DeltaTable(path))}")    DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])    print(f"delta version after the add: {DeltaTable(path).version()}")    print(f"delta data files after the add: {delta_file_count(DeltaTable(path))}")    for hour in range(3, 6):  # hours 03 to 05, written after the add        write_deltalake(path, stamp(read_cut_hour(hour), hour), mode="append")    delta_rows = read_delta(path)    print(f"delta rows in the table: {delta_rows.num_rows}")    # the same split as the Iceberg half, at 3    split_nulls(wh.con, delta_rows, "delta", "load_batch", 3, sides=("written before the add", "written after the add"))
Saídapython add-column-to-existing-files.py
iceberg snapshots before the add: 3
iceberg data files before the add: 3
iceberg snapshots after the add: 3
iceberg data files after the add: 3
iceberg rows in the table: 2999
iceberg rows written before the add: 1499
iceberg rows written before the add with load_batch null: 1499
iceberg rows written after the add: 1500
iceberg rows written after the add with load_batch null: 0
delta version before the add: 2
delta data files before the add: 3
delta version after the add: 3
delta data files after the add: 3
delta rows in the table: 2999
delta rows written before the add: 1499
delta rows written before the add with load_batch null: 1499
delta rows written after the add: 1500
delta rows written after the add with load_batch null: 0

A adição altera os metadados e nenhum arquivo de dados. A contagem de snapshots permanece em 3 após a mudança de schema, e a tabela mantém os seus 3 arquivos de dados.

As 1499 linhas gravadas antes da adição leem todas null para load_batch, e 0 das 1500 linhas gravadas depois dela são null. A tabela tem 2999 linhas no total.

No Delta Lake, na versão deltalake 1.6.6, você adiciona uma coluna pelo seu objeto alter. A chamada recebe um campo, e a versão da tabela aumenta em um:

DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])

A metade Delta segue a mesma sequência: três horas iniciais como três appends, a adição e depois as horas 03 a 05. A primeira gravação é a versão 0, e todo número de versão que este capítulo imprime é o número real do Delta. A versão passa de 2 para 3, e a tabela mantém os seus 3 arquivos de dados.

Antes da adição há 1499 linhas, todas null para load_batch. Depois que os três appends posteriores entram, a tabela tem 2999 linhas, e 0 das 1500 linhas gravadas após a adição são null. Esta tabela não tem mapeamento de colunas, um ponto ao qual a seção de renomeação do Delta Lake retorna.

Os dois formatos dão o mesmo resultado para este caso. As linhas antigas permanecem como foram gravadas, e a coluna é lida como null para elas. O gravador não precisou tocar em nenhum arquivo antigo. As duas metades têm as mesmas contagens de linhas e as mesmas contagens de nulos, de modo que uma divergência entre elas apontaria para um leitor, e não para os dados.

Regra prática: Adicione uma coluna com a chamada própria do formato, e nunca reescrevendo os arquivos. Espere que as linhas gravadas antes da adição leiam null para a coluna, e verifique se isso acontece.

Arquivos antigos lidos como nulos

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

Um nulo em uma coluna adicionada pode parecer dado ausente, e quem o vê pode supor que os arquivos antigos estão errados. Não estão. Os arquivos antigos guardam os valores que o pipeline escreveu, e a coluna que lhes falta é preenchida na leitura. A regra que você segue é a descrita na seção sobre colunas: sem initial-default, a ausência de valor para o campo significa nulo.

Por isso, a contagem de nulos é uma verificação útil. Conte os nulos por hora, como faz o exemplo de adição, e eles mostram o padrão esperado: toda linha escrita antes da adição é nula, e nenhuma linha escrita depois dela é. O Iceberg tem 1499 nulos entre suas 1499 linhas anteriores, e o Delta Lake tem 1499 entre as suas 1499.

Se uma contagem fugir desse padrão, um escritor enviou um conjunto de colunas diferente ou enviou a coluna com nulos, e a causa está no pipeline, não no formato. Examine o escritor responsável pelas linhas que quebram o padrão antes de consultar a coluna, pois uma consulta sobre uma coluna parcialmente nula retornará uma resposta que parece razoável.

Regra prática: Após uma adição, conte os nulos na coluna adicionada por hora do dia, em que cada hora corresponde a uma escrita. As linhas escritas antes da adição devem ser nulas, e as escritas depois dela não devem. Qualquer outro padrão significa que um escritor enviou um conjunto de colunas diferente ou enviou nulos na coluna, então encontre esse escritor antes de confiar na coluna.

Renomeie uma coluna pelo seu ID sem reescrever arquivos

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

Com o ID do campo definido, renomear uma coluna no Iceberg é uma única chamada. A chamada altera o nome que o esquema informa e mantém o ID:

with table.update_schema() as update:
    update.rename_column("page_title", "article_title")

Para verificar que o ID se mantém, grave três horas, leia o ID do campo de page_title, renomeie a coluna e leia o ID novamente. O exemplo também conta os arquivos de dados nos dois momentos e consulta o DuckDB com o novo nome.

rename-by-id.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Renames a column in an Iceberg table and reads the old files back under the new name.Read the field ID lines, the data file lines and the non-null count, which show what the rename kept."""import pyarrow as pafrom lib.lakehouse import (    ICEBERG_ID,    iceberg_file_count,    new_warehouse,    read_cut_hour,    scan_arrow,    snapshot_labels,    sql_rows,)with new_warehouse() as wh:    table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)    for hour in range(3):        table.append(read_cut_hour(hour))    before = table.schema().find_field("page_title").field_id  # the ID is what the reader matches on, not the name    print(f"page_title field ID before the rename: {before}")    print(f"data files before the rename: {iceberg_file_count(table)}")    with table.update_schema() as update:        update.rename_column("page_title", "article_title")    print(f"article_title field ID after the rename: {table.schema().find_field('article_title').field_id}")    print(f"data files after the rename: {iceberg_file_count(table)}")    rows = scan_arrow(table)    print(f"rows: {rows.num_rows}")    # count(column) leaves out nulls, so this counts the rows that have a value under the new name    count = sql_rows(wh.con, "SELECT count(article_title) FROM t", t=rows)[0][0]    print(f"article_title not null: {count}")    labels = snapshot_labels([snapshot.snapshot_id for snapshot in table.snapshots()])    first = table.snapshots()[0].snapshot_id  # the first snapshot, written before the rename    print(f"{labels[first]} columns: {', '.join(scan_arrow(table, snapshot_id=first).column_names)}")
Saídapython rename-by-id.py
page_title field ID before the rename: 3
data files before the rename: 3
article_title field ID after the rename: 3
data files after the rename: 3
rows: 1499
article_title not null: 1499
snapshot 1 columns: hour_utc, domain_code, page_title, views, response_bytes

O renomeio mantém o ID do campo. page_title tem o ID 3 antes da chamada, e article_title tem o ID 3 depois dela.

A contagem de arquivos de dados é 3 antes da chamada e 3 depois, portanto nenhum arquivo foi reescrito. A consulta ao DuckDB conta 1499 valores não nulos de article_title em 1499 linhas. Todas as linhas são contadas, inclusive as linhas gravadas sob page_title, porque o leitor associa os arquivos pelo ID e os lê com o novo nome.

Os painéis precisam do nome, e a tabela não precisa ser reescrita para fornecê-lo. Os dados permanecem como foram gravados, e a próxima leitura vê a coluna renomeada. A execução também imprime as colunas do primeiro snapshot, que são hour_utc, domain_code, page_title, views e response_bytes. Um snapshot é lido com o esquema com que foi gravado, então um snapshot mais antigo ainda informa o nome antigo. O capítulo 2 trata da leitura de snapshots antigos em geral, e o ponto aqui é mais restrito: um renomeio não alcança o histórico.

A comparação de custos é o que torna esta a escolha certa para o Iceberg. Um renomeio que mantém o ID toca apenas nos metadados, então seu custo não cresce com o tamanho da tabela. O mesmo renomeio feito por cópia da tabela custa uma leitura e uma escrita de cada linha. A seção sobre Delta Lake mostra o que essa cópia custa nesse formato.

Regra prática: Renomeie uma coluna do Iceberg quando o nome estiver errado, e verifique o ID do campo antes e depois da chamada. O ID do campo deve ser o mesmo, e a contagem de arquivos de dados não pode mudar. Informe a todos os leitores da tabela sobre o renomeio, porque o esquema atual tem apenas article_title, e um snapshot anterior ainda tem page_title.

Delta Lake não tem renomeação nesta versão fixada

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

A mesma renomeação no Delta Lake não tem chamada nesta versão fixada. O objeto de alteração de tabela do Delta Lake não tem método de renomeação no deltalake 1.6.6, e seus métodos estão listados no pacote [3]. O que parece uma renomeação é set_column_metadata, porque recebe um dicionário de metadados de campo, e nada impede você de passar uma chave name. A chamada retorna sem erro quando você passa name. Ela não renomeia nada em nenhuma tabela, com ou sem mapeamento de colunas, e essa é a armadilha que esta seção mostra.

A armadilha cria uma tabela com mapeamento de colunas ativado, que é o caminho do protocolo para uma renomeação, e então envia a chamada:

DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})
delta-rename-trap.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Calls set_column_metadata with a name key on a Delta Lake table with column mapping on, then reads the names back and queriesunder the new name. The columns read back line and the binder error are the lines to read."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_delta, safe_error, sql_rowswith new_warehouse() as wh:    path = f"{wh.root}/delta/pageviews_hourly"    # column mapping on: the protocol's route to a rename, which this release does not offer as a call    write_deltalake(path, read_cut_hour(0),                    configuration={"delta.columnMapping.mode": "name"})    print(f"version before the rename: {DeltaTable(path).version()}")    # the call raises nothing and writes a commit, so the names read back below are the only check    DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})    print("set_column_metadata returned")    table = DeltaTable(path)    print(f"version after the rename: {table.version()}")    page = next(field for field in table.schema().fields if field.name == "page_title")    # the name key the call wrote into the field's metadata, which the reader does not use for the column name    print(f"name in page_title metadata after the rename: {page.metadata['name']}")    print(f"columns read back: {', '.join(read_delta(path).column_names)}")    try:        sql_rows(wh.con, "SELECT article_title FROM t", t=read_delta(path))    except Exception as exc:        print(safe_error(exc, wh))
Saídapython delta-rename-trap.py
version before the rename: 0
set_column_metadata returned
version after the rename: 1
name in page_title metadata after the rename: article_title
columns read back: hour_utc, domain_code, page_title, views, response_bytes
BinderException: Binder Error: Referenced column "article_title" not found in FROM clause!
Candidate bindings: "page_title", "domain_code", "hour_utc", "views", "response_bytes"

LINE 1: SELECT article_title FROM t
               ^^^^^^^^^^^^^

A chamada retorna, e a versão da tabela passa de 0 para 1, o que mostra que a biblioteca gravou um commit. A chave name está nos metadados do campo. A coluna continua se chamando page_title: os nomes lidos de volta pela biblioteca são hour_utc, domain_code, page_title, views e response_bytes. A consulta DuckDB que pede article_title falha com um BinderException, e o erro lista page_title entre as colunas que ele poderia vincular.

A armadilha está em que a chamada parece uma renomeação e funciona como uma. Nada no valor retornado indica que o nome não mudou, por isso só a leitura dos nomes mostra a verdade.

O mapeamento de colunas também não dá renomeação nesta versão fixada. A tabela da armadilha tem delta.columnMapping.mode definido como name, e a chamada ainda não altera nenhum nome. A seção de mapeamento de colunas do protocolo descreve uma renomeação [2], mas o deltalake 1.6.6 não tem chamada que a execute.

delta-rename-by-rewrite.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Renames a Delta Lake column by overwriting the table with renamed data and schema, then reads the version before the rewrite back.Compare the two columns lines: the version before the rewrite, and the version the rewrite makes."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_deltawith new_warehouse() as wh:    path = f"{wh.root}/delta/pageviews_hourly"    for hour in range(3):        write_deltalake(path, read_cut_hour(hour), mode="append")    print(f"data files before the rewrite: {len(DeltaTable(path).file_uris())}")    before = DeltaTable(path).version()  # read first, so the old version can be read back after the rewrite    print(f"version before the rewrite: {before}")    print(f"columns before the rewrite: {', '.join(read_delta(path, version=before).column_names)}")    # the new names, in the table's column order: only the third one changes    renamed = read_delta(path).rename_columns(["hour_utc", "domain_code", "article_title", "views", "response_bytes"])    # replace the data and the schema together, in one commit, so readers of the new version see both at once    write_deltalake(path, renamed, mode="overwrite", schema_mode="overwrite")    print(f"data files after the rewrite: {len(DeltaTable(path).file_uris())}")    after = DeltaTable(path).version()    print(f"version after the rewrite: {after}")    print(f"columns after the rewrite: {', '.join(read_delta(path).column_names)}")    print(f"rows after the rewrite: {read_delta(path).num_rows}")
Saídapython delta-rename-by-rewrite.py
data files before the rewrite: 3
version before the rewrite: 2
columns before the rewrite: hour_utc, domain_code, page_title, views, response_bytes
data files after the rewrite: 1
version after the rewrite: 3
columns after the rewrite: hour_utc, domain_code, article_title, views, response_bytes
rows after the rewrite: 1499

Uma reescrita é o caminho para obter o nome nesta versão fixada. O exemplo de reescrita lê a tabela inteira pela biblioteca, renomeia a coluna em memória e grava o resultado com mode="overwrite" e schema_mode="overwrite", que substituem os dados e o esquema juntos. A tabela tinha 3 arquivos de dados antes da reescrita e passa a ter 1 depois dela. A reescrita cria a versão 3, que lê article_title, e nela há 1499 linhas.

A reescrita custa o tamanho da tabela, porque cada linha é lida e gravada novamente. A tabela aqui é pequena, mas uma tabela de produção que tem milhões de linhas paga o mesmo custo por linha, por isso uma equipe deve planejar a reescrita como uma tarefa própria. A versão anterior à reescrita, 2, ainda lê page_title, o que o exemplo também imprime. Portanto, a reescrita altera apenas a versão atual, e as versões antigas mantêm os nomes com que foram gravadas. Antes de executá-la, liste os leitores que pedem a coluna pelo nome. A troca acontece em um único commit, então todos os leitores da versão atual mudam no mesmo momento, enquanto uma tarefa que fixa uma versão antiga mantém o nome antigo. Mova essas tarefas junto com os leitores e registre o número da versão substituída pela reescrita até que elas tenham sido movidas.

Regra prática: Escolha os nomes de colunas do Delta Lake quando a tabela for criada, porque, nesta versão fixada, uma renomeação posterior é uma reescrita de toda a tabela. Não use set_column_metadata para renomear uma coluna: ele altera a versão e os metadados, e a coluna mantém o nome. Após qualquer mudança de esquema, leia de volta os nomes das colunas pela biblioteca, como faz o exemplo da armadilha, e confira-os antes que uma consulta dependa deles.

O que dá errado em produção

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

Mudanças de esquema falham em silêncio com mais frequência do que falham de forma explícita, e cada falha descrita abaixo tem um sinal que você pode observar.

Comece pela renomeação sem efeito. Uma chamada de set_column_metadata é bem-sucedida, um commit aparece no histórico, e a coluna mantém o nome antigo. A falha aparece na primeira consulta que usa article_title: a consulta no DuckDB falha com um BinderException. Um job agendado que executa essa consulta falha na primeira execução após a mudança, de modo que o erro aparece perto da sua causa.

Em seguida vem o nome desatualizado no histórico. Uma reescrita dá à versão atual o nome article_title, mas as versões anteriores mantêm os nomes com que foram escritas, e o exemplo de reescrita mostra isso: a versão 2 ainda lê page_title. Um snapshot do Iceberg faz o mesmo: o primeiro snapshot ainda informa page_title. Uma consulta que lê uma versão ou um snapshot anterior por article_title não encontra essa coluna. Leituras por número de versão ou de snapshot exigem os nomes que estavam em vigor naquele momento; por isso, um job que fixa um número de versão também fixa o seu esquema.

Em terceiro lugar, o null que parece dado ausente. Uma coluna adicionada aparece como null em todas as linhas escritas antes da adição. A contagem de nulls nessa coluna está correta, e ela só é uma falha quando cai fora do padrão de antes e depois mostrado no exemplo de adição. Conte os nulls por hora, como faz o exemplo de adição, e investigue qualquer linha que quebre o padrão.

Por último, a mudança de esquema que não aparece na lista de snapshots. As operações de adição e de renomeação no Iceberg não alteraram a contagem de snapshots, nem a contagem de arquivos. Uma ferramenta que procura mudanças de esquema contando snapshots vai deixá-las passar. Compare o próprio esquema, por ID de campo e por nome, quando precisar saber o que mudou.

Regra prática: Após qualquer mudança de esquema, faça três coisas antes que qualquer consulta a jusante seja executada: leia de volta os nomes das colunas pela biblioteca; conte os nulls em cada coluna adicionada por hora, em que cada hora corresponde a uma escrita; e compare o esquema, e não a contagem de snapshots, com o que a mudança deveria fazer.

Decisões tomadas neste capítulo

A tabela desta seção coloca os dois formatos lado a lado para as mudanças deste capítulo. Cada célula vem de um exemplo deste capítulo.

Mudança Iceberg Delta Lake
Adicionar uma coluna Funciona. Linhas antigas são lidas como null, e a contagem de snapshots permanece em 3 Funciona. Linhas antigas são lidas como null, e a versão sobe em uma unidade
Renomear uma coluna Funciona. O ID do campo permanece o mesmo, e nenhum arquivo de dados é reescrito Não há chamada de renomeação. set_column_metadata grava a operação e não altera nenhum nome; é uma reescrita que aplica o nome
Ler um snapshot ou uma versão anterior Mostra o nome anterior Mostra o nome anterior
  • Adicione uma coluna a uma tabela que já contém dados, nos dois formatos. Linhas antigas a leem como null, e o exemplo de adição mostra as contagens por hora que confirmam esse padrão. Recomendamos isso em vez de qualquer cópia da tabela, porque não grava nenhum arquivo antigo.
  • Renomeie uma coluna do Iceberg com rename_column, e verifique se o ID do campo é o mesmo antes e depois. Recomendamos essa operação para qualquer coluna do Iceberg cujo nome esteja errado, porque o custo dela não depende do tamanho da tabela.
  • Escolha os nomes das colunas do Delta Lake quando a tabela for criada. Na versão fixada, uma renomeação ali é uma reescrita da tabela inteira, e esse é o custo a planejar quando um nome estiver errado.
  • Não renomeie uma coluna do Delta Lake com set_column_metadata. A chamada é bem-sucedida e não altera nada no nome.
  • Não conte com o mapeamento de colunas para renomear nesta versão fixada. A biblioteca não tem chamada que faça isso, portanto ativar o mapeamento não traz nenhuma renomeação.
  • Leia os nomes das colunas de volta após cada mudança de esquema, nos dois formatos, antes que alguma consulta dependa deles.

Esta parte ainda não foi traduzida, por isso está em inglês.

Sources

Última alteração na edição 2026.11.7
  1. Apache Iceberg Table Spec, Schema Evolution (Column Projection), https://iceberg.apache.org/spec/, read Nov 6, 2026. Quoted: "Renaming an existing field must change the name, but not the field ID." The null rule, which the text paraphrases, is in the same section.
  2. Delta Transaction Log Protocol, Column Mapping section, tag v4.4.1, https://raw.githubusercontent.com/delta-io/delta/v4.4.1/PROTOCOL.md, read Nov 6, 2026. Quoted: "the renaming and dropping of columns without having to rewrite all the data."
  3. deltalake 1.6.6, the methods of DeltaTable.alter in the installed package: add_columns, add_constraint, add_feature, drop_column_not_null, drop_constraint, set_column_metadata, set_table_description, set_table_name and set_table_properties. None renames a column. To list them, run dir(DeltaTable(path).alter).

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.

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 3 de 10: Adicionar e renomear colunas sem reescrever arquivos

  1. As colunas são rastreadas por ID
  2. Adicione load_batch depois de três horas
  3. Arquivos antigos lidos como nulos
  4. Renomeie uma coluna pelo seu ID sem reescrever arquivos
  5. Delta Lake não tem renomeação nesta versão fixada
  6. O que dá errado em produção
  7. Decisões tomadas neste capítulo
  8. Sources

Voltar ao topoTodos os capítulos