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

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

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

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

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

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

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

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

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

נקודת הקצה של קטלוג 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://).
  • מספר מקסימלי של קטגוריות: אפשר לציין עד 15 קטגוריות לכל קטלוג.
  • מיקום ברירת מחדל: מציינים נתיב לקטגוריה (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 במיקום ברירת המחדל ובמיקומים המוגבלים צריכים להיות באותה קבוצת אזורים גיאוגרפיים (למשל ארה"ב, אירופה, קנדה או אסיה). לדוגמה, אי אפשר להגדיר קטגוריה במספר אזורים בארה"ב עם קטגוריה באירופה או בקנדה.
  • כמה קטלוגים בכל דלי: אתם יכולים להגדיר כמה קטלוגים שיצביעו לאותו דלי (לדוגמה, באמצעות מיקומי ברירת מחדל שונים או מיקומים מוגבלים). עם זאת, לא מומלץ להשתמש בהגדרה הזו כי היא עלולה להוביל לקונפליקטים במטא-נתונים, לדריסת נתונים בטעות או לבעיות אבטחה כמו דליפת הרשאות.
  • ‫Namespaces (מרחבי שמות): מאפשרים לציין מיקומים מותאמים אישית של מרחבי שמות, כל עוד הם נמצאים בנתיב שהוגדר במיקומים שמוגדרים כברירת מחדל או במיקומים מוגבלים. שימו לב: לטבלאות שנוצרות בקטלוגים האלה יצורף אוטומטית מחרוזת אקראית לסיומת של הנתיבים הפיזיים שלהן כדי למנוע התנגשויות (לדוגמה, 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 הוא:

  • קטגוריית Multi-Region‏ 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.
  • Namespace: מרחב השמות של Apache Iceberg (שווה ערך למערך נתונים ב-BigQuery).
  • Table: שם הטבלה.

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

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