Iceberg Manifest'lerini Elle Okumayı Bırakın

Apache Iceberg metadata'sı güçlüdür. Ama aynı zamanda… bir hata ayıklama oturumunda elle "okumak" isteyeceğiniz bir şey değildir.

Bir tabloya belirli koşullar altında ne olduğunu (yeni snapshot'lar, yeniden yazılan manifest'ler, eklenen/silinen veri dosyaları, ortaya çıkan equality/position delete'ler) anlamaya çalıştıysanız, muhtemelen metadata.json, manifest listeleri, manifest dosyaları ve asıl veri/silme dosyaları arasında gidip gelmişsinizdir. İşe yarar; ama yavaştır, hataya açıktır ve zihinsel olarak yorucudur.

Bu iş akışını hızlandırmak için Iceberg Lens'i geliştirdim.

Iceberg Lens, Iceberg tablo metadata'sını yapılandırılmış bir Inspector paneliyle (özellikler, köken bilgisi, changelog/özet) birlikte * etkileşimli bir grafiğe* dönüştüren, salt okunur, yerel öncelikli bir masaüstü arayüzüdür. "Şu an bir şeyi debug ediyorum" gerçekliği için tasarlandı: hızlı gezinme, net bir yapı ve ham dosyaları elle okumaya harcanan daha az zaman.

Repo (kurulum paketleri GitHub Releases'te mevcut):

https://github.com/mmdemirbas/ice-lens

Sorun: metadata'yı elle ayrıştırmak

Tipik bir elle inceleme döngüsü şöyle görünür:

1. Tablo metadata'sını (metadata.json) açıp güncel snapshot'ı belirleyin.
2. Snapshot referanslarını takip ederek manifest listesine ulaşın.
3. Manifest listesini açıp manifest dosyalarını bulun.
4. Manifest dosyalarını tek tek açıp girdileri yorumlayın:
   • veri dosyaları
   • silme dosyaları (equality / position)
5. Eski snapshot'lar veya uç durumlar için aynısını tekrarlayın.

Iceberg'i bir kez öğrenmek için bu yeterli. Ama özellik geliştirirken, hata düzeltirken ya da snapshot'lar arasında davranışı doğrularken yeterli değil.

Iceberg Lens ne yapıyor

Iceberg Lens tek bir temel hedefe odaklanır: tablonun yapısını bir bakışta anlaşılır kılmak.

Şunları incelemenize yardımcı olur:

• metadata
• snapshot'lar
• manifest'ler
• veri dosyaları
• silme dosyaları (equality / position)
• örnek satırlar (mümkün olduğunca)
• zaman içindeki değişiklikleri izlemek için her seviyedeki changelog'lar

Arayüz, birbirini tamamlayan iki görünüm üzerine kurulu:

1) Grafik görünümü (yapı ve gezinme)

Tabloyu görsel olarak dolaşabilirsiniz: metadata → snapshot'lar → manifest'ler → veri dosyaları → veri satırları. Gezinmenin yolu düğümlere tıklamak.

2) Inspector (ayrıntılar ve köken bilgisi)

Bir düğüme tıkladığınızda yapılandırılmış bir ayrıntı görünümü elde edersiniz: özellikler, üst/alt ilişkileri ve ilgili yerlerde changelog/özet.

Dosyaları açıp kafanızda join yapmak yerine tıklar, inceler ve ilerlersiniz.

Neden yerel öncelikli ve salt okunur

Iceberg Lens şu anda yalnızca yerel dosya sistemiyle çalışıyor ve bilinçli olarak salt okunur.

Bu tercih pratik nedenlere dayanıyor:

• Hata ayıklama oturumları çoğunlukla yerel ortamlarda yapılır.
• Salt okunur olmak riski ortadan kaldırır ve güven verir. Yanlışlıkla bir şeyi değiştirme endişesi olmadan keşfedebilirsiniz.
• Harici bir katalog ya da servis gerekmez. Benimsemesi kolay, çalıştırması hızlı.

Talep olursa uzak nesne depoları ve katalog entegrasyonları ileride gelebilir; ama aracı hata ayıklama için hemen kullanışlı kılan şey yerel öncelikli yaklaşım.

Kısa bir tur

Yaygın bir iş akışı şöyle:

1. Workspace'inize bir tablo veya warehouse ekleyin.
2. Bir tablo seçin ve güncel snapshot'tan başlayın.
3. Manifest'lere inip hangi dosyalara referans verdiklerini görün.
4. Equality/position delete senaryolarını doğrulamak için silme dosyalarına atlayın.
5. Seviyeler arasında neyin değiştiğini anlamak için changelog tablolarını kullanın.
6. İsterseniz varsayımlarınızı hızlıca doğrulamak için örnek satırları inceleyin.

Bu anlarda küçük özellikler fark yaratıyor: "Fit Graph", yerleşimi yeniden uygulama, aynı workspace'te birden fazla tablo açma ve metadata değiştiğinde otomatik yeniden yükleme.

Uygulama notları

Iceberg Lens Kotlin + Compose Desktop ile geliştirildi. Amaç, Iceberg üzerindeki işlerim ilerledikçe aracı geliştirmeye devam edebilmem için hızlı bir iterasyon döngüsü ve yerel hissi veren bir arayüzdü.

"Hata ayıklarken buna ihtiyacım var" diye başlayan küçük bir proje olarak doğdu. Birkaç günlük geliştirmenin ardından, herkese açık paylaşmaya değecek kadar kullanışlı olduğu netleşti.

Mevcut sınırlamalar

• Yalnızca yerel dosya sistemi (henüz katalog entegrasyonu veya uzak nesne deposu desteği yok, ancak ileride değerlendirebilirim )
• Örnek satırları okumak veri dosyalarını taradığından büyük tablolarda yavaş olacaktır.

Sırada ne var (yol haritası)

En değerli görünen yönler şunlar:

• Snapshot diff / karşılaştırma (önce dosya seviyesinde, sonra daha derine inerek)
• Arama + filtreler (partition, içerik türü, dosya adı)
• Dışa aktarma (paylaşım/hata ayıklama dokümanları için grafik / düğüm ayrıntıları)
• Yerleşim seçenekleri (farklı grafik yerleşimleri)
• Büyük tablolar için performans iyileştirmeleri
• Olası bir IntelliJ IDEA eklentisi sürümü
• Talep olursa isteğe bağlı uzak depo desteği (S3/HDFS/ADLS)

Aracı denerseniz şu konudaki geri bildiriminiz benim için değerli olur:

Bir sonraki adımda desteklenmesini en çok istediğiniz iş akışı hangisi?

Deneyin / katkıda bulunun

• Repo: https://github.com/mmdemirbas/ice-lens
• Kurulum paketleri GitHub Releases'te mevcut.
• Geri bildirim, issue ve özellik talepleri memnuniyetle karşılanır.

Iceberg geliştiricisiyseniz özellikle şu konulardaki görüşlerinizi duymak isterim:

• Hangi düğüm türlerinin/ayrıntıların varsayılan olarak gösterilmesini istersiniz
• İş akışınızda "snapshot diff" pratikte ne anlama gelmeli
• Hangi filtreler/arama size en çok zaman kazandırır

Okuduğunuz için teşekkürler!