יצירת קטלוג

הקטלוג הייעודי לזמן ריצה של Lakehouse מאפשר ליצור נקודות קצה של קטלוג ב-Lakehouse ללא גבולות.

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

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

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the BigLake API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

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

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

• יוצרים קטלוג:
  • אדמין BigLake ‏(roles/biglake.admin) בפרויקט
  • אדמין באחסון (roles/storage.admin) בפרויקט
• יצירת טבלאות (רישום): אדמין BigLake (roles/biglake.admin) בפרויקט. כדי לרשום טבלאות, צריך הרשאה ספציפית לרישום טבלאות (biglake.tables.register), שנכללת בתפקיד האדמין ב-BigLake.
• משתמשים בחשבון השירות של הקטלוג שהוקצה אוטומטית במצב הפצת פרטי כניסה: משתמש באובייקטים של אחסון (roles/storage.objectUser) בקטגוריות היעד של Cloud Storage. אחרי שיוצרים את הקטלוג, מקצים באופן מפורש את התפקיד Storage Object User‏ (roles/storage.objectUser) בקטגוריות האחסון לחשבון השירות שהוקצה באופן אוטומטי.

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

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

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

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

יצירת קטלוג

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

הערה: כשיוצרים או מנהלים קטלוג עם כמה קטגוריות ב-Google Cloud, צריך לציין את הנתיבים ב-Cloud Storage (gs://) למיקומי האחסון שמוגדרים כברירת מחדל ולמיקומי האחסון המוגבלים. הפורמט של ה-URI של bl://projects/PROJECT_ID/catalogs/CATALOG_ID משמש רק במהלך הגדרת הלקוח כדי לזהות את מחסן הנתונים של הקטלוג כשמתחברים ממנועי שאילתות (כמו Apache Spark או Trino).

המסוף

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

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

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

   מעבר אל Lakehouse

2. לוחצים על Create catalog ובוחרים באפשרות Lakehouse runtime catalog.

3. בשדה Catalog type, בוחרים באפשרות Iceberg Rest Catalog.

4. בקטע Lakehouse catalog bucket options, בוחרים באפשרות Multiple bucket catalog.

5. בשדה Default Catalog Cloud Storage path, מזינים את הנתיב של Cloud Storage שבו רוצים להשתמש בקטלוג, או מחפשים אותו.

6. בשדה מזהה קטלוג, מזינים שם מותאם אישית לקטלוג.

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

8. לוחצים על Continue.

9. בשלב Data paths, אם רוצים להוסיף עוד נתיבים של Cloud Storage, לוחצים על Add path ומזינים נתיב או מחפשים אותו.

10. לוחצים על Continue.

11. בקטע שיטת אימות, בוחרים באפשרות End-user credentials או באפשרות Credential vending mode.

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

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

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

13. אם בחרתם באפשרות Credential vending mode, בצעו את השלבים הנוספים הבאים:

    1. בקטע Authentication method, לוחצים על Set bucket permissions (או על Set permissions for buckets אם בקטלוג יש יותר מקטגוריה אחת).
    2. בתיבת הדו-שיח, לוחצים על אישור.

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

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

1. בדף Lakehouse, לוחצים על Create catalog ובוחרים באפשרות Lakehouse runtime catalog.
2. בשדה Catalog type, בוחרים באפשרות Iceberg Rest Catalog או Hive Metastore.
3. אם בחרתם באפשרות Iceberg Rest Catalog, בקטע Lakehouse catalog bucket options בוחרים באפשרות Single bucket catalog.
4. בשדה Default Catalog Cloud Storage bucket (או Default Catalog Cloud Storage path לנקודת קצה של קטלוג Apache Hive), מזינים את הקטגוריה של Cloud Storage שבה רוצים להשתמש עם הקטלוג, או מחפשים אותה. בקטלוג עם קטגוריה אחת, אפשר להגדיר רק קטלוג אחד לכל קטגוריה, ושם הקטלוג תואם לשם הקטגוריה.
5. לוחצים על Continue.
6. בקטע שיטת אימות, בוחרים באפשרות End-user credentials או באפשרות Credential vending mode.
7. לוחצים על יצירה.
8. אם בחרתם באפשרות Credential vending mode, בצעו את השלבים הנוספים הבאים:
   1. בקטע שיטת אימות, לוחצים על Set bucket permissions.
   2. בתיבת הדו-שיח, לוחצים על אישור.

gcloud

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

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

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

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

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

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

• ‫CREDENTIAL_MODE: שיטת האימות. משתמשים ב-end-user לפרטי כניסה של משתמשי קצה או ב-vended-credentials למצב של הפצת פרטי כניסה. אם מציינים את הערך end-user, הקטלוג הייעודי לזמן ריצה של Lakehouse לא מנהל באופן אוטומטי את הטבלאות בקטלוג. אי אפשר להפעיל משימות של ניהול טבלאות, כמו דחיסה ותפוגה של תמונת מצב.

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

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

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

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

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

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

כדי ליצור קטלוג עם קטגוריה אחת, מריצים את הפקודה הבאה:

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

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

• ‫CATALOG_NAME: שם לקטלוג. בקטלוגים עם קטגוריה אחת, המזהה הזה תואם למזהה הקטגוריה של Cloud Storage שמשמשת בקטלוג.
• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud.
• ‫CREDENTIAL_MODE: שיטת האימות. משתמשים ב-end-user לפרטי כניסה של משתמשי קצה או ב-vended-credentials למצב של הפצת פרטי כניסה.

REST

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

כדי ליצור נקודת קצה לניהול קטלוגים באמצעות ה-API בארכיטקטורת REST, שולחים בקשת POST לנקודת הקצה CreateIcebergCatalog:

POST /iceberg/v1/restcatalog/extensions/projects/PROJECT_ID/catalogs?iceberg-catalog-id=CATALOG_ID

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

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

• ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud .
• ‫CATALOG_ID: המזהה של הקטלוג הייעודי לזמן ריצה ב-Lakehouse.