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

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

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

תמיכה בפורמט ובגרסה של Iceberg

‫Iceberg הוא פורמט טבלה בקוד פתוח שתומך בטבלאות נתונים בקנה מידה של פטה-בייט. המפרט הפתוח של Iceberg מאפשר להריץ כמה מנועי שאילתות על עותק אחד של נתונים שמאוחסנים במאגר אובייקטים. טבלאות חיצוניות של Iceberg תומכות ב-Iceberg גרסה 2, כולל מיזוג בקריאה. התמיכה ב-Iceberg גרסה 3, כולל וקטורים של מחיקה בינארית, נמצאת בגרסת טרום-השקה (Preview). כדי לשלוח משוב או לשאול שאלות שקשורות לתכונה הזו בגרסת טרום-השקה (Preview), אפשר לפנות אל biglake-help@google.com.

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

מפעילים את BigQuery Connection API ואת BigQuery Reservation API, אם הם עדיין לא מופעלים.

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

כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

הפעלת ממשקי ה-API

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

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

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

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

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

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

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

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

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

אפשר ליצור טבלאות חיצוניות של 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.

BQ

בסביבת שורת הפקודה, משתמשים בפקודה bq mk --table עם ה-decorator‏ @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 , מזהה החיבור הוא הערך בחלק האחרון של מזהה החיבור המלא שמוצג ב-Connection ID, לדוגמה projects/myproject/locations/connection_location/connections/myconnection.

  • ‫DATASET: השם של מערך הנתונים ב-BigQuery שבו רוצים ליצור טבלה

    לדוגמה, mydataset.

  • ‫EXTERNAL_TABLE: שם הטבלה שרוצים ליצור

    לדוגמה, mytable.

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

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

BQ

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

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

  2. משתמשים בפקודה 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

משתמשים ב-method‏ 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 באמצעות אבטחה ברמת העמודה, אבטחה ברמת השורה והסתרת נתונים.

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

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

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

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

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

אין תמיכה בחלונות זמן של שמירת נתונים מסוג Time travel ו-Fail-safe בטבלאות חיצוניות.

מיפוי נתונים

‫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.

  • לטבלאות שמשתמשות במיזוג בזמן קריאה יש את המגבלות הבאות:

    • שאילתה יכולה לעבד עד 100,000 רשומות של וקטורי מחיקה בטבלה. בטבלאות בגרסה 3 של Iceberg שמשתמשות בווקטורים בינאריים של מחיקה, כל קובץ נתונים שמשויך לווקטור מחיקה נספר כרשומת מחיקה אחת במגבלה הזו.
    • אפשר לשייך כל קובץ נתונים לעד 10,000 קובצי מחיקה.
    • אפשר להחיל עד 100,000 מחיקות שוות על קובץ נתונים.
    • כדי לעקוף את המגבלות האלה, אתם יכולים לדחוס קובצי מחיקה ווקטורי מחיקה לעיתים קרובות, ליצור תצוגה מעל טבלת Iceberg שמונעת שינויים תכופים במחיצות, או לסנן שאילתות בעמודות מחולקות למחיצות כדי לצמצם את מספר קובצי הנתונים ווקטורי המחיקה שנסרקים.

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

  • יש תמיכה רק בקובצי נתונים מסוג Apache Parquet.

  • שמות עמודות גמישים:

    • אם טבלה חיצונית של Iceberg מחולקת למחיצות לפי עמודה שמכילה תווים לא אלפאנומריים, יכול להיות ש-BigQuery לא יוכל לחלץ את המטא-נתונים של המחיצה מהמניפסט, מה שעלול לגרום לסריקה מלאה של הטבלה.
    • אי אפשר לשלוח שאילתות ישירות מ-BigQuery לטבלאות Iceberg שמכילות תווים מבניים (כמו נקודות ., סימני דולר $, סוגריים מרובעים [], סוגריים עגולים () או לוכסנים /). אם תהליך העבודה שלכם מחייב רישום של טבלאות כאלה בקטלוג הייעודי לזמן ריצה או בשירותי הקטלוג של Lakehouse, לשימוש בלעדי במנועים חיצוניים (כמו Spark או Trino), פנו אל Cloud Customer Care כדי לבקש הפעלה ברמת הפרויקט.

  • התכונות הבאות של Iceberg גרסה 3 לא נתמכות:

    • סוגי נתונים חדשים: חותמת זמן בננו-שניות(tz), לא ידוע, וריאנט, גיאומטריה, גיאוגרפיה
    • ערכי ברירת המחדל הראשוניים
    • מפתחות הצפנה של טבלאות

עלויות של מיזוג בקריאה (merge-on-read)

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

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

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

כדי לדרוש שימוש במסנני פרדיקט, אתם יכולים להפעיל את האפשרות דרישת מסנן מחיצה בטבלת 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, עם דרישת מסנן מחיצה: 

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 , מזהה החיבור הוא הערך בקטע האחרון של מזהה החיבור המלא שמוצג ב-Connection ID, לדוגמה projects/myproject/locations/connection_location/connections/myconnection.

  • ‫DATASET: השם של מערך הנתונים ב-BigQuery

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

  • ‫EXTERNAL_TABLE: שם הטבלה שרוצים ליצור

    לדוגמה, mytable.

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

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

BQ

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

לדוגמה:

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

bq update --require_partition_filter PROJECT_ID:DATASET.TABLE

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