יצירת טבלאות חיצוניות ב-BigLake ל-Cloud Storage

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

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

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

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Enable the BigQuery Connection API.

    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 API

    אם רוצים לקרוא טבלאות BigLake ממנועי קוד פתוח כמו Apache Spark, צריך להפעיל את BigQuery Storage Read API.

  4. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

  5. מוודאים שיש לכם מערך נתונים ב-BigQuery.

  6. מוודאים שהגרסה של Google Cloud SDK היא 366.0.0 ואילך:

    gcloud version

    במקרה הצורך, מעדכנים את Google Cloud SDK.

    1. אופציונלי: ל-Terraform נדרשת גרסה 4.25.0 ואילך של terraform-provider-google. גרסאות של terraform-provider-google מפורטות ב-GitHub. אפשר להוריד את הגרסה העדכנית של Terraform מההורדות של HashiCorp Terraform.

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

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

    כדי ליצור טבלת BigLake, אתם צריכים את ההרשאות הבאות ב-BigQuery לניהול זהויות והרשאות גישה (IAM):

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

    ההרשאות האלה כלולות בתפקיד המוגדר מראש 'אדמין של BigQuery' (roles/bigquery.admin) בניהול זהויות והרשאות גישה.

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

    במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

    שיקולים לגבי מיקום

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

    יצירת טבלאות BigLake על נתונים לא מחולקים

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

    לפני שיוצרים טבלת BigLake, צריך שיהיה מערך נתונים וחיבור למשאב Cloud שמאפשר גישה ל-Cloud Storage.

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

    המסוף

    1. עוברים לדף BigQuery.

      כניסה ל-BigQuery

    2. בחלונית הימנית, לוחצים על כלי הניתוחים:

      כפתור מודגש לחלונית הסייר.

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

    3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ואז בוחרים מערך נתונים.

    4. מרחיבים את האפשרות Actions (פעולות) ולוחצים על Create table (יצירת טבלה).

    5. בקטע מקור, מציינים את הפרטים הבאים:

      1. בקטע Create table from (יצירת טבלה מתוך), בוחרים באפשרות Google Cloud Storage.

      2. בקטע Select file from GCS bucket or use a URI pattern (בחירת קובץ ממאגר GCS או שימוש בתבנית URI), מעיינים כדי לבחור מאגר וקובץ לשימוש, או מקלידים את הנתיב בפורמט gs://bucket_name/[folder_name/]file_name.

        אי אפשר לציין כמה כתובות URI במסוף Google Cloud , אבל אפשר לבחור כמה קבצים על ידי ציון כוכבית אחת (*) כתו כללי. לדוגמה, gs://mybucket/file_name*. מידע נוסף זמין במאמר בנושא תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

      3. בקטע פורמט קובץ, בוחרים את הפורמט שמתאים לקובץ.

    6. בקטע יעד, מציינים את הפרטים הבאים:

      1. בשדה Project, בוחרים את הפרויקט שבו רוצים ליצור את הטבלה.

      2. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.

      3. בשדה Table (טבלה), מזינים את שם הטבלה שיוצרים.

      4. בשדה Table type (סוג הטבלה), בוחרים באפשרות External table (טבלה חיצונית).

      5. בוחרים באפשרות יצירת טבלת BigLake באמצעות חיבור למשאב בענן.

      6. בשדה מזהה חיבור בוחרים את החיבור שיצרתם קודם.

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

      • כדי להפעיל זיהוי אוטומטי של סכימה, בוחרים באפשרות זיהוי אוטומטי.

      • כדי לציין סכימה באופן ידני, משאירים את האפשרות זיהוי אוטומטי לא מסומנת. מפעילים את האפשרות Edit as text ומזינים את סכימת הטבלה כמערך JSON.

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

    9. לוחצים על יצירת טבלה.

    אחרי שיוצרים את הטבלה הקבועה, אפשר להריץ שאילתה על הטבלה כאילו היא הייתה טבלה ב-BigQuery. אחרי שהשאילתה מסתיימת, אפשר לייצא את התוצאות כקובצי CSV או JSON, לשמור את התוצאות כטבלה או לשמור את התוצאות ב-Google Sheets.

    SQL

    משתמשים בהצהרת ה-DDL‏ CREATE EXTERNAL TABLE. אפשר לציין את הסכימה באופן מפורש, או להשתמש בזיהוי אוטומטי של סכימה כדי להסיק את הסכימה מהנתונים החיצוניים.

    1. במסוף Google Cloud , עוברים לדף BigQuery.

      כניסה ל-BigQuery

    2. מזינים את ההצהרה הבאה בעורך השאילתות:

      CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS (
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'[,...]],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

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

      • ‫PROJECT_ID: שם הפרויקט שבו רוצים ליצור את הטבלה, לדוגמה myproject
      • ‫DATASET: השם של מערך הנתונים ב-BigQuery שבו רוצים ליצור את הטבלה – למשל, mydataset
      • ‫EXTERNAL_TABLE_NAME: השם של הטבלה שרוצים ליצור, לדוגמה mytable
      • ‫REGION: האזור שמכיל את החיבור, למשל us
      • ‫CONNECTION_ID: מזהה החיבור, לדוגמה: myconnection

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

        כדי להשתמש ב חיבור שמוגדר כברירת מחדל, מציינים DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

      • ‫TABLE_FORMAT: הפורמט של הטבלה שרוצים ליצור. לדוגמה: PARQUET

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

      • ‫BUCKET_PATH: הנתיב לדלי Cloud Storage שמכיל את הנתונים של הטבלה החיצונית, בפורמט ['gs://bucket_name/[folder_name/]file_name'].

        אפשר לבחור כמה קבצים מהמאגר על ידי ציון כוכבית אחת (*) כתו כללי בנתיב. לדוגמה, ['gs://mybucket/file_name*']. מידע נוסף זמין במאמר תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

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

        • ['gs://bucket/path1/myfile.csv']
        • ['gs://bucket/path1/*.csv']
        • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

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

        מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב של Cloud Storage.

      • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת BigLake משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שצריכה להיות כדי שהפעולה תשתמש בהם. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

        כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

        כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מילול של מרווח בין 30 דקות ל-7 ימים. לדוגמה, כדי לציין מרווח של 4 שעות, צריך להזין INTERVAL 4 HOUR. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

      • ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתרענן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירה במטמון של מטא-נתונים זמין במאמר שמירה במטמון של מטא-נתונים לשיפור הביצועים.

        מגדירים את הערך AUTOMATIC כדי שהמטמון של המטא-נתונים יתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

        מגדירים את הערך MANUAL אם רוצים לרענן את מטמון המטא-נתונים לפי לוח זמנים שקובעים. במקרה כזה, אפשר להתקשר אל BQ.REFRESH_EXTERNAL_METADATA_CACHE הליך המערכת כדי לרענן את המטמון.

        אם מגדירים את STALENESS_INTERVAL לערך גדול מ-0, צריך להגדיר גם את CACHE_MODE.

    3. לוחצים על הפעלה.

    מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

    BQ

    אפשרות 1: קובץ הגדרת טבלה

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

    bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

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

    • ‫CONNECTION_ID: מזהה החיבור, לדוגמה myconnection

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

      כדי להשתמש בחיבור ברירת מחדל, צריך לציין DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

    • ‫SOURCE_FORMAT: הפורמט של מקור הנתונים החיצוני. לדוגמה, PARQUET.

    • ‫BUCKET_PATH: הנתיב לקטגוריה של Cloud Storage שמכילה את הנתונים של הטבלה, בפורמט gs://bucket_name/[folder_name/]file_pattern.

      אפשר לבחור כמה קבצים מהמאגר על ידי ציון כוכבית אחת (*) כתו כללי ב-file_pattern. לדוגמה, gs://mybucket/file00*.parquet. מידע נוסף זמין במאמר בנושא תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

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

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.parquet
      • gs://bucket/path1/file1*, gs://bucket1/path1/*

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

      מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב ב-Cloud Storage.

    • ‫DEFINITION_FILE: הנתיב אל קובץ הגדרת הטבלה במחשב המקומי.

    • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת BigLake משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שצריכה להיות כדי שהפעולה תוכל להשתמש בהם. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

      כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

      כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים, באמצעות הפורמט Y-M D H:M:S שמתואר במסמכי התיעוד של סוג הנתונים INTERVAL. לדוגמה, כדי להגדיר את מרווח הרענון ל-4 שעות, מציינים 0-0 0 4:0:0. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים שנשמרו במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

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

    • ‫EXTERNAL_TABLE_NAME: השם של הטבלה שרוצים ליצור, לדוגמה mytable

    • ‫SCHEMA: הסכימה של טבלת BigLake

    דוגמה:

    bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

    כדי להשתמש בזיהוי אוטומטי של סכימה, מגדירים את הדגל --autodetect=true בפקודה mkdef ומשמיטים את הסכימה:

    bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

    אפשרות 2: הגדרת טבלה במקום

    במקום ליצור קובץ הגדרת טבלה, אפשר להעביר את הגדרת הטבלה ישירות אל הפקודה bq mk. משתמשים ב-decorator‏ @connection כדי לציין את החיבור שבו רוצים להשתמש בסוף הדגל --external_table_definition.

    bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

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

    • ‫SOURCE_FORMAT: הפורמט של מקור הנתונים החיצוני

      לדוגמה, CSV.

    • ‫BUCKET_PATH: הנתיב לקטגוריה של Cloud Storage שמכילה את הנתונים של הטבלה, בפורמט gs://bucket_name/[folder_name/]file_pattern.

      אפשר לבחור כמה קבצים מהמאגר על ידי ציון כוכבית אחת (*) כתו כללי ב-file_pattern. לדוגמה, gs://mybucket/file00*.parquet. מידע נוסף זמין במאמר בנושא תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

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

      • gs://bucket/path1/myfile.csv
      • gs://bucket/path1/*.parquet
      • gs://bucket/path1/file1*, gs://bucket1/path1/*

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

      מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב ב-Cloud Storage.

    • ‫PROJECT_ID: שם הפרויקט שבו רוצים ליצור את הטבלה, לדוגמה myproject

    • ‫REGION: האזור שמכיל את החיבור, us

    • ‫CONNECTION_ID: מזהה החיבור, לדוגמה myconnection

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

      כדי להשתמש בחיבור ברירת מחדל, צריך לציין DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

    • ‫DATASET_NAME: השם של מערך הנתונים שבו רוצים ליצור את טבלת BigLake.

    • ‫TABLE_NAME: השם של טבלת BigLake

    • ‫SCHEMA: הסכימה של טבלת BigLake

    דוגמה:

    bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

    API

    מבצעים קריאה ל-method של API‏ tables.insert ויוצרים ExternalDataConfiguration במשאב Table שמעבירים.

    מציינים את המאפיין schema או מגדירים את המאפיין autodetect לערך true כדי להפעיל זיהוי אוטומטי של סכימה עבור מקורות נתונים נתמכים.

    מציינים את המאפיין connectionId כדי לזהות את החיבור שבו יש להשתמש כדי להתחבר ל-Cloud Storage.

    Terraform

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

    כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

    # This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}


# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  depends_on = [time_sleep.default]
}

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

    הכנת Cloud Shell

    1. מפעילים את Cloud Shell.

    2. מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud

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

      export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

    הכנת הספרייה

    לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

    1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf. 
      mkdir DIRECTORY && cd DIRECTORY && touch main.tf

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

      מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

      לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

    3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
    4. שומרים את השינויים.
    5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה. 
      terraform init

      אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google: 

      terraform init -upgrade

    החלה של השינויים

    1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם: 
      terraform plan

      מתקנים את ההגדרות לפי הצורך.

    2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform: 
      terraform apply

      ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

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

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

    יצירת טבלאות BigLake על נתונים עם חלוקה למחיצות ב-Apache Hive

    אפשר ליצור טבלת BigLake לנתונים שמחולקים למחיצות ב-Hive ב-Cloud Storage. אחרי שיוצרים טבלה מחולקת למחיצות חיצוניות, אי אפשר לשנות את מפתח המחיצה. כדי לשנות את מפתח המחיצה, צריך ליצור מחדש את הטבלה.

    כדי ליצור טבלת BigLake על סמך נתונים עם חלוקה למחיצות ב-Hive ב-Cloud Storage, בוחרים באחת מהאפשרויות הבאות:

    המסוף

    1. עוברים לדף BigQuery.

      כניסה ל-BigQuery

    2. בחלונית הימנית, לוחצים על כלי הניתוחים:

      כפתור מודגש לחלונית הסייר.

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

    3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets (מערכי נתונים) ואז לוחצים על מערך נתונים.

    4. לוחצים על יצירת טבלה. נפתחת החלונית Create table.

    5. בקטע מקור, מציינים את הפרטים הבאים:

      1. בקטע Create table from (יצירת טבלה מתוך), בוחרים באפשרות Google Cloud Storage.

      2. מזינים את הנתיב לתיקייה באמצעות תווים כלליים לחיפוש. לדוגמה, my_bucket/my_files*. התיקייה צריכה להיות באותו מיקום של מערך הנתונים שמכיל את הטבלה שרוצים ליצור, לצרף או להחליף.

      3. מהרשימה פורמט קובץ בוחרים את סוג הקובץ.

      4. מסמנים את תיבת הסימון חלוקה למחיצות של נתוני המקור ומציינים את הפרטים הבאים:

        1. בשדה Select Source URI Prefix, מזינים את התחילית של ה-URI. לדוגמה, gs://my_bucket/my_files.
        2. אופציונלי: כדי לדרוש מסנן מחיצה בכל השאילתות של הטבלה הזו, מסמנים את תיבת הסימון דרישת מסנן מחיצה. הוספת דרישה לסינון מחיצות יכולה להפחית את העלויות ולשפר את הביצועים. מידע נוסף מופיע במאמר בנושא הוספת מסנני פרדיקטים למפתחות של מחיצות בשאילתות.

        3. בקטע Partition inference mode, בוחרים באחת מהאפשרויות הבאות:

          • הסקת סוגים באופן אוטומטי: מגדירים את מצב הזיהוי של סכימת החלוקה למחיצות לערך AUTO.
          • כל העמודות הן מחרוזות: מגדירים את מצב הזיהוי של סכימת המחיצה ל-STRINGS.
          • אני רוצה לספק משלי: מגדירים את מצב הזיהוי של סכימת המחיצות ל-CUSTOM ומזינים ידנית את פרטי הסכימה של מפתחות המחיצות. מידע נוסף מופיע במאמר בנושא הגדרת סכימה מותאמת אישית של מפתח מחיצה.

    6. בקטע יעד, מציינים את הפרטים הבאים:

      1. בשדה Project, בוחרים את הפרויקט שבו רוצים ליצור את הטבלה.
      2. בשדה Dataset, בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      3. בשדה Table, מזינים את שם הטבלה שרוצים ליצור.
      4. בשדה Table type (סוג הטבלה), בוחרים באפשרות External table (טבלה חיצונית).
      5. מסמנים את התיבה יצירת טבלת BigLake באמצעות חיבור למשאב בענן.
      6. בקטע מזהה חיבור, בוחרים את החיבור שיצרתם קודם.

    7. בקטע סכימה, בוחרים באפשרות זיהוי אוטומטי כדי להפעיל זיהוי אוטומטי של סכימה.

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

    9. לוחצים על יצירת טבלה.

    SQL

    משתמשים בהצהרת ה-DDL‏ CREATE EXTERNAL TABLE:

    1. במסוף Google Cloud , עוברים לדף BigQuery.

      כניסה ל-BigQuery

    2. מזינים את ההצהרה הבאה בעורך השאילתות:

      CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
WITH PARTITION COLUMNS
(
  PARTITION_COLUMN PARTITION_COLUMN_TYPE,
)
WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT}
OPTIONS (
  hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
  uris=['FILE_PATH'],
  max_staleness = STALENESS_INTERVAL,
  metadata_cache_mode = 'CACHE_MODE',
  format ="TABLE_FORMAT"
);

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

      • ‫PROJECT_ID: שם הפרויקט שבו רוצים ליצור את הטבלה, לדוגמה, myproject
      • ‫DATASET: השם של מערך הנתונים ב-BigQuery שבו רוצים ליצור את הטבלה – למשל, mydataset
      • ‫EXTERNAL_TABLE_NAME: השם של הטבלה שרוצים ליצור, לדוגמה mytable
      • ‫PARTITION_COLUMN: השם של עמודת החלוקה
      • ‫PARTITION_COLUMN_TYPE: הסוג של עמודת החלוקה למחיצות
      • ‫REGION: האזור שמכיל את החיבור, למשל us
      • ‫CONNECTION_ID: מזהה החיבור, לדוגמה: myconnection

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

        כדי להשתמש ב חיבור שמוגדר כברירת מחדל, מציינים DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

      • ‫HIVE_PARTITION_URI_PREFIX: קידומת URI של חלוקה למחיצות ב-Hive – לדוגמה, gs://mybucket/
      • ‫FILE_PATH: הנתיב למקור הנתונים של הטבלה החיצונית שרוצים ליצור, לדוגמה: gs://mybucket/*.parquet
      • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת BigLake משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שצריכה להיות כדי שהפעולה תשתמש בהם. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

        כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

        כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מילול של מרווח בין 30 דקות ל-7 ימים. לדוגמה, כדי לציין מרווח של 4 שעות, צריך להזין INTERVAL 4 HOUR. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

      • ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתרענן באופן אוטומטי או ידני. מידע נוסף על שיקולים לגבי שמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

        מגדירים את הערך AUTOMATIC כדי שהמטמון של המטא-נתונים יתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

        מגדירים את הערך MANUAL אם רוצים לרענן את מטמון המטא-נתונים לפי לוח זמנים שקובעים. במקרה כזה, אפשר להתקשר אל BQ.REFRESH_EXTERNAL_METADATA_CACHE הליך המערכת כדי לרענן את המטמון.

        אם מגדירים את STALENESS_INTERVAL לערך גדול מ-0, צריך להגדיר גם את CACHE_MODE.

      • ‫TABLE_FORMAT: הפורמט של הטבלה שרוצים ליצור. לדוגמה: PARQUET

    3. לוחצים על הפעלה.

    מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

    דוגמאות

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

    • הסכימה מזוהה אוטומטית.
    • המרווח בין עדכונים של מטמון המטא-נתונים בטבלה הוא יום אחד.
    • מטמון המטא-נתונים מתעדכן באופן אוטומטי.
    CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

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

    • הסכימה מצוינת.
    • המרווח בין עדכוני המטמון של המטא-נתונים של הטבלה הוא 8 שעות.
    • צריך לרענן את מטמון המטא-נתונים באופן ידני.
    CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

    BQ

    קודם כל, משתמשים בפקודה bq mkdef כדי ליצור קובץ הגדרת טבלה:

    bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_URIS > DEFINITION_FILE

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

    • ‫SOURCE_FORMAT: הפורמט של מקור הנתונים החיצוני. לדוגמה, CSV.
    • ‫REGION: האזור שמכיל את החיבור, לדוגמה us.

    • ‫CONNECTION_ID: מזהה החיבור, לדוגמה myconnection.

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

      כדי להשתמש בחיבור ברירת מחדל, צריך לציין DEFAULT במקום מחרוזת החיבור שמכילה PROJECT_ID.REGION.CONNECTION_ID.

    • ‫PARTITIONING_MODE: מצב החלוקה למחיצות של Hive. משתמשים באחד מהערכים הבאים:

      • ‫AUTO: זיהוי אוטומטי של שמות וסוגי המפתחות.
      • ‫STRINGS: המערכת תמיר אוטומטית את שמות המפתחות למחרוזות.
      • ‫CUSTOM: קידוד סכמת המפתח בקידומת של ה-URI במקור.

    • ‫GCS_URI_SHARED_PREFIX: קידומת ה-URI של המקור.

    • ‫BOOLEAN: מציין אם נדרש מסנן של תנאי מסוים בזמן השאילתה. הדגל הזה הוא אופציונלי. ערך ברירת המחדל הוא false.

    • ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתרענן באופן אוטומטי או ידני. צריך לכלול את הדגל הזה רק אם מתכננים להשתמש גם בדגל --max_staleness בפקודה הבאה bq mk כדי להפעיל שמירת מטא-נתונים במטמון. מידע נוסף על שיקולים בנוגע לשמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

      אם מגדירים את הערך AUTOMATIC, מטמון המטא-נתונים מתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

      מגדירים את הערך MANUAL אם רוצים לרענן את מטמון המטא-נתונים לפי לוח זמנים שקובעים. במקרה כזה, אפשר להתקשר אל BQ.REFRESH_EXTERNAL_METADATA_CACHE מערכת ההליכים כדי לרענן את המטמון.

      אם הערך של STALENESS_INTERVAL גדול מ-0, צריך להגדיר את CACHE_MODE.

    • ‫GCS_URIS: הנתיב לתיקייה ב-Cloud Storage, בפורמט של wildcard.

    • ‫DEFINITION_FILE: הנתיב אל קובץ הגדרת הטבלה במחשב המקומי.

    אם PARTITIONING_MODE הוא CUSTOM, צריך לכלול את סכימת מפתח המחיצה בקידומת של מזהה ה-URI של המקור, באמצעות הפורמט הבא:

    --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

    אחרי שיוצרים את קובץ הגדרת הטבלה, משתמשים בפקודה bq mk כדי ליצור את טבלת BigLake:

    bq mk --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

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

    • ‫DEFINITION_FILE: הנתיב לקובץ הגדרת הטבלה.

    • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלת BigLake משתמשות במטא-נתונים שנשמרו במטמון, ומה רמת העדכניות של המטא-נתונים שצריכה להיות כדי שהפעולה תוכל להשתמש בהם. אם כוללים את הדגל הזה, צריך גם לציין ערך לדגל --metadata_cache_mode בפקודה bq mkdef הקודמת. מידע נוסף על שיקולים בנוגע לשמירה במטמון של מטא-נתונים זמין במאמר שמירה במטמון של מטא-נתונים לשיפור הביצועים.

      כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

      כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים, באמצעות הפורמט Y-M D H:M:S שמתואר במסמכי התיעוד של סוג הנתונים INTERVAL. לדוגמה, כדי להגדיר את מרווח הזמן של הנתונים הלא עדכניים ל-4 שעות, צריך לציין 0-0 0 4:0:0. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

    • ‫DATASET_NAME: השם של מערך הנתונים שמכיל את הטבלה.

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

    • ‫SCHEMA: מציין נתיב לקובץ סכימת JSON, או מציין את הסכימה בפורמט field:data_type,field:data_type,.... כדי להשתמש בזיהוי אוטומטי של סכימה, משמיטים את הארגומנט הזה.

    דוגמאות

    בדוגמה הבאה נעשה שימוש בAUTO מצב חלוקה למחיצות של Hive, וגם מוגדר מטמון המטא-נתונים כך שיהיה לו מרווח זמן של 12 שעות עד שיהפוך למיושן, ושהוא יתעדכן אוטומטית:

    bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

    בדוגמה הבאה נעשה שימוש במצב החלוקה למחיצות של Hive:‏ STRING

    bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

    בדוגמה הבאה נעשה שימוש במצב החלוקה למחיצות של Hive:‏ CUSTOM

    bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

    API

    כדי להגדיר חלוקה למחיצות ב-Hive באמצעות BigQuery API, צריך לכלול את האובייקט hivePartitioningOptions באובייקט ExternalDataConfiguration כשיוצרים את קובץ הגדרת הטבלה. כדי ליצור טבלת BigLake, צריך לציין גם ערך בשדה connectionId.

    אם מגדירים את השדה hivePartitioningOptions.mode ל-CUSTOM, צריך לקודד את סכימת מפתח המחיצה בשדה hivePartitioningOptions.sourceUriPrefix באופן הבא: gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

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

    Terraform

    בדוגמה הזו נוצרת טבלת BigLake על נתונים מחולקים.

    כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

    
# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }


  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

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

    הכנת Cloud Shell

    1. מפעילים את Cloud Shell.

    2. מגדירים את פרויקט ברירת המחדל שבו רוצים להחיל את ההגדרות של Terraform. Google Cloud

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

      export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

    הכנת הספרייה

    לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

    1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf. 
      mkdir DIRECTORY && cd DIRECTORY && touch main.tf

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

      מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

      לחלופין, אפשר גם להעתיק את הקוד מ-GitHub. כדאי לעשות את זה כשקטע הקוד של Terraform הוא חלק מפתרון מקצה לקצה.

    3. בודקים את הפרמטרים לדוגמה ומשנים אותם בהתאם לסביבה שלכם.
    4. שומרים את השינויים.
    5. מפעילים את Terraform. צריך לעשות זאת רק פעם אחת לכל ספרייה. 
      terraform init

      אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google: 

      terraform init -upgrade

    החלה של השינויים

    1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם: 
      terraform plan

      מתקנים את ההגדרות לפי הצורך.

    2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform: 
      terraform apply

      ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

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

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

    יש כמה דרכים לשלוט בגישה לטבלאות BigLake:

    לדוגמה, נניח שרוצים להגביל את הגישה לשורות בטבלה mytable בקבוצת הנתונים mydataset:

    +---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
| JP      | tablet  |   300 |
| UK      | laptop  |   200 |
+---------+---------+-------+

    אתם יכולים ליצור מסנן ברמת השורה עבור Kim (kim@example.com) שמגביל את הגישה שלה לשורות שבהן country שווה ל-US.

    CREATE ROW ACCESS POLICY only_us_filter
ON mydataset.mytable
GRANT TO ('user:kim@example.com')
FILTER USING (country = 'US');

    לאחר מכן, קים מריצה את השאילתה הבאה:

    SELECT * FROM projectid.mydataset.mytable;

    בפלט מוצגות רק השורות שבהן country שווה ל-US:

    +---------+---------+-------+
| country | product | price |
+---------+---------+-------+
| US      | phone   |   100 |
+---------+---------+-------+

    שליחת שאילתות לטבלאות BigLake

    מידע נוסף זמין במאמר בנושא שאילתות על נתונים ב-Cloud Storage בטבלאות BigLake.

    עדכון טבלאות BigLake

    במקרה הצורך, אפשר לעדכן את הטבלאות ב-BigLake, למשל כדי לשנות את השמירה במטמון של המטא-נתונים. כדי לקבל פרטים על הטבלה, כמו פורמט המקור ו-URI המקור, אפשר לעיין במאמר בנושא קבלת פרטי טבלה.

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

    כדי לעדכן טבלת BigLake, בוחרים באחת מהאפשרויות הבאות:

    SQL

    כדי לעדכן טבלה, משתמשים בCREATE OR REPLACE EXTERNAL TABLE הצהרת DDL:

    1. במסוף Google Cloud , עוברים לדף BigQuery.

      כניסה ל-BigQuery

    2. מזינים את ההצהרה הבאה בעורך השאילתות:

      CREATE OR REPLACE EXTERNAL TABLE
  `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
  WITH CONNECTION {`REGION.CONNECTION_ID` | DEFAULT}
  OPTIONS(
    format ="TABLE_FORMAT",
    uris = ['BUCKET_PATH'],
    max_staleness = STALENESS_INTERVAL,
    metadata_cache_mode = 'CACHE_MODE'
    );

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

      • ‫PROJECT_ID: השם של הפרויקט שמכיל את הטבלה
      • ‫DATASET: השם של מערך הנתונים שמכיל את הטבלה
      • ‫EXTERNAL_TABLE_NAME: שם הטבלה
      • ‫REGION: האזור שבו נמצא החיבור
      • ‫CONNECTION_ID: השם של החיבור שרוצים להשתמש בו

        כדי להשתמש ב חיבור שמוגדר כברירת מחדל, מציינים DEFAULT במקום מחרוזת החיבור שמכילה REGION.CONNECTION_ID.

      • ‫TABLE_FORMAT: הפורמט שבו הטבלה משתמשת

        אי אפשר לשנות את זה כשמעדכנים את הטבלה.

      • ‫BUCKET_PATH: הנתיב לדלי Cloud Storage שמכיל את הנתונים של הטבלה החיצונית, בפורמט ['gs://bucket_name/[folder_name/]file_name'].

        אפשר לבחור כמה קבצים מהמאגר על ידי ציון כוכבית אחת (*) כתו כללי בנתיב. לדוגמה, ['gs://mybucket/file_name*']. מידע נוסף זמין במאמר תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

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

        • ['gs://bucket/path1/myfile.csv']
        • ['gs://bucket/path1/*.csv']
        • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

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

        מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב של Cloud Storage.

      • ‫STALENESS_INTERVAL: מציין אם פעולות שמתבצעות בטבלה משתמשות במטא-נתונים ששמורים במטמון, ומה רמת העדכניות של המטא-נתונים ששמורים במטמון שנדרשת כדי שהפעולה תוכל להשתמש בהם.

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

        כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

        כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מילול של מרווח בין 30 דקות ל-7 ימים. לדוגמה, כדי לציין מרווח של 4 שעות, צריך להזין INTERVAL 4 HOUR. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים ששמורים במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

      • ‫CACHE_MODE: מציין אם המטמון של המטא-נתונים מתרענן באופן אוטומטי או ידני

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

        מגדירים את הערך AUTOMATIC כדי שהמטמון של המטא-נתונים יתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

        מגדירים את הערך MANUAL אם רוצים לרענן את מטמון המטא-נתונים לפי לוח זמנים שקובעים. במקרה כזה, אפשר להתקשר אל BQ.REFRESH_EXTERNAL_METADATA_CACHE הליך המערכת כדי לרענן את המטמון.

        אם מגדירים את STALENESS_INTERVAL לערך גדול מ-0, צריך להגדיר גם את CACHE_MODE.

    3. לוחצים על הפעלה.

    מידע נוסף על הרצת שאילתות זמין במאמר הרצת שאילתה אינטראקטיבית.

    BQ

    כדי לעדכן טבלה, משתמשים בפקודות bq mkdef ו-bq update:

    1. יוצרים הגדרה של טבלה חיצונית שמתארת את ההיבטים של הטבלה שרוצים לשנות:

      bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
--source_format=TABLE_FORMAT \
--metadata_cache_mode=CACHE_MODE \
"BUCKET_PATH" > /tmp/DEFINITION_FILE

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

      • ‫PROJECT_ID: השם של הפרויקט שמכיל את החיבור
      • ‫REGION: האזור שמכיל את החיבור
      • ‫CONNECTION_ID: השם של החיבור שרוצים להשתמש בו
      • ‫TABLE_FORMAT: הפורמט שבו נעשה שימוש בטבלה. אי אפשר לשנות את זה כשמעדכנים את הטבלה.

      • ‫CACHE_MODE: מציין אם מטמון המטא-נתונים מתרענן באופן אוטומטי או ידני. מידע נוסף על שיקולים בנוגע לשמירת מטא-נתונים במטמון זמין במאמר שמירת מטא-נתונים במטמון לשיפור הביצועים.

        מגדירים את הערך AUTOMATIC כדי שהמטמון של המטא-נתונים יתעדכן במרווח זמן שמוגדר על ידי המערכת, בדרך כלל בין 30 ל-60 דקות.

        מגדירים את הערך MANUAL אם רוצים לרענן את מטמון המטא-נתונים לפי לוח זמנים שקובעים. במקרה כזה, אפשר להתקשר אל BQ.REFRESH_EXTERNAL_METADATA_CACHE ההליך של המערכת כדי לרענן את המטמון.

        אם הערך של CACHE_MODE גדול מ-0, צריך להגדיר את STALENESS_INTERVAL.

      • ‫BUCKET_PATH: הנתיב לדלי Cloud Storage שמכיל את הנתונים של הטבלה החיצונית, בפורמט gs://bucket_name/[folder_name/]file_name.

        כדי להגביל את הקבצים שנבחרו מהמאגר, מציינים כוכבית אחת (*) בנתיב. לדוגמה, gs://mybucket/file_name*. מידע נוסף זמין במאמר בנושא תמיכה בתווים כלליים בכתובות URI של Cloud Storage.

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

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

        • gs://bucket/path1/myfile.csv
        • gs://bucket/path1/*.csv
        • gs://bucket/path1/*,gs://bucket/path2/file00*

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

        מידע נוסף על שימוש בכתובות URI של Cloud Storage ב-BigQuery זמין במאמר בנושא נתיב משאב ב-Cloud Storage.

      • ‫DEFINITION_FILE: השם של קובץ הגדרת הטבלה שאתם יוצרים.

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

      bq update --max_staleness=STALENESS_INTERVAL \
--external_table_definition=/tmp/DEFINITION_FILE \
PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

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

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

        כדי להשבית את השמירה במטמון של המטא-נתונים, מציינים את הערך 0. (זוהי ברירת המחדל)

        כדי להפעיל שמירת מטא-נתונים במטמון, צריך לציין ערך של מרווח זמן בין 30 דקות ל-7 ימים, באמצעות הפורמט Y-M D H:M:S שמתואר במסמכי התיעוד של סוג הנתונים INTERVAL. לדוגמה, כדי להגדיר את מרווח הרענון ל-4 שעות, מציינים 0-0 0 4:0:0. אם הערך הזה מוגדר, פעולות שמתבצעות בטבלה משתמשות במטא נתונים שנשמרו במטמון אם הם רעננו ב-4 השעות האחרונות. אם המטא-נתונים שבמטמון ישנים יותר, הפעולה מאחזרת מטא-נתונים מ-Cloud Storage במקום זאת.

      • ‫DEFINITION_FILE: השם של קובץ הגדרת הטבלה שיצרתם או עדכנתם.

      • ‫PROJECT_ID: שם הפרויקט שמכיל את הטבלה

      • ‫DATASET: השם של מערך הנתונים שמכיל את הטבלה

      • ‫EXTERNAL_TABLE_NAME: שם הטבלה

    דוגמה

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

    bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

    כאשר enable_metadata.json מכיל את התוכן הבא: json { "metadataCacheMode": "AUTOMATIC" }

    רישום ביומן ביקורת

    מידע על רישום ביומן ב-BigQuery זמין במאמר מבוא לניטור ב-BigQuery. מידע נוסף על כניסה זמין במאמר בנושא Cloud Logging. Google Cloud

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