יצירת טבלאות חיצוניות של Apache Iceberg

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

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

אדמינים ב-BigQuery יכולים לאכוף בקרת גישה ברמת השורה והעמודה, כולל מיסוך נתונים בטבלאות. במאמר הגדרת מדיניות בקרת גישה מוסבר איך להגדיר בקרת גישה ברמת הטבלה. מדיניות הגישה לטבלאות נאכפת גם כשמשתמשים ב-BigQuery Storage API כמקור נתונים לטבלה ב-Dataproc וב-Serverless Spark.

אפשר ליצור טבלאות חיצוניות בפורמט Iceberg בדרכים הבאות:

עם BigLake metastore (מומלץ ל- Google Cloud). מאגר המטא-נתונים של BigLake הוא מאגר מטא-נתונים מאוחד, מנוהל, בלי שרת (serverless) ומדרגי, שמקשר נתונים של lakehouse שמאוחסנים ב- Google Cloud לזמני ריצה מרובים, כולל מנועי קוד פתוח (כמו Apache Spark) ו-BigQuery.
עם AWS Glue Data Catalog (מומלץ ל-AWS). ‫AWS Glue היא השיטה המומלצת ל-AWS כי היא מאגר מטא-נתונים מרכזי שבו מגדירים את המבנה והמיקום של הנתונים שמאוחסנים בשירותי AWS שונים, והיא מספקת יכולות כמו גילוי סכימות אוטומטי ושילוב עם כלי ניתוח של AWS.
עם קובצי מטא-נתונים של Iceberg JSON (מומלץ ל-Azure). אם משתמשים בקובץ מטא-נתונים בפורמט JSON של Iceberg, צריך לעדכן ידנית את קובץ המטא-נתונים האחרון בכל פעם שיש עדכונים בטבלה. אתם יכולים להשתמש בפרוצדורה מאוחסנת ב-BigQuery עבור Apache Spark כדי ליצור טבלאות חיצוניות של Iceberg שמפנות לקובץ מטא-נתונים של Iceberg.

רשימה מלאה של המגבלות זמינה במאמר בנושא מגבלות.

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

Enable the BigQuery Connection and BigQuery Reservation APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

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

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

אדמין של BigQuery (roles/bigquery.admin)
אדמין של אובייקטים באחסון (roles/storage.objectAdmin)

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

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

ההרשאות הנדרשות

כדי ליצור טבלת Iceberg חיצונית, צריך את ההרשאות הבאות:

bigquery.tables.create
bigquery.connections.delegate
bigquery.jobs.create

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

יצירת טבלאות בעזרת מאגר המטא-נתונים של BigLake

מומלץ ליצור טבלאות חיצוניות ב-Iceberg באמצעות מאגר המטא-נתונים של BigLake.

יצירת טבלאות באמצעות קובץ מטא-נתונים

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

קבצי המטא-נתונים של טבלאות Iceberg נוצרים בקטגוריה של Cloud Storage שאתם מציינים כשאתם יוצרים טבלת Iceberg באמצעות Spark.

בוחרים באחת מהאפשרויות הבאות:

SQL

משתמשים בהצהרה CREATE EXTERNAL TABLE. בדוגמה הבאה נוצרת טבלה חיצונית בפורמט Iceberg בשם myexternal-table:

  CREATE EXTERNAL TABLE myexternal-table
  WITH CONNECTION `myproject.us.myconnection`
  OPTIONS (
         format = 'ICEBERG',
         uris = ["gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json"]
   )

מחליפים את הערך של uris בקובץ המטא-נתונים בפורמט JSON העדכני של תמונת מצב ספציפית של טבלה.

כדי להפעיל את האפשרות require partition filter (דרישת מסנן מחיצה), צריך להגדיר את הדגל require_partition_filter.

BQ

בסביבת שורת פקודה, משתמשים בפקודה bq mk --table עם העיטור @connection כדי לציין את החיבור שבו רוצים להשתמש בסוף הפרמטר --external_table_definition. כדי להפעיל את האפשרות 'דרישת מסנן מחיצה', משתמשים ב---require_partition_filter.

bq mk 

    --table 

    --external_table_definition=TABLE_FORMAT=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID 

    PROJECT_ID:DATASET.EXTERNAL_TABLE

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

‫TABLE_FORMAT: הפורמט של הטבלה שרוצים ליצור

במקרה הזה, ICEBERG.
‫URI: קובץ המטא-נתונים בפורמט JSON האחרון של תמונת מצב ספציפית של טבלה.

לדוגמה, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

ה-URI יכול להצביע גם על מיקום חיצוני בענן, כמו Amazon S3 או Azure Blob Storage.
- דוגמה ל-AWS: ‏ s3://mybucket/iceberg/metadata/1234.metadata.json.
- דוגמה ל-Azure: ‏ azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.
‫CONNECTION_PROJECT_ID: הפרויקט שמכיל את החיבור ליצירת טבלת Iceberg חיצונית – לדוגמה, myproject
‫CONNECTION_REGION: האזור שמכיל את החיבור ליצירת הטבלה החיצונית של Iceberg, לדוגמה us
‫CONNECTION_ID: מזהה החיבור לטבלה, לדוגמה myconnection

כשמציגים את פרטי החיבור במסוף Google Cloud , מזהה החיבור הוא הערך בקטע האחרון של מזהה החיבור המלא שמוצג במזהה החיבור – לדוגמה, projects/myproject/locations/connection_location/connections/myconnection
‫DATASET: השם של מערך הנתונים ב-BigQuery שבו רוצים ליצור טבלה

לדוגמה, mydataset.
‫EXTERNAL_TABLE: השם של הטבלה שרוצים ליצור

לדוגמה, mytable.

עדכון המטא-נתונים של הטבלה

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

BQ

יוצרים קובץ הגדרת טבלה:

bq mkdef --source_format=ICEBERG \
"URI" > TABLE_DEFINITION_FILE

משתמשים בפקודה bq update עם הדגל --autodetect_schema:
```
bq update --autodetect_schema --external_table_definition=TABLE_DEFINITION_FILE
PROJECT_ID:DATASET.TABLE
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫URI: ה-URI של Cloud Storage עם קובץ המטא-נתונים העדכני בפורמט JSON
  
  לדוגמה, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.
- ‫TABLE_DEFINITION_FILE: השם של הקובץ שמכיל את סכימת הטבלה
- ‫PROJECT_ID: מזהה הפרויקט שמכיל את הטבלה שרוצים לעדכן
- ‫DATASET: מערך הנתונים שמכיל את הטבלה שרוצים לעדכן
- ‫TABLE: הטבלה שרוצים לעדכן

API

משתמשים בשיטה tables.patch עם המאפיין autodetect_schema שהוגדר לערך true:

PATCH https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET/tables/TABLE?autodetect_schema=true

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

‫PROJECT_ID: מזהה הפרויקט שמכיל את הטבלה שרוצים לעדכן
‫DATASET: מערך הנתונים שמכיל את הטבלה שרוצים לעדכן
‫TABLE: הטבלה שרוצים לעדכן

בגוף הבקשה, מציינים את הערכים המעודכנים של השדות הבאים:

{
     "externalDataConfiguration": {
      "sourceFormat": "ICEBERG",
      "sourceUris": [
        "URI"
      ]
    },
    "schema": null
  }'

מחליפים את URI בקובץ המטא-נתונים העדכני של Iceberg. לדוגמה, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

הגדרת מדיניות בקרת גישה

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

שליחת שאילתות לטבלאות חיצוניות של Iceberg

מידע נוסף זמין במאמר בנושא שליחת שאילתות לנתוני Iceberg.

שאילתת נתונים היסטוריים

אפשר לגשת לתמונות מצב של טבלאות חיצוניות ב-Iceberg שנשמרות במטא-נתונים של Iceberg באמצעות פסוקית FOR SYSTEM_TIME AS OF.

אין תמיכה בחלונות של שמירת נתונים לצורך שחזור נתונים וגישה לנתונים היסטוריים בטבלאות חיצוניות.

מיפוי נתונים

‫BigQuery ממיר סוגי נתונים של Iceberg לסוגי נתונים של BigQuery כמו שמוצג בטבלה הבאה:

סוג הנתונים של Iceberg	סוג נתונים ב-BigQuery
`boolean`	`BOOL`
`int`	`INT64`
`long`	`INT64`
`float`	`FLOAT64`
`double`	`FLOAT64`
`Decimal(P/S)`	`NUMERIC or BIG_NUMERIC depending on precision`
`date`	`DATE`
`time`	`TIME`
`timestamp`	`DATETIME`
`timestamptz`	`TIMESTAMP`
`string`	`STRING`
`uuid`	`BYTES`
`fixed(L)`	`BYTES`
`binary`	`BYTES`
`list<Type>`	`ARRAY<Type>`
`struct`	`STRUCT`
`map<KeyType, ValueType>`	`ARRAY<Struct<key KeyType, value ValueType>>`

מגבלות

בנוסף למגבלות על טבלאות חיצוניות, יש לטבלאות חיצוניות בפורמט Iceberg את המגבלות הבאות:

לא ניתן להשתמש בשאילתות ב-VPC Service Controls, והן יובילו לשגיאה כמו NO_MATCHING_ACCESS_LEVEL.
הטבלאות שמשתמשות במיזוג בזמן הקריאה כפופות למגבלות הבאות:
- אפשר לשייך לכל קובץ נתונים עד 10,000 קבצים למחיקה.
- אפשר להחיל על קובץ נתונים עד 100,000 מחיקות של שוויון.
- כדי לעקוף את המגבלות האלה, אפשר לבצע דחיסה של קובצי מחיקה בתדירות גבוהה, ליצור תצוגה מעל טבלת Iceberg כדי להימנע ממחיצות שעוברות שינויים בתדירות גבוהה, או להשתמש במחיקות לפי מיקום במקום במחיקות לפי שוויון.
‫BigQuery תומך בגיזום של קובצי מניפסט באמצעות כל פונקציות ההמרה של מחיצות Iceberg. מידע על גיזום מחיצות מופיע במאמר בנושא שאילתות בטבלאות מחולקות. שאילתות שמפנות לטבלאות חיצוניות של Iceberg חייבות להכיל ערכים מילוליים בפרדיקטים בהשוואה לעמודות שמחולקות למחיצות.
המערכת תומכת רק בקובצי נתונים בפורמט Apache Parquet.

עלויות של מיזוג בזמן קריאה

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

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

דרישה למסנן מחיצות

כדי לדרוש שימוש במסנני פרדיקטים, צריך להפעיל את האפשרות require partition filter (דרישת מסנן מחיצה) בטבלת Iceberg. אם מפעילים את האפשרות הזו, ניסיונות לשלוח שאילתה לטבלה בלי לציין פסקה WHERE שתואמת לכל קובץ מניפסט יגרמו לשגיאה הבאה:

Cannot query over table project_id.dataset.table without a
filter that can be used for partition elimination.

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

אתם יכולים להפעיל את require_partition_filter בדרכים הבאות כשאתם יוצרים טבלת Iceberg :

SQL

משתמשים בהצהרת CREATE EXTERNAL TABLE.בדוגמה הבאה נוצרת טבלה חיצונית של Iceberg בשם TABLE עם מסנן מחיצות שמופעל:

  CREATE EXTERNAL TABLE TABLE
  WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
  OPTIONS (
         format = 'ICEBERG',
         uris = [URI],
         require_partition_filter = true
   )

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

‫TABLE: שם הטבלה שרוצים ליצור.
‫PROJECT_ID: מזהה הפרויקט שמכיל את הטבלה שרוצים ליצור.
‫REGION: המיקום שבו רוצים ליצור את טבלת Iceberg.
‫CONNECTION_ID: מזהה החיבור. לדוגמה, myconnection.
‫URI: ה-URI של Cloud Storage עם קובץ המטא-נתונים העדכני בפורמט JSON.

לדוגמה, gs://mybucket/us/iceberg/mytable/metadata/1234.metadata.json.

ה-URI יכול להצביע גם על מיקום חיצוני בענן, כמו Amazon S3 או Azure Blob Storage.
- דוגמה ל-AWS: ‏ s3://mybucket/iceberg/metadata/1234.metadata.json.
- דוגמה ל-Azure: ‏ azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.

BQ

משתמשים בפקודה bq mk --table עם העיטור @connection כדי לציין את החיבור שבו יש להשתמש בסוף הפרמטר --external_table_definition. משתמשים באפשרות --require_partition_filter כדי להפעיל את המסנן 'דרישת מחיצה'. בדוגמה הבאה נוצרת טבלה חיצונית של Iceberg בשם TABLE עם האפשרות require partition filter (דרישת מסנן מחיצה) מופעלת:

bq mk \
    --table \
    --external_table_definition=ICEBERG=URI@projects/CONNECTION_PROJECT_ID/locations/CONNECTION_REGION/connections/CONNECTION_ID \
    PROJECT_ID:DATASET.EXTERNAL_TABLE \
    --require_partition_filter

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

‫URI: קובץ מטא-נתונים בפורמט JSON העדכני ביותר של תמונת מצב ספציפית של טבלה

לדוגמה, gs://mybucket/mydata/mytable/metadata/iceberg.metadata.json.

ה-URI יכול להצביע גם על מיקום חיצוני בענן, כמו Amazon S3 או Azure Blob Storage.
- דוגמה ל-AWS: ‏ s3://mybucket/iceberg/metadata/1234.metadata.json.
- דוגמה ל-Azure: ‏ azure://mystorageaccount.blob.core.windows.net/mycontainer/iceberg/metadata/1234.metadata.json.
‫CONNECTION_PROJECT_ID: הפרויקט שמכיל את החיבור ליצירת טבלת Iceberg חיצונית – לדוגמה, myproject
‫CONNECTION_REGION: האזור שמכיל את החיבור ליצירת טבלת Iceberg חיצונית. לדוגמה, us.
‫CONNECTION_ID: : מזהה החיבור. לדוגמה, myconnection.

כשמציגים את פרטי החיבור במסוף Google Cloud , מזהה החיבור הוא הערך בקטע האחרון של מזהה החיבור המלא שמוצג במזהה החיבור – לדוגמה, projects/myproject/locations/connection_location/connections/myconnection
‫DATASET: השם של BigQuery

קבוצת נתונים שמכילה את הטבלה שרוצים לעדכן. לדוגמה, mydataset.
‫EXTERNAL_TABLE: השם של הטבלה שרוצים ליצור

לדוגמה, mytable.

אפשר גם לעדכן את טבלת Iceberg כדי להפעיל את האפשרות require partition filter (דרישת מסנן מחיצה).

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

BQ

משתמשים בפקודה bq update עם הדגל --require_partition_filter.

לדוגמה:

כדי לעדכן את mypartitionedtable ב-mydataset בפרויקט ברירת המחדל, מזינים:

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

יצירת טבלאות חיצוניות של Apache Iceberg

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

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

ההרשאות הנדרשות

יצירת טבלאות בעזרת מאגר המטא-נתונים של BigLake

יצירת טבלאות באמצעות קובץ מטא-נתונים

SQL

BQ

עדכון המטא-נתונים של הטבלה

BQ

API

הגדרת מדיניות בקרת גישה

שליחת שאילתות לטבלאות חיצוניות של Iceberg

שאילתת נתונים היסטוריים

מיפוי נתונים

מגבלות

עלויות של מיזוג בזמן קריאה

דרישה למסנן מחיצות

SQL

BQ

BQ

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