Mover uma tabela entre formatos e verificar a cópia

Cerca de 23 minutos min de leitura, com 4 exemplos em 7 seções.

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

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.10. Leia o original

Ao final deste capítulo, você será capaz de copiar uma tabela de um formato para outro e verificar se a cópia mantém as mesmas linhas. Você também saberá identificar o que a cópia deixa para trás e decidir quais perdas aceitar e quais devem interromper a mudança.

Os analistas querem a tabela pageviews no DuckLake, onde consultam um arquivo de catálogo por meio do DuckDB. A tabela pageviews, wiki.pageviews_hourly, está no Apache Iceberg desde o capítulo 1. Outra equipe mantém suas tabelas no Delta Lake e quer as mesmas linhas no Iceberg. Nas duas mudanças, a origem permanece onde está, e a mudança é uma cópia para uma nova tabela. Uma cópia é uma gravação única, e a maior parte do trabalho está nas verificações ao redor dela. O capítulo faz as duas cópias e, em seguida, acrescenta as verificações que detectam perdas silenciosas.

Os exemplos deste capítulo fixam 0.12.0 para o pyiceberg, 1.6.6 para o deltalake e 2.0.0 para o DuckDB, que também executa o DuckLake. Cada exemplo de cópia cria sua própria origem pequena em um warehouse temporário, a partir das mesmas três horas do recorte de pageviews. São 1499 linhas.

O que uma cópia mantém e o que perde

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

Uma cópia lê as linhas de uma tabela em um determinado momento e as grava em outra tabela, em outro formato. Cada biblioteca de destino grava seus próprios arquivos de dados, seus próprios metadados e seu próprio histórico. O que sobrevive à viagem é aquilo que os dois lados conseguem representar: as linhas e as colunas cujos tipos ambos os lados suportam. Todo o resto permanece com a origem ou precisa ser configurado de novo no destino, manualmente.

As perdas são mais fáceis de ver em forma de tabela. Cada linha nomeia uma parte da tabela, o que a cópia faz com ela e onde este capítulo mostra o resultado.

Parte da tabela Após a cópia Onde este capítulo mostra
Linhas e seus valores Mantidos A verificação do digest
Nomes e tipos das colunas Mantidos onde ambos os formatos têm o tipo A seção sobre Delta Lake
Histórico de commits Perdido. A cópia inicia um histórico próprio Ambas as seções sobre cópia
Especificação de partição Perdida, a menos que seja definida no destino A seção sobre DuckLake
Timestamps abaixo de um microssegundo Depende do formato: rejeitados, truncados ou mantidos A seção sobre timestamps

O histórico é uma perda que os leitores frequentemente não percebem. O Iceberg registra as mudanças como snapshots, e o Delta Lake registra cada commit como uma versão. O capítulo sobre snapshots e viagem no tempo mostrou como o leitor os utiliza. Uma cópia inicia um novo histórico no destino, de modo que o histórico do destino começa na cópia. A origem mantém seu próprio histórico enquanto você a mantiver. Nada na cópia faz referência a ele.

Uma cópia também é diferente do registro. Um arquivo de metadados registrado torna uma tabela visível em um segundo catálogo sem tocar em seus arquivos, de modo que os dois catálogos leem os mesmos dados. Uma cópia grava novos arquivos e deixa a origem intacta, o que significa que duas tabelas passam a receber escritas e podem divergir. Escolha a cópia quando o destino precisar ser dono de seus arquivos e de seu histórico. Escolha o registro quando os dois catálogos deverem compartilhar um único conjunto de arquivos, e aceite que os arquivos compartilhados precisam permanecer no lugar.

As linhas sobrevivem porque a cópia move valores, não arquivos. Uma cópia não move arquivos de dados. Ela lê valores de uma tabela e grava novos arquivos Parquet para a outra. É por isso que os nomes e a quantidade de arquivos diferem entre uma origem e sua cópia, e por que comparar nomes ou quantidades de arquivos não serve para verificar a cópia. A verificação precisa comparar as linhas.

Regra prática: Antes de uma cópia, liste o que a origem contém e que o destino não vai manter: seu histórico, sua especificação de partição e qualquer valor mais fino do que o destino consegue armazenar. Dê a cada item uma única decisão: aceitar a perda, definir a propriedade manualmente no destino ou interromper a movimentação. O runbook deve nomear cada decisão.

Copie a tabela pageviews para o DuckLake

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

A cópia lê a tabela Iceberg com scan_arrow, e depois entrega essas linhas ao DuckLake. O DuckLake cria uma tabela vazia com as colunas delas, define nela a especificação de partição e, em seguida, insere as linhas com INSERT ... SELECT. O Arrow é a ponte porque cada lado mantém a sua própria biblioteca. O pyiceberg lê a origem, e o DuckDB escreve a tabela do DuckLake por meio da sua própria extensão ducklake. Nenhum dos lados lê os arquivos do outro. O capítulo sobre o catálogo mostrou como o catálogo do DuckLake é anexado, e o auxiliar deste capítulo o anexa da mesma forma.

A origem é particionada pela hora de hour_utc, que é o layout a que chega a migração de partições diárias para horárias. Aqui, o pyiceberg constrói essa origem com a especificação horária e acrescenta três horas, cada uma com um commit:

iceberg-to-ducklake-copy.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Copy an Iceberg table into DuckLake through Arrow, then print what the copy kept of the layout and the history.The point rests on the copy partition transforms and copy files per partition lines, which show whether thelayout arrived with the rows, and on the copy snapshot lines, which show the history starting at the copy."""from pyiceberg.partitioning import PartitionField, PartitionSpecfrom pyiceberg.transforms import HourTransformfrom lib.lakehouse import (copy_to_ducklake, create_iceberg_table, ducklake_files_by_partition, ducklake_partition_transforms,                           new_warehouse, read_cut_hour, safe_error, scan_arrow, TABLE)def main():    try:        with new_warehouse() as wh:            # source_id 1 is the field ID of hour_utc in the table lib creates            spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=HourTransform(), name="ts_hour"))            table = create_iceberg_table(wh, partition_spec=spec)            for hour in range(3):                table.append(read_cut_hour(hour))            arrow = scan_arrow(table)            print(f"source rows: {arrow.num_rows}")            print(f"source snapshots: {len(table.metadata.snapshots)}")            for field in table.spec().fields:                print(f"source partition field: {field.name}")            # the helper creates the copy empty, sets this spec with ALTER, and only then inserts the rows            target = copy_to_ducklake(wh, arrow, partition_by="hour(hour_utc)")            print(f"copy rows: {wh.con.execute(f'SELECT count(*) FROM {target}').fetchall()[0][0]}")            # current=True keeps only the spec still in force; an earlier spec would otherwise be listed too            print(f"copy partition transforms: {ducklake_partition_transforms(wh.con, table=TABLE, current=True)}")            # one (partition value, files, rows) tuple per partition, in value order            files = ducklake_files_by_partition(wh.con, "lake", TABLE)            print(f"copy partition values: {[value for value, _, _ in files]}")            print(f"copy files per partition: {[count for _, count, _ in files]}")            print(f"copy rows per partition: {[int(rows) for _, _, rows in files]}")            changes = wh.con.execute("SELECT changes FROM ducklake_snapshots('lake') ORDER BY snapshot_id").fetchall()            # labels start at 1, so label N is the snapshot whose snapshot_id is N-1            for number, (change,) in enumerate(changes, start=1):                print(f"copy snapshot {number}: {', '.join(sorted(change))}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython iceberg-to-ducklake-copy.py
source rows: 1499
source snapshots: 3
source partition field: ts_hour
copy rows: 1499
copy partition transforms: ['hour']
copy partition values: ['0', '1', '2']
copy files per partition: [1, 1, 1]
copy rows per partition: [499, 500, 500]
copy snapshot 1: schemas_created
copy snapshot 2: schemas_created
copy snapshot 3: tables_created
copy snapshot 4: tables_altered
copy snapshot 5: tables_inserted_into

O auxiliar scan_arrow lê a origem no seu snapshot atual e devolve todas as linhas desse snapshot como uma única tabela Arrow. A cópia, portanto, contém as linhas de um único momento, o último commit que a leitura viu. Escritores que fazem commit depois da leitura não estão na cópia, e nada na cópia indica isso. Commits que chegam depois da leitura da cópia e nunca a alcançam são o problema da troca, ao qual a seção de produção retorna.

Duas perguntas decidem a cópia: as linhas e o layout chegaram, e que histórico veio com elas? A saída responde às duas.

Primeiro, a origem. Ela imprime o número de linhas, a quantidade de snapshots e os campos de partição. A origem tem 3 snapshots, um para cada acréscimo, e um campo de partição, ts_hour, uma transformação de hora sobre hour_utc.

Depois, o número de linhas da cópia, que é 1499. Ele é igual ao da origem. É uma primeira verificação útil, mas, como explica a seção sobre resumos abaixo, não basta por si só.

Uma cópia pode perder o seu layout sem nenhum erro, por isso a ordem das instruções importa. O auxiliar cria a cópia como tabela vazia, executa ALTER TABLE ... SET PARTITIONED BY (hour(hour_utc)) nela e só então insere as linhas. A documentação de particionamento do DuckLake diz que as chaves de partição "afetam apenas os dados novos gravados na tabela", de modo que um ALTER executado depois de as linhas já estarem no lugar as deixaria sem partição. O auxiliar mantém apenas a especificação ainda em vigor, e ela lista uma transformação, hour. A lista diz o que foi dado à cópia. Os arquivos dizem o que ela contém: a cópia grava [1, 1, 1] arquivos, e as linhas se dividem entre eles como [499, 500, 500]. Uma cópia feita em uma única instrução não carrega especificação de partição, então a sua lista fica vazia e as suas linhas ficam em arquivos sem partição. As linhas estão todas lá de qualquer modo, por isso a verificação precisa olhar o layout.

A lista de partições lê a tabela de catálogo ducklake_partition_column, conforme define a especificação do DuckLake, pelo banco de metadados anexado. Nenhuma função pública a devolve nesta versão fixada.

Por fim, a lista de snapshots mostra o histórico da cópia. Cada linha dá o número de um snapshot e as mudanças que ele fez. Os rótulos contam cada snapshot que o DuckLake registra, inclusive os da configuração, como no capítulo 2. Os dois primeiros snapshots criam o esquema padrão e o esquema wiki. O terceiro cria a tabela vazia, o quarto define a sua especificação de partição, e o quinto grava as linhas na tabela já particionada. Os três acréscimos horários da origem não aparecem. O histórico da cópia começa na sua própria criação, então a viagem no tempo sobre a cópia alcança apenas até esse ponto. Para ler a origem como estava depois da primeira hora, você ainda precisa da tabela Iceberg.

O auxiliar de anexação também define DATA_INLINING_ROW_LIMIT como 0, de modo que as linhas copiadas são gravadas como arquivos Parquet, e as contagens acima são desses arquivos.

Regra prática: Copie por meio do Arrow com o gravador do próprio destino. Crie o destino vazio, defina a sua especificação de partição com um ALTER e só então insira as linhas. Imprima a lista de partições do destino e a quantidade de arquivos por partição. Leia os snapshots da cópia como o histórico próprio da cópia, e mantenha a origem até que as verificações das duas últimas seções tenham sido aprovadas.

Copie a tabela Delta para uma tabela pyiceberg

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

A fonte Delta é construída da forma como o pipeline de uma equipe a construiria: três appends com deltalake, um por hora. Os três appends são as versões 0, 1 e 2. A cópia lê as linhas atuais com read_delta e as acrescenta a uma tabela Iceberg criada com o esquema de destino:

delta-to-iceberg-copy.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Copy a Delta Lake table into Iceberg through Arrow, then compare the copy with its source.The point rests on the delta versions and iceberg snapshots lines, which show several commits becoming one,and on the two column listings, which show the names carried across."""from deltalake import DeltaTablefrom lib.lakehouse import (create_iceberg_table, new_warehouse, print_schema, read_delta, safe_error, scan_arrow,                           write_delta_hours)def main():    try:        with new_warehouse() as wh:            path = write_delta_hours(wh.root, range(3))            source = read_delta(path)            # Delta numbers its versions from 0, so the count is the last version plus one            print(f"delta versions: {DeltaTable(path).version() + 1}")            print(f"delta rows: {source.num_rows}")            print("delta columns (name, type, nullability):")            print_schema(source.schema)            table = create_iceberg_table(wh)            table.append(source)            print(f"iceberg snapshots: {len(table.metadata.snapshots)}")            print(f"iceberg rows: {scan_arrow(table).num_rows}")            print("iceberg columns (name, type, requirement):")            # sorted by name, so the two listings line up row for row            for field in sorted(table.schema().fields, key=lambda field: field.name):                # Iceberg calls a nullable field optional, so the listing says optional where Delta says nullable                requirement = "required" if field.required else "optional"                print(f"{field.name}\t{field.field_type}\t{requirement}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython delta-to-iceberg-copy.py
delta versions: 3
delta rows: 1499
delta columns (name, type, nullability):
domain_code	string	nullable
hour_utc	timestamp[us]	nullable
page_title	string	nullable
response_bytes	int64	nullable
views	int64	nullable
iceberg snapshots: 1
iceberg rows: 1499
iceberg columns (name, type, requirement):
domain_code	string	optional
hour_utc	timestamp	optional
page_title	string	optional
response_bytes	long	optional
views	long	optional

A cópia tem tantas linhas quanto a fonte, mas deixa o histórico para trás. A tabela Delta tem 3 versões e 1499 linhas. A tabela Iceberg é construída a partir de um único append de todas elas, por isso tem 1 snapshot, o início do próprio histórico, como a cópia para o DuckLake. Sua contagem de linhas, 1499, é igual à da fonte.

O restante da saída lista os dois esquemas, uma coluna por linha. Leia-os lado a lado:

Coluna Delta Lake (tipo Arrow) Tipo Iceberg
domain_code string string
hour_utc timestamp[us] timestamp
page_title string string
response_bytes int64 long
views int64 long

Os nomes são mantidos sem alteração, porque a cópia os obtém do esquema Arrow. Os tipos correspondem um a um. A única mudança de grafia é int64 no Arrow, que o Iceberg chama de long. Os dois lados usam microssegundos para hour_utc, e a verificação de timestamp abaixo explica o que acontece quando não usam.

O pyiceberg é rigoroso com os nomes. Ele verifica o esquema Arrow contra o esquema da tabela antes de gravar. Ele para com um erro de incompatibilidade quando o nome de uma coluna difere, ou quando um tipo não pode ser promovido ao tipo da tabela. Ele aceita um tipo que pode ser promovido, como int para long. Essa verificação está na função _check_pyarrow_schema_compatible, em pyiceberg/io/pyarrow.py, na versão fixada da biblioteca. A tabela Delta também não pode renomear uma coluna nesta versão fixada, como a seção de renomeação do capítulo sobre esquemas mostrou. Se os dois lados discordarem de um nome, você altera o destino, não a fonte. O pyiceberg associa as colunas Arrow à tabela pelo nome, então os IDs de campo do destino vêm do esquema que você escreve. Você escreve o esquema de destino por conta própria, em vez de deixar que o primeiro lote o defina.

Regra prática: Escreva o esquema de destino por conta própria, com os tipos que você deseja, e imprima os dois esquemas após a cópia, como faz o exemplo. Aceite um tipo quase equivalente, como int64 para long, somente depois de verificá-lo na saída. Não aceite um nome que seja diferente.

Verifique a precisão dos timestamps antes da cópia

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

Timestamps são um ponto em que os formatos divergem, às vezes de forma silenciosa. A especificação do Iceberg define timestamps em nanossegundos como um tipo da versão 3, de modo que uma tabela da versão 2 não tem tipo para eles (a especificação do Iceberg, seção da versão 3). A tabela do exemplo é da versão 2, o padrão. Nesta versão fixada, o pyiceberg se recusa a gravar a versão 3, de modo que os valores em nanossegundos só podem ser mantidos por um formato diferente do Iceberg. Este exemplo grava dois valores que diferem apenas abaixo de um microssegundo, 1000000500 e 1000000999 nanossegundos, em cada formato:

timestamp-precision-check.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Write two timestamps that differ only below a microsecond to Iceberg, Delta Lake and DuckLake, and show what each kept.The point rests on the Iceberg error line and on the Delta and DuckLake read-back lines."""import pyarrow as pafrom deltalake import write_deltalakefrom pyiceberg.schema import Schemafrom pyiceberg.types import NestedField, TimestampTypefrom lib.lakehouse import copy_to_ducklake, new_warehouse, NAMESPACE, read_delta, safe_error, sql_rows# nanoseconds since 1970: one second plus 500 and 999 nanoseconds, so the two values differ below a microsecondNANOSECONDS = pa.table({"hour_utc": pa.array([1000000500, 1000000999], pa.timestamp("ns"))})def main():    try:        with new_warehouse() as wh:            # cast to int64 gives the integer behind each timestamp, so distinct values are counted exactly            print(f"written distinct values: {len(set(NANOSECONDS['hour_utc'].cast(pa.int64()).to_pylist()))}")            # TimestampType stores microseconds; a version 2 table has no nanosecond type to declare instead            table = wh.catalog.create_table(                f"{NAMESPACE}.precision",                schema=Schema(NestedField(1, "hour_utc", TimestampType(), required=False)),            )            try:                # this append raises, because the table cannot hold nanoseconds; the except prints the error                table.append(NANOSECONDS)            except Exception as exc:                print(f"iceberg append: {safe_error(exc, wh)}")            path = str(wh.root / "precision")            write_deltalake(path, NANOSECONDS, mode="overwrite")            # the cast reads the count in the column's unit, which Delta wrote as microseconds, so 1000000 is one second            kept = read_delta(path)["hour_utc"].cast(pa.int64()).to_pylist()            print(f"delta read back as microseconds: {kept}")            print(f"delta distinct values read back: {len(set(kept))}")            target = copy_to_ducklake(wh, NANOSECONDS)            # epoch_ns returns nanoseconds since 1970, so a value cut to microseconds would end in three zeros            rows = sql_rows(wh.con, f"SELECT epoch_ns(hour_utc) FROM {target}")            print(f"ducklake epoch nanoseconds read back: {[row[0] for row in rows]}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython timestamp-precision-check.py
written distinct values: 2
iceberg append: UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns]
delta read back as microseconds: [1000000, 1000000]
delta distinct values read back: 1
ducklake epoch nanoseconds read back: [1000000500, 1000000999]

A primeira linha é a entrada, dois valores distintos. Em seguida, cada formato responde à sua maneira.

O append no Iceberg falha. O erro é UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns]. O erro indica a coluna e o tipo, de modo que a falha é a mais clara dos três casos e, por padrão, nada é alterado silenciosamente. O erro do pyiceberg indica uma configuração, PYICEBERG_DOWNCAST_NS_TIMESTAMP_TO_US_ON_WRITE, que converte nanossegundos para microssegundos na gravação. Com ela definida, o mesmo append é concluído e os valores são lidos de volta como microssegundos inteiros, com apenas um aviso registrado no log. É o mesmo corte que o Delta faz; por isso, defina-a apenas para um job que tenha decidido cortar os valores, e não em um ambiente que todos os escritores compartilham.

A gravação no Delta é concluída, e a leitura mostra [1000000, 1000000]. Ambos os valores foram cortados para microssegundos inteiros, e os dois valores distintos se tornaram um só. A gravação não gerou erro, e a contagem de linhas é a mesma. Somente uma verificação dos valores revela a perda. A contagem de valores distintos cai de 2 para 1.

O DuckLake mantém os nanossegundos. Sua tabela armazena os dois valores como foram gravados, e o exemplo os lê de volta como [1000000500, 1000000999].

A tabela pageviews registra horas, por isso o caso nunca chega ao problema. Uma tabela de logs brutos de requisições, sim. Seus timestamps vêm de um relógio que conta com precisão maior que um microssegundo, e sua cópia precisa escolher uma regra para esses dígitos. Faça a pergunta para cada coluna de timestamp antes da primeira cópia, porque a resposta só é visível nos valores. As cópias deste capítulo usam timestamps em microssegundos, que os três formatos mantêm, por isso as cópias coincidem. Uma tabela real pode conter valores abaixo de um microssegundo vindos da fonte, e a cópia precisa decidir o que fazer com eles antes da primeira gravação.

Regra prática: Verifique a precisão dos timestamps com um valor abaixo de um microssegundo antes da primeira cópia. Escolha a regra com antecedência. Converta a coluna para microssegundos e conte os valores que a conversão altera; rejeite a cópia; ou grave em um formato que mantenha nanossegundos. Não deixe a escolha para a biblioteca de gravação, porque um corte silencioso não gera erro que você possa tratar.

Verifique cada cópia com um digest ordenado

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

Uma contagem de linhas igual não prova que os valores coincidem. Uma cópia pode manter a contagem e alterar um valor, e a contagem não mostrará isso. Um digest mostra. O digest de uma tabela é um hash de suas linhas ordenadas: digest_rows ordena as linhas, escreve cada uma delas como uma linha de texto e calcula o hash do resultado. A ordenação torna o digest independente da ordem em que as linhas são devolvidas, de modo que duas cópias com as mesmas linhas obtêm o mesmo digest, qualquer que seja o formato de cada uma. digest_rows é executado nas duas cópias, e também em uma cópia com uma contagem de visualizações alterada de propósito:

verify-copies-by-digest.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""Check each copy against its source with a sorted digest, and show that one changed value fails it.The point rests on the two iceberg to ducklake digest lines: the copy matches its source, and a copy with onechanged count does not."""from lib.lakehouse import (copy_to_ducklake, create_iceberg_table, digest_rows, new_warehouse, read_cut_hour,                           read_delta, safe_error, scan_arrow, sql_rows, write_delta_hours)def same(source, copy):    return digest_rows(source) == digest_rows(copy)def check_iceberg_to_ducklake():    with new_warehouse() as wh:        table = create_iceberg_table(wh)        for hour in range(3):            table.append(read_cut_hour(hour))        target = copy_to_ducklake(wh, scan_arrow(table))        source_rows = sql_rows(wh.con, "SELECT * FROM source", source=scan_arrow(table))        copy_rows = wh.con.execute(f"SELECT * FROM {target}").fetchall()        first = copy_rows[0]        # the copy's columns are hour_utc, domain_code, page_title, views, response_bytes, so index 3 is views        changed = [(*first[:3], first[3] + 1, first[4]), *copy_rows[1:]]        print(f"iceberg to ducklake rows: {len(source_rows)} and {len(copy_rows)}")        matches = same(source_rows, copy_rows)        # printed before the assert, so a failing run still shows the word        print(f"iceberg to ducklake digests: {'match' if matches else 'differ'}")        assert matches        still_matches = same(source_rows, changed)        print(f"iceberg to ducklake with one changed view count digests: {'match' if still_matches else 'differ'}")        # one changed count must change the digest        assert not still_matchesdef check_delta_to_iceberg():    with new_warehouse() as wh:        path = write_delta_hours(wh.root, range(3))        table = create_iceberg_table(wh)        table.append(read_delta(path))        source_rows = sql_rows(wh.con, "SELECT * FROM source", source=read_delta(path))        copy_rows = sql_rows(wh.con, "SELECT * FROM copy", copy=scan_arrow(table))        print(f"delta to iceberg rows: {len(source_rows)} and {len(copy_rows)}")        assert same(source_rows, copy_rows)def main():    try:        check_iceberg_to_ducklake()        check_delta_to_iceberg()    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Saídapython verify-copies-by-digest.py
iceberg to ducklake rows: 1499 and 1499
iceberg to ducklake digests: match
iceberg to ducklake with one changed view count digests: differ
delta to iceberg rows: 1499 and 1499

Um único número alterado basta para mudar o digest, de modo que um digest que coincide é uma evidência, e um digest que difere é motivo para parar. Para a cópia de Iceberg para DuckLake, a saída mostra as duas contagens de linhas, que são iguais, e em seguida os digests match. A mesma verificação na cópia de Delta para Iceberg também coincide. Com uma contagem de visualizações alterada, os digests differ.

O digest compara os valores como o banco de dados os devolve, e tem um limite. Se os dois lados forem convertidos para texto antes do hash, dois valores de tipos diferentes podem produzir o mesmo texto. O inteiro 1 e o texto '1' são o mesmo texto. Compare valores tipados, como faz o exemplo, e imprima os esquemas como fez a cópia de Delta para Iceberg. O digest também não diz nada sobre nomes e tipos de colunas. Duas tabelas com as mesmas linhas sob nomes de colunas diferentes têm o mesmo digest. As listagens de esquema das seções anteriores verificam os nomes, e o digest verifica os valores, por isso uma cópia precisa dos dois.

O digest não é um hash dos arquivos. As linhas são ordenadas por seus valores tipados, cada uma se torna uma linha com sua representação em Python, e o texto unido recebe o hash SHA-256. Duas linhas com valores iguais produzem linhas iguais, que é o que a comparação exige. Uma alteração em um valor muda uma linha e, portanto, todo o digest.

Escolha também o momento da verificação. Um digest é verdadeiro para as linhas que existiam quando ele foi executado. Qualquer gravação na origem depois desse ponto torna a cópia desatualizada, e o digest de antes da gravação deixa de valer. A verificação deve ocorrer depois da última gravação na origem, e antes que alguém leia da cópia.

Regra prática: Calcule o digest dos dois lados depois da última gravação na origem, sobre as mesmas colunas, com valores tipados. Compare as contagens de linhas e os digests juntos. Não migre os leitores para a cópia nem apague a origem até que os dois coincidam. Se houve gravações durante a cópia, repita a cópia e o digest.

O que dá errado em produção

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

Uma migração que falha geralmente passa na primeira verificação e falha depois. Estas são as falhas a observar e como você perceberia cada uma.

  • Uma virada que disputa com um escritor. Um digest cobre apenas as linhas que leu, como diz a seção sobre digest. A primeira inserção depois dele deixa a cópia desatualizada, e o digest não avisa você. Pare os escritores, copie, calcule o digest e só então mova os leitores. Se os escritores não puderem parar, copie em janelas e verifique as linhas que chegaram depois da última janela.
  • Apagar a origem antes de as verificações passarem. A origem guarda o histórico que a cópia não tem. Quando a origem some, a viagem no tempo para os seus snapshots e versões vai junto. Mantenha a origem até que os digests coincidam e todos os leitores tenham sido movidos. Depois, decida por escrito por quanto tempo mantê-la.
  • Uma cópia com as linhas e sem o layout. Uma cópia feita sem o ALTER teria todas as linhas e coincidiria com o digest, mas sem nenhuma partição definida. A lista de partições e os arquivos por partição são as verificações que mostram que o layout está ausente, então imprima as duas após a cópia.
  • Timestamps que mudam sem erro. O Delta Lake cortou os valores de nanossegundos para microssegundos e não levantou nenhum erro. A contagem de linhas continuou a mesma. Só uma verificação dos valores detecta o problema, então uma cópia com dados abaixo de microssegundos precisa dessa verificação antes de ser executada.
  • Nomes e tipos que diferem. O pyiceberg recusa uma inserção cujos nomes de colunas difiram dos da tabela, ou cujo tipo ele não consiga promover, e essa recusa é a falha mais clara. O caso mais difícil é uma coluna cujo nome coincide e cujo tipo ele aceita, como um long que era um int. Imprima os dois esquemas e leia-os, em vez de confiar que a inserção teve sucesso.
  • Tamanho e memória. As funções auxiliares deste capítulo leem a tabela inteira na memória antes de gravá-la. Isso funciona bem para 1499 linhas. Uma tabela de bilhões de linhas precisa de uma cópia que leia e grave em lotes, e o digest deve então ser calculado sobre os mesmos lotes dos dois lados, para que continue sendo uma verificação da tabela inteira.
  • Leitores que gravam nas duas tabelas. Durante uma cópia, uma tarefa que grava nas duas tabelas por engano faz as tabelas divergirem, e o digest mostrará uma divergência que nenhuma gravação isolada explica. Indique no runbook um único escritor por tabela antes de a virada começar.
  • Um digest sobre texto. Um digest calculado sobre conversões de tipo pode coincidir quando os tipos são diferentes. A verificação deste capítulo compara valores tipados, e o runbook deve dizer isso, para que uma edição posterior da verificação não elimine os tipos silenciosamente.

Decisões tomadas neste capítulo

Última alteração na edição 2026.11.7
  • As cópias passam pelo Arrow, e cada destino é escrito pela biblioteca que é dona do seu formato. O pyiceberg escreve Iceberg, a extensão ducklake do DuckDB escreve DuckLake, e o deltalake escreve Delta Lake. Este livro não usa as extensões iceberg ou delta do DuckDB, de modo que nenhuma cópia dele depende delas.
  • As tabelas Delta são lidas por meio de read_delta, pelo motivo explicado no capítulo 8. Toda leitura Delta deste capítulo passa por ela.
  • Uma cópia é feita uma única vez, inicia um novo histórico e é verificada antes que alguém passe a usá-la. A origem permanece no lugar até que os digests coincidam e os leitores tenham migrado.
  • A especificação de partição é definida manualmente no destino, com um ALTER antes da inserção das linhas, e é impressa. A cópia não a transfere.
  • Cada exemplo de cópia cria sua própria origem a partir das mesmas três horas do recorte. Cada exemplo é executado isoladamente, e cada verificação lê apenas as linhas que o próprio exemplo gravou.
  • As verificações são executadas sobre valores tipados, após a última gravação, nas mesmas colunas. A contagem de linhas e o digest são lidos em conjunto, e nenhum dos dois é usado isoladamente para dar uma cópia como correta.
  • As cópias usam timestamps em microssegundos, e um exemplo separado verifica valores abaixo de microssegundo. Cada cópia deste capítulo mantém seus valores em microssegundos, de modo que os digests coincidem. O exemplo de precisão mostra o que cada formato faz com um valor que não consegue manter.
  • A migração apenas de metadados não é usada aqui. O Table.add_files do pyiceberg adiciona a uma tabela Iceberg, como arquivos de dados, arquivos Parquet que já existem (Table.add_files em pyiceberg/table/__init__.py, pyiceberg 0.12.0). Sua documentação da API, que não está fixada nessa versão, descreve isso como efetivar os arquivos sem reescrevê-los. Isso mantém os arquivos de dados no lugar, o que uma cópia não faz. Este capítulo não o executou, e copia linhas no lugar disso.

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 9 de 10: Mover uma tabela entre formatos e verificar a cópia

  1. O que uma cópia mantém e o que perde
  2. Copie a tabela pageviews para o DuckLake
  3. Copie a tabela Delta para uma tabela pyiceberg
  4. Verifique a precisão dos timestamps antes da cópia
  5. Verifique cada cópia com um digest ordenado
  6. O que dá errado em produção
  7. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos