# מיגרציה מ־Delta יכולה ליצור תגיות ולשנות את היסטוריית חותמות הזמן

Iceberg 1.12.0 העביר שתי גרסאות של טבלת Delta סינתטית ריקה לשני צילומי מצב, ויצר ארבע תגיות ממספרי גרסאות המקור ומזמני ה־commit-info השמורים. ביעד פורסמה רשומה אחת בהיסטוריית חותמות הזמן, עבור צילום המצב האחרון. במיגרציה שנייה, שני זמני commit שמורים וזהים גרמו לשגיאת תגית כפולה. טבלת היעד נותרה חסרה בקטלוג המקומי, ושני קובצי Avro שהוכנו נותרו בנתיב המחסן שלה. [תצורת הבדיקה](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java) ו[תוצאות התצפית](https://sapien1.com/research/iceberg-delta-clock/observations.json) משתמשות בטבלאות מקומיות ריקות עם Delta Standalone 3.3.3 ו־HadoopCatalog. [פעולת המיגרציה](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L177-L189)

## שני צילומי מצב ורשומת היסטוריה אחת שפורסמה

הבדיקה מגדירה את זמני קובצי הלוג של Delta בהפרש של שתי שניות. בורר חותמות הזמן הוותיק של Delta משתמש בזמני הקבצים האלה. זמני ה־commit-info השמורים בנפרד במקור נבדלים באלפית שנייה במקרה המוצלח. Iceberg משתמש בערכים השמורים האלה למתן שמות לתגיות `delta-ts`, ויוצר גם תגית `delta-version` לכל גרסת מקור. [שעוני ההיסטוריה של Delta](https://github.com/delta-io/delta/blob/v3.3.3/connectors/standalone/src/main/scala/io/delta/standalone/internal/DeltaHistoryManager.scala#L196-L236) · [הקצאת תגיות ב־Iceberg](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440)

| חיפוש | תוצאה שנצפתה |
| --- | --- |
| חיפוש לפי חותמת זמן ב־Delta בזמן קובץ הלוג השני של המקור | גרסת מקור 1 |
| תגית `delta-version-0` של Iceberg | צילום המצב המוקדם שהועבר |
| חיפוש לפי חותמת זמן ב־Iceberg בזמן קובץ הלוג השני של Delta | אין רשומה תואמת בהיסטוריה שפורסמה |
| חיפוש לפי חותמת זמן ב־Iceberg בזמן היצירה של צילום המצב הראשון ביעד | אין רשומה תואמת בהיסטוריה שפורסמה |
| חיפוש לפי חותמת זמן ב־Iceberg בזמן ההיסטוריה שפורסם ביעד | צילום המצב האחרון שהועבר |

המיגרציה מכינה את שני השחזורים בעסקת יצירה אחת. בונה המטא־נתונים של Iceberg מסנן מההיסטוריה שפורסמה רשומות ביניים של צילום המצב הראשי. צילום המצב המוקדם והתגיות שלו נשארים זמינים. פותר חותמות הזמן מחפש בהיסטוריה שפורסמה. תצורת הבדיקה הראשונה שלנו ציפתה לשתי רשומות ונעצרה בבדיקת התנאי הזאת. תצורת הבדיקה המתוקנת בדקה בנפרד את שני צילומי המצב המתויגים ואת ההיסטוריה שכללה רק את האחרון. [סינון רשומות לוג ביניים](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/TableMetadata.java#L1840-L1885) · [פותר ההיסטוריה](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/util/SnapshotUtil.java#L314-L337) · [שינוי קודם בהיסטוריה](https://github.com/apache/iceberg/pull/5568)

## זמנים שמורים חוזרים

במקרה המקביל עדיין יש במקור שני זמני קובצי לוג עוקבים, ולכן עדיין אפשר לקרוא את הנתונים לפי שני גבולות גרסאות המקור. שתי חותמות הזמן של ה־commit-info השמור זהות. השחזור השני מנסה ליצור את אותה תגית `delta-ts-1577836800000` ונתקל בבדיקת ההפניה הכפולה של Iceberg לפני שעסקת היצירה מתבצעת. הקטלוג מדווח שהטבלה חסרה. בבדיקה נפרדת של הקבצים נמצאו שני קובצי Avro שהוכנו, בגודל כולל של 8,641 בתים. תצורת הבדיקה מפעילה את חותמת הזמן השמורה הוותיקה שבה משתמשת הפעולה. בגרסאות חדשות יותר של Delta, `inCommitTimestamp` הוא שדה נפרד בפרוטוקול. מימוש מוצע למיגרציה ב־Delta Kernel כבר כולל לוגיקה לדילוג על תגיות זמן חוזרות. [בדיקת הפניה כפולה](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/core/src/main/java/org/apache/iceberg/UpdateSnapshotReferencesOperation.java#L61-L66) · [חישוב שם התגית של Delta](https://github.com/apache/iceberg/blob/212aa894e919ff9fdf89160da4aadcbe6858ac01/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeTableAction.java#L429-L440) · [פרוטוקול Delta](https://github.com/delta-io/delta/blob/v3.3.3/PROTOCOL.md#in-commit-timestamps) · [טיפול מוצע ב־Kernel](https://github.com/apache/iceberg/blob/0275a908e9314cced92dbaafb65aa3f794b39663/delta-lake/src/main/java/org/apache/iceberg/delta/BaseSnapshotDeltaLakeKernelTableAction.java#L615-L629)

במיגרציה שמשרתת צרכנים של נתונים היסטוריים, יש לשמור יחד את גרסת המקור, שעון הבורר של המקור וההפניה לצילום המצב ביעד. מומלץ לתרגל בנפרד קריאות לפי הפניה בעלת שם ולפי חותמת זמן. גם לאחר כשל ביצירה נדרשות בדיקות נפרדות של הקטלוג ושל קובצי היעד. הריצות שלנו מדדו את התהליכים האלה בטבלאות סינתטיות ריקות וב־HadoopCatalog מקומי. Spark SQL, שוויון רשומות, התנהגות בניסיון חוזר וקטלוגים אחרים לא נמדדו.

## שחזור

יש להוריד את [ClockReplay.java](https://sapien1.com/research/iceberg-delta-clock/ClockReplay.java), את [pom.xml](https://sapien1.com/research/iceberg-delta-clock/pom.xml) ואת [תוצאות התצפית](https://sapien1.com/research/iceberg-delta-clock/observations.json) לאותה תיקייה. מתוך התיקייה הזאת יש להשתמש ב־JDK 17 וב־Maven. הריצה המאומתת השתמשה ב־Liberica JDK Lite 17.0.21.0.3+5 וב־Maven 3.9.16. Maven פותר את גרסאות התלויות הקבועות אל התיקייה הזמנית. משגר קובצי המקור של Java מריץ את המיגרציה על שני זוגות קובצי לוג שנכתבו זה עתה. [יעד ה־classpath של Maven](https://maven.apache.org/plugins-archives/maven-dependency-plugin-3.8.1/build-classpath-mojo.html) · [משגר קובצי המקור של Java](https://docs.oracle.com/en/java/javase/17/docs/specs/man/java.html)

```
set -eu
sapien_delta_run=$(mktemp -d)
trap 'rm -rf -- "$sapien_delta_run"' EXIT
mkdir "$sapien_delta_run/fixture"
mvn -C -B -q -f pom.xml -Dmaven.repo.local="$sapien_delta_run/repository" \
  org.apache.maven.plugins:maven-dependency-plugin:3.8.1:build-classpath \
  -DincludeScope=runtime -Dmdep.outputFile="$sapien_delta_run/classpath.txt"
java --class-path "$(cat "$sapien_delta_run/classpath.txt")" --source 17 ClockReplay.java \
  "$sapien_delta_run/fixture"
sapien_delta_warehouse="$sapien_delta_run/fixture/warehouse/fixture"
cat "$sapien_delta_warehouse/distinct_times/metadata/v1.metadata.json"
find "$sapien_delta_warehouse/repeated_time" -type f -exec wc -c {} +
```

כלי הבדיקה מדפיס את שתי שורות התוצאה האלה.

```
DISTINCT sourceCutoffVersion=1 migratedSnapshots=2 migrationTags=4 publishedHistoryEntries=1 targetCutoffSnapshot=null
REPEATED duplicateTimestampTagRejected=true catalogTableExists=false
```

קריאת המטא־נתונים חושפת את `snapshots`, את `refs` ואת `snapshot-log`. הפקודה האחרונה סוקרת את קובצי היעד שבו היצירה נכשלה, לפני ניקוי הקבצים הזמניים. מזהי צילומי המצב, זמני היצירה ושמות הקבצים שהוכנו עשויים להשתנות בין ריצות. יש להשוות את מיפוי התגיות שנשמר ואת תוצאות הקטלוג והחיפוש לפי חותמת זמן.
