Gao Kaptan DocsApache Iceberg: ACID tablolar, şema evrimi ve time travel
MinIO + Iceberg REST katalog + Trino ile gerçek tablo formatlı bir veri gölü. Kurulum, SQL ve zaman yolculuğu — hepsi ölçülmüş çıktılarla.
Apache Iceberg bir tablo formatıdır. S3'teki Parquet dosyalarını "tarayan" bir motordan farkı şu: tablonun ne olduğunu, hangi dosyalardan oluştuğunu ve geçmişte hangi hâllerden geçtiğini metadata olarak yazar. Karşılığında düz dosya taramasının veremediği üç şeyi verir: ACID işlemler, şema evrimi ve time travel.
Bu sayfa üç pod'la çalışan bir kurulum anlatıyor:
Trino (sorgu motoru) ──► Iceberg REST katalog ──► MinIO (S3)
:8080 :8181 :9000
SQL çalıştırır tabloların nerede veri + metadata
olduğunu bilir burada dururKatalog, Iceberg'in beynidir: hangi tablonun hangi metadata dosyasını işaret ettiğini o
tutar. Katalogsuz Iceberg olmaz — bir CREATE TABLE önce kataloğa yazılır, sonra S3'e.
Tek tıkla: Atölye tarifi
Katalog → Atölye → Trino + Iceberg Lakehouse. İki varyant var:
- Tüm yığını otomatik kur — MinIO, katalog ve Trino birlikte gelir, ambar kovası da
açılır. Tek girdi ambar yolu (
s3://warehouse/). - MinIO (mevcut pod) — çalışan bir MinIO'ya bağlanır; access key/secret ve ambar yolunu siz verirsiniz. Bu varyantta kovayı önceden açmış olmanız gerekir (aşağıdaki adım).
Tarif ne kuruyorsa aşağıda elle de anlatılıyor — ne olduğunu görmek ya da parçaları ayrı ayrı yönetmek isterseniz.
Elle kurulum
MinIO — nesne deposu
Şablondan minio deploy edin (web_port: 9000, konsol 9090). Kök kullanıcı ve parolayı
not alın; ikisi de sonraki iki adımda geçecek.
Warehouse bucket'ını oluşturun
Otomatik kurulum bunu sizin için yapar; elle kurarken atlamayın. Boş bir MinIO'da
bucket yokken CREATE TABLE şu hatayla düşer ve sebebi hiç görünmez:
Failed checking new table's location: s3://warehouse/demo/olaylar_...MinIO pod'unun terminalinde (mc imajda kurulu geliyor):
mc alias set yerel http://127.0.0.1:9000 <kullanici> <parola>
mc mb yerel/warehouse
mc ls yerelIceberg REST katalog
Imaj apache/iceberg-rest-fixture:1.9.1, port 8181, dışarı açılmasına gerek yok.
Ortam değişkenleri (çift alt çizgiler kasıtlı — nokta yerine geçiyor):
| Anahtar | Değer |
|---|---|
CATALOG_WAREHOUSE | s3://warehouse/ |
CATALOG_IO__IMPL | org.apache.iceberg.aws.s3.S3FileIO |
CATALOG_S3_ENDPOINT | http://<minio-pod>-svc.<ns>.svc.cluster.local:9000 |
CATALOG_S3_PATH__STYLE__ACCESS | true |
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY | MinIO kimlikleri |
AWS_REGION | us-east-1 |
Katalog durumunu bellekte tutar; pod yeniden başlarsa tablo kayıtları gider (veri S3'te kalır). Kalıcılık için JDBC arkasına alınması gerekir — bu sayfa onu kapsamıyor.
Trino — sorgu motoru
Imaj trinodb/trino:483, port 8080. Katalog tanımı bir dosya olarak pod'a
enjekte edilir; Trino bunu açılışta okur:
# /etc/trino/catalog/iceberg.properties
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=http://<katalog-pod>-svc.<ns>.svc.cluster.local:8181
iceberg.rest-catalog.warehouse=s3://warehouse/
fs.native-s3.enabled=true
s3.endpoint=http://<minio-pod>-svc.<ns>.svc.cluster.local:9000
s3.path-style-access=true
s3.region=us-east-1
s3.aws-access-key=<kullanici>
s3.aws-secret-key=<parola>Trino imajı 1 GB. Ölçüldü: indirme 2 dk 36 sn, pod'un running olması 6 dk 34 sn
sürdü. Pod uzun süre pending görünürse bozuk sanmayın — olaylara bakın, Pulling image
yazıyorsa sadece bekliyor.
Kullanım
Trino pod'unun terminalinde trino CLI hazır gelir.
CREATE SCHEMA iceberg.demo;
CREATE TABLE iceberg.demo.olaylar (ts timestamp(6), tur varchar)
WITH (format = 'PARQUET');
INSERT INTO iceberg.demo.olaylar VALUES (now(), 'deneme'), (now(), 'ikinci');
SELECT * FROM iceberg.demo.olaylar ORDER BY ts;"2026-09-04 22:18:05.690000","deneme"
"2026-09-04 22:18:05.690000","ikinci"Şema evrimi
Tabloyu yeniden yazmadan kolon eklenir; eski satırlar NULL ile gelir:
ALTER TABLE iceberg.demo.olaylar ADD COLUMN kaynak varchar;
INSERT INTO iceberg.demo.olaylar VALUES (now(), 'ucuncu', 'web');
SELECT tur, kaynak FROM iceberg.demo.olaylar ORDER BY tur;"deneme",""
"ikinci",""
"ucuncu","web"Snapshot'lar ve time travel
Her yazma bir snapshot üretir:
SELECT snapshot_id, operation
FROM iceberg.demo."olaylar$snapshots"
ORDER BY committed_at;"5366955591441431207","append"
"3124762228519191535","append"
"1418514429503265749","append"Herhangi bir snapshot doğrudan sorgulanabilir:
SELECT count(*) FROM iceberg.demo.olaylar; -- 3
SELECT count(*) FROM iceberg.demo.olaylar FOR VERSION AS OF 3124762228519191535; -- 2Time travel şemayı da geri sarar. kaynak kolonu eklenmeden önceki bir snapshot'ta o
kolonu sorgularsanız Trino şunu der:
Column 'kaynak' cannot be resolvedBu bir hata değil, doğru davranış: o an tabloda öyle bir kolon yoktu.
S3'te ne duruyor
mc ls --recursive yerel/warehousedemo/olaylar-2099abe5.../data/20260904_221805_...parquet 396B
demo/olaylar-2099abe5.../data/20260904_221829_...parquet 494B
demo/olaylar-2099abe5.../metadata/00000-24a217df....metadata.json 1.6KiB
demo/olaylar-2099abe5.../metadata/00001-039fce82....metadata.json 3.2KiB
demo/olaylar-2099abe5.../metadata/00002-f5f180ef....metadata.json 3.6KiB
demo/olaylar-2099abe5.../metadata/00003-9f9ffb8a....metadata.json 5.2KiBdata/ altındaki Parquet dosyaları veriyi, metadata/ altındaki JSON dosyaları tablonun
her hâlini tutuyor. Time travel'ı mümkün kılan şey bu numaralı metadata zinciridir — her
yazma yeni bir metadata.json üretir, eskisi yerinde kalır.
Tuzaklar
1 — Bucket kendiliğinden oluşmaz. Yukarıda anlatıldı; belirti Failed checking new table's location ve sebebi mesajda geçmiyor.
2 — Katalog seçimi önemli. Bu sayfa ve Atölye tarifi Iceberg'in resmî REST
kataloğunu kullanıyor. Tarif başlangıçta Nessie ile geliyordu; denendi (aynı MinIO, aynı Trino, tek değişken katalogdu) ve
CREATE TABLE şu hatayla düştü:
Location for ICEBERG_TABLE 'demo.olaylar' cannot be associated with any
configured object storage location: Missing access key and secret for
STATIC authentication modeNessie'nin NESSIE_CATALOG_SERVICE_S3_DEFAULT_OPTIONS_* değişkenleri konteynerde dolu
olmasına rağmen. Denenen ve işe yaramayan üç yol: Trino'da
iceberg.rest-catalog.vended-credentials-enabled=false, Nessie'de warehouse'a özel
(NESSIE_CATALOG_WAREHOUSES_WAREHOUSE_S3_*) kimlik tanımı, ve :latest yerine sabit
sürüm (0.104.1). Nessie'nin dallanma/commit özelliklerine ihtiyacınız yoksa REST
katalog daha az parça ve daha az sürprizdir.
3 — İmaj sürümünü sabitleyin. Nessie denemesi :latest ile başlamıştı; böyle bir
kurulum bugün çalışıp yarın kırılabilir çünkü altınızdaki imaj sessizce değişir. Bu
sayfadaki üç imaj da sürümlü: apache/iceberg-rest-fixture:1.9.1, trinodb/trino:483.
4 — REST katalog belleğe yazar. Pod yeniden başlarsa tablo kayıtları gider, veri ve metadata S3'te durur. Kalıcı bir kurulum için katalogun arkasına bir veritabanı (JDBC) koymak gerekir.
5 — Metadata dosyaları birikir. Her yazma yeni bir metadata.json üretir. Uzun süre
çalışan tablolarda snapshot süresi/sayısı sınırlanmalı
(ALTER TABLE ... EXECUTE expire_snapshots), yoksa metadata/ dizini şişer.