הגדרת נקודת הקצה של קטלוג REST של Iceberg Lakehouse

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

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

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

לעומת זאת, נקודת הקצה Custom Apache Iceberg catalog for BigQuery היא שילוב מוקדם יותר. אפשר להמשיך להשתמש בו בתהליכי עבודה קיימים, אבל קטלוג REST מציע חוויה סטנדרטית יותר ועשירה בתכונות.

לפני שמתחילים

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

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

  1. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

  2. מפעילים את BigLake API.

    תפקידים שנדרשים להפעלת ממשקי API

    כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של שימוש בשירות' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

    להפעלת ה-API

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לשימוש בנקודת הקצה של קטלוג Apache Iceberg REST בקטלוג של זמן הריצה של Lakehouse, צריך לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

  • ביצוע משימות אדמיניסטרטיביות, כמו ניהול גישת משתמשים לקטלוג, גישה לאחסון ומצב מכירת האישורים של הקטלוג:
  • רישום טבלאות בקטלוג BigLake: BigLake Admin (roles/biglake.admin) בפרויקט.
  • קריאת נתוני טבלה במצב של מכירת אישורים: BigLake Viewer (roles/biglake.viewer) בפרויקט. אם אתם משתמשים במנועי שאילתות כמו Managed Service for Apache Spark או Dataflow כדי לקרוא נתונים בטבלה, אתם צריכים להעניק את התפקיד הזה לחשבון השירות שבו אתם משתמשים כדי להריץ משימות במנוע הזה.
  • כתיבת נתוני טבלה במצב של מכירת אישורים: BigLake Editor (roles/biglake.editor) בפרויקט. אם אתם משתמשים במנועי שאילתות כמו Managed Service for Apache Spark או Dataflow כדי לכתוב נתוני טבלה, אתם צריכים להעניק את התפקיד הזה לחשבון השירות שבו אתם משתמשים כדי להריץ משימות במנוע הזה.
  • שימוש בחשבון השירות של קטלוג זמן הריצה של Lakehouse שהוקצה אוטומטית במצב של מכירת פרטי כניסה: משתמש באובייקט אחסון (roles/storage.objectUser) בכל הקטגוריות המשויכות ב-Cloud Storage. אחרי שיוצרים את הקטלוג, צריך להעניק במפורש את התפקיד 'משתמש באובייקט אחסון' (roles/storage.objectUser) בכל קטגוריות האחסון המשויכות לחשבון השירות של הקטלוג בזמן הריצה של Lakehouse שהוקצה אוטומטית.
  • קריאת משאבי קטלוג ונתוני טבלה במצב שבו לא מונפקים אישורים:
  • ניהול משאבי קטלוג וכתיבת נתוני טבלה במצב שאינו 'הקצאת אישורים':

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

מגבלות

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

מגבלות כלליות

  • יש תמיכה בטבלאות Apache Iceberg V2 (זמינות כללית) ובטבלאות V3 (גרסת Preview). אין תמיכה בטבלאות Iceberg V1. לפני שמשתמשים בטבלאות קיימות מגרסה 1 עם נקודת הקצה של קטלוג Apache Iceberg REST, צריך לשדרג אותן לגרסה נתמכת.
  • יש תמיכה ב-Trino רק בשילוב עם פדרציית קטלוגים של BigQuery כשמשתמשים בגרסאות 2.3.16 ואילך של תמונת Managed Service for Apache Spark ב-Compute Engine 2.3.
  • כשמשתמשים במצב של מכירת פרטי כניסה, אם מנוע השאילתות מאפשר להגדיר את המאפיין io-impl לחיבור קטלוג, צריך להגדיר אותו ל-org.apache.iceberg.gcp.gcs.GCSFileIO.
  • כרגע אין תמיכה בקטגוריות עם מרחב שמות היררכי במצב של הקצאת פרטי כניסה.

מגבלות על טבלאות

  • אי אפשר ליצור או לשנות טבלאות בנקודת הקצה של קטלוג Apache Iceberg REST באמצעות הצהרות של שפת הגדרת נתונים (DDL) או שפת מניפולציה של נתונים (DML) ב-BigQuery. אפשר לשנות את הטבלאות האלה באמצעות BigQuery API (עם כלי שורת הפקודה של BigQuery או ספריות לקוח), אבל יש סיכון ששינויים כאלה לא יהיו תואמים למנוע החיצוני.
  • טבלאות שמנוהלות דרך נקודת הקצה של קטלוג Apache Iceberg REST לא תומכות בבקרת גישה פרטנית (FGAC), כמו אבטחה ברמת השורה וברמת העמודה.
  • אסור להגדיר את מאפייני טבלת Iceberg‏ write.data.path או write.metadata.path לערכים שונים מערכי ברירת המחדל שלהם.
  • נתיבי הטבלה צריכים להיות מוטמעים בנתיב של מרחב השמות הראשי (לדוגמה, gs://{namespace_path}/.../{table_name}). כדי למנוע התנגשויות ולשפר את האבטחה, סיומת של מחרוזת אקראית מצורפת אוטומטית למיקום שמתקבל (לדוגמה, gs://{namespace_path}/{table_name}/{random_suffix}).

מגבלות נתונים

  • יש תמיכה רק בקובצי Parquet. למידע נוסף על האופן שבו BigQuery מטפל בקובצי Parquet, אפשר לעיין במאמר בנושא טעינת נתוני Parquet מ-Cloud Storage.
  • גודל הקובץ של Iceberg metadata.json מוגבל ל-1MB. כדי לבקש להגדיל את המגבלה הזו, אפשר לפנות לצוות התמיכה בחשבון Google.

מגבלות על שאילתות

  • אי אפשר לשלוח שאילתות לטבלאות מטא-נתונים של Apache Iceberg (כמו .snapshots או .files) ב-BigQuery באמצעות מזהי שמות בני חמישה חלקים. אפשר לשלוח שאילתות לטבלאות האלה באמצעות Spark.

הגדרת נקודת הקצה של קטלוג REST של Iceberg

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

אלה השלבים הכלליים שצריך לבצע כשמשתמשים בנקודת הקצה של קטלוג Apache Iceberg REST בקטלוג של זמן הריצה של Lakehouse:

  1. על סמך הסקירה הכללית של נקודת הקצה של קטלוג Iceberg REST, בוחרים את סוג הקטלוג. אפשר להגדיר קטלוג מרובה קטגוריות (bl://) (מומלץ) או קטלוג של קטגוריה אחת (gs://).
  2. יוצרים קטלוג שמצביע על מיקום המחסן.
  3. מגדירים את נקודת הקצה של קטלוג REST של Apache Iceberg באפליקציית הלקוח.
  4. יוצרים מרחב שמות או סכימה כדי לארגן את הטבלאות.
  5. יוצרים טבלאות ומריצים עליהן שאילתות באמצעות הלקוח שהגדרתם.

לתשומת ליבכם

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

מצב פרטי הכניסה (היקף)

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

  • פרטי כניסה של משתמש קצה: הקטלוג מעביר את הזהות של משתמש הקצה שניגש אליו אל Cloud Storage לצורך בדיקות הרשאות.

  • מצב של מכירת אישורים: מנגנון להענקת הרשאות גישה לאחסון שמאפשר למנהלי קטלוג של Lakehouse runtime לשלוט בהרשאות ישירות במשאבי קטלוג של Lakehouse runtime, וכך לבטל את הצורך של משתמשי הקטלוג בגישה ישירה לקטגוריות של Cloud Storage. הוא מאפשר לאדמינים של Lakehouse ב-Google Cloud להעניק למשתמשים הרשאות לקבצי נתונים ספציפיים.

סוג הקטגוריה

אתם יכולים ליצור קטלוג עם מאגר אחד או קטלוג עם כמה מאגרים.

  • כמה קטגוריות (bl://) (מומלץ): ההגדרה הזו מאפשרת לקטלוג לשייך כמה קטגוריות, ולקבוע שם לקטלוג בלי קשר לשם של קטגוריה כלשהי. אין תמיכה בקטלוגים עם כמה מאגרי מידע במסוף Google Cloud .
  • קטגוריה אחת (gs://): ההגדרה הזו מגבילה את הקטלוג לקטגוריה אחת ונועלת את שם הקטלוג לשם הקטגוריה. לא מומלץ להשתמש בהם בפרויקטים חדשים.

מיקום

לפני שיוצרים קטלוג, חשוב לעיין בדרישות בנוגע למיקומים.

  • כשיוצרים מרחב שמות, הוא משתמש אוטומטית באותו אזור כמו הקטלוג.

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

יצירת קטלוג

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

פרטי הכניסה של משתמשי הקצה

המסוף

  1. פותחים את הדף Lakehouse במסוף Google Cloud .

    מעבר אל Lakehouse

  2. לוחצים על יצירת קטלוג.

  3. בקטע סוג הקטלוג, בוחרים באפשרות קטגוריה של Cloud Storage.

  4. מזינים או מחפשים את הקטגוריה של Cloud Storage שבה רוצים להשתמש בקטלוג (בקטלוג של קטגוריה אחת (gs://), יכול להיות רק קטלוג אחד לכל קטגוריה, והשם של הקטלוג זהה לשם של הקטגוריה).

  5. בקטע שיטת אימות, בוחרים באפשרות פרטי כניסה של משתמש קצה.

  6. לוחצים על יצירה.

gcloud

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

ההגדרה הזו מאפשרת לקטלוג לשייך כמה קטגוריות, ומאפשרת לתת לקטלוג שם שלא תלוי בשם של אף קטגוריה.

כדי ליצור קטלוג עם כמה קטגוריות (bl://) (מומלץ), מריצים את הפקודה gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

יצירת קטלוג של דלי אחד (gs://)

כדי ליצור קטלוג של קטגוריה אחת (gs://), מריצים את הפקודה הבאה:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: שם לקטלוג. בקטלוגים מרובי-קטגוריות (bl://) (מומלץ), זהו שם הקטלוג המותאם אישית. בקטלוגים של קטגוריה אחת (gs://), הערך הזה זהה למזהה הקטגוריה ב-Cloud Storage שמשמש עם קטלוג REST. השם הזה משמש גם כמזהה הקטלוג כששולחים שאילתות לטבלאות האלה מ-BigQuery.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫DEFAULT_LOCATION: ציון מיקום האחסון שמוגדר כברירת מחדל לקטלוג. אפשר לציין קטגוריה (gs://my-bucket) או נתיב משנה (gs://my-bucket/path). כל מרחבי השמות והטבלאות בקטלוג צריכים להיות בנתיב שצוין. לדוגמה, אם מציינים gs://my-bucket/path, אי אפשר ליצור מרחבי שמות או טבלאות מתחת ל-gs://my-bucket/another/path.
  • ‫RESTRICTED_LOCATIONS: (אופציונלי) רשימה מופרדת בפסיקים של מיקומי אחסון מורשים נוספים, בפורמט gs://my-bucket-1/...,gs://my-bucket-2/.... אם מציינים נתיב (למשל gs://my-bucket/path), כל מרחבי השמות או הטבלאות בתוך הקטגוריה הזו צריכים להיות מתחת לנתיב הזה. כל מיקומי האחסון בענן שהוגדרו במיקום ברירת המחדל ובמיקומים המוגבלים צריכים להיות באותה קבוצה של אזורים גיאוגרפיים או באותה סמכות שיפוט (למשל ארצות הברית, אירופה, קנדה או אסיה). לדוגמה, אי אפשר לערבב בין באקט בארה"ב לבין באקט באירופה. רשימת המיקומים הנתמכים מופיעה במאמר מיקומי Lakehouse. אזהרת אבטחה: כדי למנוע חשיפה לא מורשית של פרטי כניסה, מומלץ להימנע מהגדרת נתיבים חופפים עם קטלוגים אחרים. מידע נוסף זמין במאמר אחסון בכמה קטגוריות.
  • ‫LOCATION: (אופציונלי) האזור הראשי של הקטלוג כדי להבטיח יכולת פעולה הדדית עם BigQuery. לקטגוריות ב-Cloud Storage באזור ארה"ב (לדוגמה, US או us-central1) או באזור האיחוד האירופי (לדוגמה, EU או europe-west4), צריך לציין US או EU בהתאמה כדי לוודא שאפשר לגשת לקטלוג ולבצע בו שאילתות ממספר האזורים התואם ב-BigQuery. מידע נוסף זמין במאמר אזורים של קטלוגים וקטגוריות.

מצב מכירת פרטי כניסה

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

חשבון השירות של קטלוג זמן הריצה של Lakehouse שמוקצה אוטומטית צריך את התפקיד 'משתמש באובייקט אחסון' (roles/storage.objectUser) באופן מפורש בכל הקטגוריות המשויכות ב-Cloud Storage. כברירת מחדל, אין לו גישה בכלל. בלי התפקיד הזה, לפרטי הכניסה שסופקו לא יהיה היקף מספיק כדי לבצע כתיבות לאחסון. אם אתם משתמשים בכלים כמו gcloud או Terraform, אתם צריכים להעניק את התפקיד הזה באופן ידני.

המסוף

  1. במסוף Google Cloud , פותחים את הדף Lakehouse.

    מעבר אל Lakehouse

  2. לוחצים על יצירת קטלוג. ייפתח הדף Create catalog.

  3. בקטע סוג הקטלוג, בוחרים באפשרות קטגוריה של Cloud Storage.

  4. מזינים או מחפשים את הקטגוריה של Cloud Storage שבה רוצים להשתמש בקטלוג (בקטלוג של קטגוריה אחת (gs://), יכול להיות רק קטלוג אחד לכל קטגוריה, והשם של הקטלוג זהה לשם של הקטגוריה).

  5. בקטע שיטת אימות, בוחרים באפשרות מצב מכירת אישורים.

  6. לוחצים על יצירה.

    הקטלוג נוצר והדף פרטי הקטלוג נפתח.

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

  8. בתיבת הדו-שיח, לוחצים על אישור.

    כך מוודאים שלחשבון השירות של הקטלוג יש את התפקיד 'משתמש באובייקט אחסון' בכל מאגרי האחסון המשויכים.

gcloud

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

ההגדרה הזו מאפשרת לקטלוג לשייך כמה קטגוריות, ומאפשרת לתת לקטלוג שם שלא תלוי בשם של אף קטגוריה.

כדי ליצור קטלוג עם כמה קטגוריות (bl://) (מומלץ), מריצים את הפקודה gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

יצירת קטלוג של דלי אחד (gs://)

כדי ליצור קטלוג של קטגוריה אחת (gs://), מריצים את הפקודה הבאה:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: שם לקטלוג. בקטלוגים מרובי-מאגרים (bl://) (מומלץ), זהו השם של הקטלוג בהתאמה אישית. בקטלוגים של קטגוריה אחת (gs://), הערך הזה זהה למזהה הקטגוריה ב-Cloud Storage שמשמש עם קטלוג REST. השם הזה משמש גם כמזהה הקטלוג כששולחים שאילתות לטבלאות האלה מ-BigQuery.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫DEFAULT_LOCATION: ציון מיקום האחסון שמוגדר כברירת מחדל לקטלוג. אפשר לציין קטגוריה (gs://my-bucket) או נתיב משנה (gs://my-bucket/path). כל מרחבי השמות והטבלאות בקטלוג צריכים להיות בנתיב שצוין. לדוגמה, אם מציינים gs://my-bucket/path, אי אפשר ליצור מרחבי שמות או טבלאות מתחת ל-gs://my-bucket/another/path.
  • ‫RESTRICTED_LOCATIONS: (אופציונלי) רשימה מופרדת בפסיקים של מיקומי אחסון מורשים נוספים, בפורמט gs://my-bucket-1/...,gs://my-bucket-2/.... אם מציינים נתיב (למשל gs://my-bucket/path), כל מרחבי השמות או הטבלאות בתוך הקטגוריה הזו צריכים להיות מתחת לנתיב הזה. כל מיקומי האחסון בענן שהוגדרו במיקום ברירת המחדל ובמיקומים המוגבלים צריכים להיות באותה קבוצה של אזורים גיאוגרפיים או באותה סמכות שיפוט (למשל ארצות הברית, אירופה, קנדה או אסיה). לדוגמה, אי אפשר לערבב בין באקט בארה"ב לבין באקט באירופה. רשימת המיקומים הנתמכים מופיעה במאמר מיקומי Lakehouse. אזהרת אבטחה: כדי למנוע חשיפה לא מורשית של פרטי כניסה, מומלץ להימנע מהגדרת נתיבים חופפים עם קטלוגים אחרים. מידע נוסף זמין במאמר אחסון בכמה קטגוריות.

  • ‫LOCATION: (אופציונלי) האזור הראשי של הקטלוג כדי להבטיח יכולת פעולה הדדית עם BigQuery. לקטגוריות ב-Cloud Storage באזור ארה"ב (לדוגמה, US או us-central1) או באזור האיחוד האירופי (לדוגמה, EU או europe-west4), צריך לציין US או EU בהתאמה כדי לוודא שאפשר לגשת לקטלוג ולבצע בו שאילתות ממספר האזורים התואם ב-BigQuery. מידע נוסף זמין במאמר אזורים של קטלוגים וקטגוריות.

    אחרי שיוצרים את הקטלוג, צריך להעניק באופן מפורש את התפקיד משתמש באובייקט אחסון (roles/storage.objectUser) בכל קטגוריות האחסון המשויכות לחשבון השירות של קטלוג זמן הריצה של Lakehouse שהוקצה אוטומטית.

הגדרת אפליקציית לקוח

אחרי שיוצרים קטלוג, מגדירים את אפליקציית הלקוח כך שתשתמש בו. בדוגמאות האלה מוסבר איך להגדיר את התכונה עם או בלי מכירת אישורים.

אשכול

יוצרים אשכול של Managed Service for Apache Spark ב-Compute Engine באמצעות מאפייני תצורה פשוטים (מומלץ), או על ידי ציון מאפיינים באופן ידני.

יוצרים אשכול עם נכס הקטלוג:

gcloud dataproc clusters create CLUSTER_NAME \
  --enable-component-gateway \
  --project=PROJECT_ID \
  --region=REGION \
  --optional-components=ICEBERG \
  --image-version=DATAPROC_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CLUSTER_NAME: שם לאשכול.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫REGION: האזור של אשכול Managed Service for Apache Spark.
  • ‫DATAPROC_VERSION: גרסת התמונה של Managed Service for Apache Spark, לדוגמה, 2.3.
  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog). יכול להיות שזה יהיה אותו שם כמו CATALOG_ID.
  • ‫CATALOG_ID: המזהה של הקטלוג שיצרתם.

בקובץ האפליקציה של PySpark, יוצרים את SparkSession בלי לציין הגדרות של קטלוג:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

הגדרה ידנית

אם לא משתמשים במאפיין ההגדרה הפשוטה, יוצרים אשכול כמו שמתואר למעלה, אבל בלי הדגל --properties. לאחר מכן, מגדירים את SparkSession באופן ידני:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog).
  • ‫APP_NAME: שם להפעלת Spark.
  • ‫REST_API_VERSION: מוגדר ל-v1 לגרסה היציבה של ה-API.
  • ‫WAREHOUSE_PATH: הנתיב למחסן הנתונים. בקטלוגים של BigLake, משתמשים ב-bl://projects/PROJECT_ID/catalogs/CATALOG_ID. לגבי קטלוגים של קטגוריות ב-Cloud Storage, משתמשים ב-gs://CLOUD_STORAGE_BUCKET_NAME. כדי להשתמש בפדרציית קטלוגים ב-BigQuery, אפשר לעיין במאמר שימוש בפדרציית קטלוגים ב-BigQuery.
  • ‫PROJECT_ID: הפרויקט שמחויב על השימוש בנקודת הקצה של קטלוג REST של Apache Iceberg, שיכול להיות שונה מהפרויקט שבבעלותו נמצאת קטגוריית Cloud Storage. פרטים על הגדרת פרויקט כשמשתמשים ב-API ל-REST מופיעים במאמר פרמטרים של המערכת.

הגדרה באמצעות הקצאת הרשאות

כדי להשתמש בהקצאת הרשאות, צריך להשתמש בקטלוג במצב הקצאת הרשאות ולהוסיף את הכותרת X-Iceberg-Access-Delegation לבקשות קטלוג של Iceberg REST עם הערך vended-credentials. לשם כך, מוסיפים את השורה הבאה לבונה SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

דוגמה לשימוש ב-Credential Vending

בדוגמה הבאה מוגדר מנגנון השאילתות עם מכירת פרטי כניסה:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

מידע נוסף מופיע בקטע Headers in RESTCatalog במסמכי העזרה של Apache Iceberg.

שירותים מנוהלים לאשכולות Apache Spark תומכים בתהליכי הרשאה של Google ל-Apache Iceberg בגרסאות הבאות:

  • ‫Managed Service for Apache Spark בגרסאות של תמונות Compute Engine‏ 2.2 2.2.65 ואילך.
  • ‫Managed Service for Apache Spark ב-Compute Engine בגרסאות אימג' 2.3‏, 2.3.11 ואילך.

ללא שרת (serverless)

שליחת עומס עבודה של אצווה ב-PySpark אל Managed Service for Apache Spark באמצעות מאפייני הגדרה פשוטים (מומלץ), או על ידי ציון מאפיינים באופן ידני.

שולחים עבודת אצווה עם נכס הקטלוג:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PYSPARK_FILE: הנתיב של Cloud Storage אל קובץ אפליקציית PySpark.gs://
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
  • ‫REGION: האזור של עומס העבודה של עיבוד ברצף (batch processing) ב-Managed Service for Apache Spark.
  • ‫RUNTIME_VERSION: גרסת זמן הריצה של Managed Service for Apache Spark, לדוגמה 2.3.
  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog). יכול להיות שזה יהיה אותו שם כמו CATALOG_ID.
  • ‫CATALOG_ID: המזהה של הקטלוג שיצרתם.

בקובץ האפליקציה של PySpark, יוצרים את SparkSession בלי לציין הגדרות של קטלוג:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

הגדרה ידנית

אם לא משתמשים במאפיין ההגדרה הפשוטה, צריך לציין ידנית את הגדרות הקטלוג:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PYSPARK_FILE: הנתיב של Cloud Storage אל קובץ אפליקציית PySpark.gs://
  • ‫REGION: האזור של עומס העבודה של עיבוד ברצף (batch processing) ב-Managed Service for Apache Spark.
  • ‫RUNTIME_VERSION: גרסת זמן הריצה של Managed Service for Apache Spark, לדוגמה 2.3.
  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog).
  • ‫REST_API_VERSION: מוגדר ל-v1 לגרסה היציבה של ה-API.
  • ‫WAREHOUSE_PATH: הנתיב למחסן הנתונים. בקטלוגים של BigLake, משתמשים ב-bl://projects/PROJECT_ID/catalogs/CATALOG_ID. לגבי קטלוגים של קטגוריות ב-Cloud Storage, משתמשים ב-gs://CLOUD_STORAGE_BUCKET_NAME. כדי להשתמש בפדרציית קטלוגים ב-BigQuery, אפשר לעיין במאמר שימוש בפדרציית קטלוגים ב-BigQuery.
  • ‫PROJECT_ID: הפרויקט שמחויב על השימוש בנקודת הקצה של קטלוג REST של Apache Iceberg, שיכול להיות שונה מהפרויקט שבבעלותו נמצאת קטגוריית Cloud Storage. פרטים על הגדרת פרויקט כשמשתמשים ב-API ל-REST מופיעים במאמר פרמטרים של המערכת.

הגדרה באמצעות הקצאת הרשאות

כדי להשתמש בהקצאת אישורים, צריך להשתמש בקטלוג במצב הקצאת אישורים ולהוסיף את הכותרת X-Iceberg-Access-Delegation לבקשות של נקודת הקצה של קטלוג Apache Iceberg REST עם הערך vended-credentials. לשם כך, מוסיפים את השורה הבאה להגדרות של Managed Service for Apache Spark: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

דוגמה לשימוש ב-Credential Vending

בדוגמה הבאה מוגדר מנגנון השאילתות עם מכירת פרטי כניסה:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

מידע נוסף זמין בקטע Headers in RESTCatalog במאמרי העזרה של Apache Iceberg.

‫Managed Service for Apache Spark תומך בתהליכי הרשאה של Google ל-Apache Iceberg בגרסאות זמן הריצה הבאות:

  • ‫Managed Service for Apache Spark 2.2 runtimes 2.2.60 and later
  • ‫Managed Service for Apache Spark 2.3 runtimes 2.3.10 and later

Trino

כדי להשתמש ב-Trino עם נקודת הקצה של קטלוג REST של Apache Iceberg, צריך ליצור אשכול של Managed Service for Apache Spark עם רכיב Trino ולהגדיר את מאפייני הקטלוג באמצעות הדגל gcloud dataproc clusters create --properties. בדוגמה הבאה נוצר קטלוג Trino בשם CATALOG_NAME:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CLUSTER_NAME: שם לאשכול.
  • ‫REGION: האזור של אשכול Managed Service for Apache Spark.
  • ‫DATAPROC_VERSION: גרסת התמונה של Managed Service for Apache Spark, לדוגמה 2.2.
  • ‫NETWORK_ID: מזהה רשת האשכול. מידע נוסף זמין במאמר בנושא הגדרת רשת של אשכול Managed Service for Apache Spark.
  • ‫CATALOG_NAME: השם של קטלוג Trino באמצעות נקודת הקצה של קטלוג Apache Iceberg REST.
  • ‫REST_API_VERSION: מוגדר ל-v1 לגרסה היציבה של ה-API.
  • ‫WAREHOUSE_PATH: הנתיב למחסן הנתונים. בקטלוגים של BigLake, משתמשים ב-bl://projects/PROJECT_ID/catalogs/CATALOG_ID. לגבי קטלוגים של קטגוריות ב-Cloud Storage, משתמשים ב-gs://CLOUD_STORAGE_BUCKET_NAME.
  • ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud שבו רוצים להשתמש בקטלוג של זמן הריצה של Lakehouse.

אחרי שיוצרים את האשכול, מתחברים למופע ה-VM הראשי ומשתמשים ב-Trino CLI:

trino --catalog=CATALOG_NAME

‫Managed Service for Apache Spark Trino תומך בתהליכי הרשאה של Google ל-Apache Iceberg בגרסאות הבאות:

  • ‫Managed Service for Apache Spark בגרסאות זמן ריצה של Compute Engine‏ 2.2 2.2.65 ואילך
  • ‫Managed Service for Apache Spark ב-Compute Engine גרסאות זמן ריצה 2.3‏ 2.3.11 ואילך
  • אין תמיכה ב-Managed Service for Apache Spark ב-Compute Engine 3.0.

הגדרה באמצעות הקצאת הרשאות

הקצאת אישורים נתמכת רק ב-Trino מגרסה 481 ואילך.

‫Apache Iceberg 1.10 ואילך

בגרסאות 1.10 ואילך של Apache Iceberg עם קוד פתוח יש תמיכה מובנית בזרימות הרשאות של Google ב-GoogleAuthManager. בדוגמה הבאה מוצג אופן ההגדרה של Spark לשימוש בנקודת הקצה של קטלוג Apache Iceberg REST.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog).
  • ‫APP_NAME: שם להפעלת Spark.
  • ‫REST_API_VERSION: מוגדר ל-v1 לגרסה היציבה של ה-API.
  • ‫WAREHOUSE_PATH: הנתיב למחסן הנתונים. בקטלוגים של BigLake, משתמשים ב-bl://projects/PROJECT_ID/catalogs/CATALOG_ID. לגבי קטלוגים של קטגוריות ב-Cloud Storage, משתמשים ב-gs://CLOUD_STORAGE_BUCKET_NAME. כדי להשתמש בפדרציית קטלוגים ב-BigQuery, אפשר לעיין במאמר שימוש בפדרציית קטלוגים ב-BigQuery.
  • ‫PROJECT_ID: הפרויקט שמחויב על השימוש בנקודת הקצה של קטלוג REST של Apache Iceberg, שיכול להיות שונה מהפרויקט שבבעלותו נמצא מאגר Cloud Storage. פרטים על הגדרת פרויקט כשמשתמשים ב-API ל-REST מופיעים במאמר פרמטרים של המערכת.

הגדרה באמצעות הקצאת הרשאות

בדוגמה הקודמת לא נעשה שימוש במכירת אישורים. כדי להשתמש במנגנון למתן הרשאות, צריך להשתמש בקטלוג במצב של מתן הרשאות ולהוסיף את הכותרת X-Iceberg-Access-Delegation לבקשות של נקודת הקצה של קטלוג REST של Apache Iceberg עם הערך vended-credentials. לשם כך, מוסיפים את השורה הבאה לבונה SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

דוגמה לשימוש ב-Credential Vending

בדוגמה הבאה מוגדר מנגנון השאילתות עם מכירת פרטי כניסה:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

מידע נוסף זמין בקטע Headers in RESTCatalog במאמרי העזרה של Apache Iceberg.

גרסאות קודמות של Apache Iceberg

בגרסאות של Apache Iceberg עם קוד פתוח שקדמו לגרסה 1.10, אפשר להגדיר אימות OAuth רגיל על ידי הגדרת סשן עם הפרמטרים הבאים:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: שם לקטלוג המקומי של Spark (לדוגמה, my_catalog).
  • ‫APP_NAME: שם להפעלת Spark.
  • ‫REST_API_VERSION: מוגדר ל-v1 לגרסה היציבה של ה-API.
  • ‫WAREHOUSE_PATH: הנתיב למחסן הנתונים. בקטלוגים של BigLake, משתמשים ב-bl://projects/PROJECT_ID/catalogs/CATALOG_ID. לגבי קטלוגים של קטגוריות ב-Cloud Storage, משתמשים ב-gs://CLOUD_STORAGE_BUCKET_NAME. כדי להשתמש בפדרציית קטלוגים ב-BigQuery, אפשר לעיין במאמר שימוש בפדרציית קטלוגים ב-BigQuery.
  • ‫PROJECT_ID: הפרויקט שמחויב על השימוש בנקודת הקצה של קטלוג REST של Apache Iceberg, שיכול להיות שונה מהפרויקט שבבעלותו נמצא מאגר Cloud Storage. פרטים על הגדרת פרויקט כשמשתמשים ב-API ל-REST מופיעים במאמר פרמטרים של המערכת.
  • ‫TOKEN: אסימון האימות שלכם, שתקף לשעה אחת – לדוגמה, אסימון שנוצר באמצעות gcloud auth application-default print-access-token.

הגדרה באמצעות הקצאת הרשאות

בדוגמה הקודמת לא נעשה שימוש במכירת אישורים. כדי להשתמש במנגנון למתן הרשאות, צריך להשתמש בקטלוג במצב של מתן הרשאות ולהוסיף את הכותרת X-Iceberg-Access-Delegation לבקשות של נקודת הקצה של קטלוג REST של Apache Iceberg עם הערך vended-credentials. לשם כך, מוסיפים את השורה הבאה לבונה SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

דוגמה לשימוש ב-Credential Vending

בדוגמה הבאה מוגדר מנגנון השאילתות עם מכירת פרטי כניסה:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

מידע נוסף זמין בקטע Headers in RESTCatalog במאמרי העזרה של Apache Iceberg.

יצירת מרחב שמות או סכימה

אחרי שמגדירים את הלקוח, יוצרים מרחב שמות או סכימה כדי לארגן את הטבלאות. התחביר ליצירת מרחב שמות או סכימה משתנה בהתאם למנוע השאילתות. בדוגמאות הבאות מוסבר איך ליצור אותם באמצעות Spark ו-Trino.

המסוף

  1. במסוף Google Cloud , עוברים אל Lakehouse.

    מעבר אל Lakehouse

  2. בוחרים קטלוג קיים או יוצרים קטלוג חדש אם אין לכם קטלוג.

  3. בסרגל התפריטים, לוחצים על + יצירת מרחב שמות.

  4. בשדה Namespace name (שם מרחב השמות), מזינים שם ייחודי למרחב השמות.

  5. במאפיין מיקום, מציינים את הנתיב לשיוך למרחב השמות:

    • ‫Multi-bucket (bl://) (מומלץ): אפשר להגדיר כל מיקום מותאם אישית, כל עוד הוא נמצא במיקום שמותר על ידי הקטלוג (default_location או restricted_locations). אם לא מציינים מיקום, מרחב השמות נוצר במיקום ברירת המחדל של הקטלוג (לדוגמה, gs://{path-to-default-location}/{namespace_name}). שימו לב שאי אפשר לנהל קטלוגים מסוג Multi-bucket (bl://) (מומלץ) במסוף.
    • קטגוריה אחת (gs://): מיקום מרחב השמות עובר בירושה באופן אוטומטי מהקטגוריה היחידה בקטלוג.

  6. לוחצים על יצירה.

Spark

מחסן נתונים ב-Cloud Storage

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

מחליפים את NAMESPACE_NAME בשם של מרחב השמות.

Trino

מחסן נתונים ב-Cloud Storage

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

מחליפים את מה שכתוב בשדות הבאים:

  • ‫CATALOG_NAME: השם של קטלוג Trino באמצעות נקודת הקצה של קטלוג Apache Iceberg REST.
  • ‫SCHEMA_NAME: שם הסכימה.

שדרוג קטלוג

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

כדי לשדרג את הקטלוג, אפשר לעיין במאמר בנושא עדכון קטלוג.

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