מידע על נקודת הקצה של קטלוג Apache Iceberg REST

ב-Borderless Lakehouse, המטא-נתונים מנוהלים באמצעות הקטלוג הייעודי לזמן ריצה של Lakehouse. כשמשתמשים בנקודת הקצה של קטלוג Apache Iceberg REST, המערכת מארגנת את הנתונים בהיררכיית משאבים קפדנית. הגדרת הקטלוג קובעת את סוגי האחסון הנתמכים ואת אופן הניתוב האזורי.

יכולות ותאימות

הקטלוג הייעודי לזמן ריצה של Lakehouse נועד לשילוב עם מנועי שאילתות שתואמים ל-Iceberg, על ידי תמיכה בפורמטים סטנדרטיים של טבלאות ועמידה בדרישות של ממשקי API פתוחים.

פורמטים נתמכים של טבלאות

יש תמיכה בטבלאות Apache Iceberg V2 (זמינות לכולם) ובטבלאות V3 (גרסת טרום-השקה). אין תמיכה בטבלאות Iceberg V1. כדי להשתמש בטבלאות קיימות בגרסה 1 עם נקודת הקצה של קטלוג REST של Apache Iceberg, צריך לשדרג אותן לגרסה נתמכת. מידע נוסף זמין במאמר שדרוג טבלאות Iceberg מגרסה 1 לגרסה 2.

תאימות ל-API ופעולות REST

הקטלוג הייעודי לזמן ריצה של Lakehouse מטמיע את התקן הפתוח Apache Iceberg REST Catalog API. מנועי שאילתות של לקוחות יוצרים אינטראקציה עם הקטלוג באמצעות ממשקי API סטנדרטיים של קטלוג REST. איך Lakehouse מטמיע את Apache Iceberg REST Catalog API

היררכיית המשאבים

נקודת הקצה של קטלוג REST של Apache Iceberg משתמשת בהיררכיה של משאבים כדי לארגן את הנתונים. בטבלה הבאה מפורטים המשאבים האלה:

משאב תיאור
קטלוג קטלוג הוא מאגר ברמה העליונה שמאפשר לארגן מרחבי שמות וטבלאות בקבוצות לוגיות, על ידי חלוקה שלהם לקטלוגים שונים. כל קטלוג מגובה במיקומי אחסון ייעודיים במחסן (כמו קטגוריה אחת או יותר של Cloud Storage) שבהם מאוחסנים המטא-נתונים וקובצי הנתונים הבסיסיים שלו.
מרחב שמות קיבוץ לוגי שמשמש לארגון טבלאות בתוך קטלוג, שפועל כמו מסדי נתונים, סכימות או ספריות.
טבלה טבלאות מכילות הגדרות של שורות ועמודות שאפשר לשלוח להן שאילתות.

קטלוגים ומיקומי אחסון

ההגדרות של הקטלוג קובעות איך הוא פועל ואיך הוא משתלב עם שירותי Google Cloud. אפשר להגדיר קטלוג עם כמה קטגוריות (מומלץ) או קטלוג עם קטגוריה אחת.

שתי האפשרויות תומכות בהנפקת פרטי כניסה.

כשמגדירים מנועי שאילתות של לקוחות (כמו Spark או Trino) להתחבר לנקודת הקצה של קטלוג REST של Apache Iceberg, מציינים את נתיב המחסן לפי סוג הקטלוג:

  • קטלוג עם כמה קטגוריות: מגדירים את הנתיב של המחסן ל-bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
  • קטלוג עם קטגוריה אחת: מגדירים את הנתיב של המחסן ל-gs://CLOUD_STORAGE_BUCKET_NAME.

קטלוג עם כמה קטגוריות (מומלץ)

כך אתם יכולים לתת לקטלוג שם שלא תלוי בשם של קטגוריה, ולהגדיר כמה קטגוריות לקטלוג אחד. ב-API הבסיסי, זה תואם להגדרה CATALOG_TYPE_BIGLAKE.

שיקולים:

  • הגדרת מחסן נתונים של לקוח (bl://): כשמגדירים לקוח Iceberg להתחבר לקטלוג עם כמה קטגוריות, צריך לציין את הנתיב של מחסן הנתונים באמצעות פורמט ה-URI של bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. הפורמט bl:// משמש רק במהלך הגדרת הלקוח כדי לזהות את הקטלוג. כשיוצרים או מגדירים את הקטלוג עצמו ב-Google Cloud, מיקומי האחסון (default_location ו-restricted_locations) תמיד מצוינים כנתיבים של Cloud Storage‏ (gs://).
  • מספר מקסימלי של מיקומי אחסון: בנוסף ל-default_location, אתם יכולים לציין עד 128 קטגוריות של Cloud Storage או נתיבי משנה ב-restricted_locations לכל קטלוג.
  • מיקום ברירת המחדל: אתם מספקים נתיב לקטגוריה (default_location) או נתיב משנה (כמו gs://my-bucket/path) שישמש כמיקום האחסון שמוגדר כברירת מחדל. כל המשאבים בקטלוג (מרחבי שמות וטבלאות) צריכים להיות בנתיב שצוין. לדוגמה, אם מציינים את gs://my-bucket/path, אי אפשר לארח מרחבי שמות או טבלאות ב-gs://my-bucket/another/path. במרחבי שמות שנוצרו בלי מיקום ספציפי, נעשה שימוש ב-default_location.
  • מיקומים מוגבלים: אתם יכולים גם לספק הגדרה אופציונלית של restricted_locations לקטגוריות או לנתיבים נוספים שבהם אפשר ליצור מרחבי שמות וטבלאות. אם מציינים נתיב משנה (כמו gs://my-bucket/path), כל המשאבים שנוצרים באמצעות ההגדרה הזו חייבים להיות בנתיב הזה (לדוגמה, gs://my-bucket/another/path לא יכול לארח מרחבי שמות או טבלאות).
  • דרישות לגבי קבוצת האזורים הגיאוגרפיים: למרות שהקטגוריות יכולות להיות בפרויקטים שונים, באזורים שונים ועם הגדרות שונות (כמו אזור יחיד, שני אזורים או מספר אזורים), כל המיקומים של Cloud Storage במיקום ברירת המחדל ובמיקומים המוגבלים חייבים להיות באותה קבוצת אזורים גיאוגרפיים (כמו ארה"ב, אירופה, קנדה או אסיה). לדוגמה, אי אפשר להגדיר קטגוריה במספר אזורים בארה"ב עם קטגוריה באירופה או בקנדה.
  • כמה קטלוגים לכל קטגוריה: אתם יכולים להגדיר כמה קטלוגים שיפנו לאותה קטגוריה (לדוגמה, באמצעות מיקומי ברירת מחדל שונים או מיקומים מוגבלים). עם זאת, אנחנו לא ממליצים על ההגדרה הזו כי היא עלולה לגרום להתנגשויות במטא-נתונים, לדריסת נתונים בטעות או לבעיות אבטחה כמו דליפת הרשאות.
  • מרחבי שמות: מאפשרים לציין מיקומים של מרחבי שמות בהתאמה אישית, כל עוד הם נמצאים בנתיב שהוגדר במיקומי ברירת המחדל או במיקומים המוגבלים. שימו לב: לטבלאות שנוצרות בקטלוגים האלה תתווסף באופן אוטומטי סיומת של מחרוזת אקראית לנתיבים הפיזיים שלהן, כדי למנוע התנגשויות (לדוגמה, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). מידע נוסף זמין במאמר כללי אבטחה וניהול של טבלאות.

קטלוג עם קטגוריה אחת

זו הגישה הקודמת, שבה הקטלוג מנהל ישירות את המטא-נתונים ואת קובצי הנתונים של Apache Iceberg בקטגוריה אחת של Cloud Storage (gs://) שאתם מציינים. ב-API הבסיסי, זה תואם להגדרה CATALOG_TYPE_GCS_BUCKET.

בקטלוגים עם קטגוריה אחת, שם הקטלוג מוגדר לשם הקטגוריה.

לדוגמה, אם נותנים לקטגוריה את השם iceberg-bucket, גם הקטלוג וגם הקטגוריה יקבלו את השם הזה. השתמשו בשם הזה כשאתם שולחים שאילתות לקטלוג ב-BigQuery באמצעות תחביר P.C.N.T, לדוגמה, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

שיקולים:

  • מגבלות על סוגי קטלוגים מדור קודם. לא מומלץ להשתמש בהגדרת הקטגוריה היחידה הקודמת בפרויקטים חדשים. להגדרה הזו יש כמה מגבלות קריטיות:

    • שם הקטלוג: נעול לשם של הקטגוריה הבסיסית ב-Cloud Storage.
    • פרויקט: נעול לפרויקט של הקטגוריה (אין תמיכה בקטלוגים של פרויקטים שונים).
    • אזור: נגזר אך ורק מהמיקום של הקטגוריה ואי אפשר להתאים אותו אישית.
    • אחסון: הגבלת הקטלוג לקטגוריה אחת (אין מיקומים מוגבלים).

  • הגדרת מחסן נתונים של לקוח (gs://): כשמגדירים לקוח Iceberg לקטלוג של קטגוריה אחת, מציינים את הנתיב של הקטגוריה ב-Cloud Storage‏ (gs://CLOUD_STORAGE_BUCKET_NAME) בתור המיקום של מחסן הנתונים.

  • הגבלה של קטלוג אחד לכל קטגוריה: בסוג הקטלוג הקודם הזה, אפשר להגדיר רק קטלוג אחד לכל קטגוריה, ושם הקטלוג חייב להתאים לשם הקטגוריה.

  • שדרוג לקטלוג עם כמה קטגוריות (מומלץ): אתם יכולים לשדרג קטלוג קיים עם קטגוריה אחת לקטלוג עם כמה קטגוריות (מומלץ). הקטלוג המשודרג שומר על השם של הקטגוריה המקורית. אחרי זה, אתם יכולים לשייך כמה קטגוריות לקטלוג ולהגדיר מיקומים מוגבלים.

אזורים של קטגוריות וקטלוגים

האזור של נקודת הקצה של הקטלוג בקטלוג הייעודי לזמן ריצה של Lakehouse נקבע לפי האזור של הקטגוריה של Cloud Storage הבסיסית:

  • קטלוג עם כמה קטגוריות (מומלץ): האזור של הקטלוג נגזר מהקטגוריה שהוגדרה ב-default_location.
  • קטלוג בקטגוריה אחת: אזור הקטלוג נגזר אך ורק מהקטגוריה שמשויכת לקטלוג, ואי אפשר להתאים אותו אישית.

האזור הממופה של הקטלוג משתנה בהתאם לסוג האזור של הקטגוריה:

  • אזור יחיד: האזור של הקטלוג תואם בדיוק לאזור של הקטגוריה.
  • שני אזורים: אזור הקטלוג תואם לשני האזורים של הקטגוריה (למשל ASIA1 או NAM4).
  • מספר אזורים: האזור של הקטלוג מוגדר למיקום אזורי ספציפי בתוך הדומיין הגיאוגרפי של מספר האזורים. כברירת מחדל, יכול להיות שהמיקום לא יתאים למיקומים נפוצים במספר אזורים ב-BigQuery, כמו US ו-EU (לדוגמה, קטגוריה במספר אזורים ב-US ממופה ל-us-central1 או ל-us-east4).

כש-BigQuery מריץ שאילתה על טבלאות בקטלוגים האלה, הוא מנתב את השאילתה לאזור הראשי של הקטלוג. אם אתם שולחים שאילתות לטבלאות באזור וירטואלי ספציפי (כמו US או EU) והמטא-נתונים של הקטלוג לא נמצאים במיקום הזה, השאילתה נכשלת.

אזורים ראשיים במספר אזורים

כדי לאפשר ל-BigQuery לשלוח שאילתות לטבלאות הקטלוג מהאזור US או מהאזור EU במספר אזורים, צריך לציין את US או את EU כאזור הראשי כשיוצרים את הקטלוג.

אפשר לציין מספר אזורים (US או EU) בתור האזור הראשי בהגדרות הבאות:

אם הקטגוריה default_location:

  • קטגוריה במספר אזורים ב-US או ב-EU.
  • קטגוריה באזור יחיד בתוך מספר האזורים האלה (כמו us-central1 או europe-west4).
  • קטגוריה בשני אזורים או בשני אזורים בהתאמה אישית באותם אזורים (כמו NAM4 או EUR4).

הרפליקה הראשית מוגדרת כשיוצרים את הקטלוג, אבל אפשר לבצע יתירות כשל באופן דינמי באמצעות קריאה ל-FailoverCatalog. מידע נוסף זמין במאמר יצירת קטלוג.

כדי לנתב בקשות ישירות לאזור ספציפי בהתאם לדרישות של מיקום אחסון הנתונים וריבונות הנתונים, אתם יכולים להשתמש בנקודות קצה אזוריות (biglake.LOCATION.rep.googleapis.com). מידע נוסף זמין במאמר נקודות קצה אזוריות של Lakehouse.

שליחת שאילתות לקטלוגים מ-BigQuery

כששולחים שאילתות לטבלאות של קטלוג ייעודי לזמן ריצה ב-Lakehouse מ-BigQuery, משתמשים במבנה שם שמורכב מארבעה חלקים, שלרוב נקרא P.C.N.T:

  • ‫Project: מזהה הפרויקט ב- Google Cloud שהקטלוג נמצא בבעלותו.
  • ‫Catalog: השם של הקטלוג הייעודי לזמן ריצה ב-Lakehouse.
  • מרחב שמות: מרחב השמות של Apache Iceberg (שווה ערך למערך נתונים ב-BigQuery).
  • טבלה: שם הטבלה.

לדוגמה, my-project.lakehouse-catalog-id.my-namespace.my-table.

המאמרים הבאים