טעינת נתוני Avro מ-Cloud Storage

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

למידע על טעינת נתוני Avro מקובץ מקומי, ראו טעינת נתונים ל-BigQuery ממקור נתונים מקומי.

מגבלות

כשאתם טוענים נתונים ל-BigQuery מקטגוריה של Cloud Storage, אתם כפופים למגבלות הבאות:

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

המגבלות הבאות חלות גם כשמבצעים טעינה של קובצי Avro ל-BigQuery:

  • ב-BigQuery אי אפשר לטעון קובצי סכימה נפרדים של Avro‏ (‎.avsc).
  • אין תמיכה בפורמט של מערך בתוך מערך ב-BigQuery. צריך להמיר קובצי Avro שמשתמשים בפורמט הזה לפני הייבוא.
  • בקובץ Avro, השמות ומרחבי השמות של שם מלא יכולים להכיל רק תווים אלפאנומריים ואת תו הקו התחתון _. הביטוי הרגולרי הבא מציג את התווים המותרים: [A-Za-z_][A-Za-z0-9_]*.

למידע על המגבלות של משימות טעינה ב-BigQuery, קראו את המאמר משימות טעינה.

הדרישות לגבי קובץ הקלט

כדי להימנע משגיאות resourcesExceeded כשאתם טוענים קובצי Avro ל-BigQuery, כדאי לפעול לפי ההנחיות הבאות:

  • גודל השורות צריך להיות עד 50MB.
  • אם השורה מכילה הרבה שדות של מערכים, או שדות של מערכים ארוכים מאוד, פצלו את ערכי המערכים לשדות נפרדים.

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

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

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

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

הרשאות לטעינת נתונים ל-BigQuery

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

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

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

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • ‫roles/bigquery.admin (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.user (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.jobUser (כולל את ההרשאה bigquery.jobs.create)

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

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

הרשאות לטעינת נתונים מ-Cloud Storage

כדי לקבל את ההרשאות שנדרשות לטעינת נתונים מקטגוריה של Cloud Storage, בקשו מהאדמין לתת לכם את התפקיד אדמין של אחסון (roles/storage.admin) ב-IAM בקטגוריה. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

כדי לטעון נתונים מקטגוריה של Cloud Storage, נדרשות ההרשאות הבאות:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

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

יצירת מערך נתונים וטבלה

כדי לאחסן את הנתונים, צריך ליצור מערך נתונים ב-BigQuery, ואז ליצור טבלה ב-BigQuery בתוך מערך הנתונים הזה.

היתרונות של Avro

‫Avro הוא הפורמט המועדף לטעינת נתונים ל-BigQuery. לטעינת קובצי Avro יש את היתרונות הבאים על פני קובצי CSV ו-JSON (מופרדים באמצעות שורה חדשה):

  • הפורמט הבינארי של Avro:
    • נטען מהר יותר. אפשר לקרוא את הנתונים במקביל, גם אם בלוקי הנתונים דחוסים.
    • לא צריך להקליד או להגדיר סריאליזציה.
    • קל יותר לנתח אותו כי אין בעיות קידוד כמו בפורמטים אחרים, למשל ASCII.
  • כשאתם טוענים קובצי Avro ל-BigQuery, סכימת הטבלה מאוחזרת באופן אוטומטי מנתוני המקור שמתארים את עצמם.

סכימות של Avro

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

לדוגמה, נניח שיש לכם את קובצי ה-Avro הבאים ב-Cloud Storage:

gs://mybucket/00/
  a.avro
  z.avro
gs://mybucket/01/
  b.avro

הרצת הפקודה הזו בכלי שורת הפקודה של BigQuery טוענת את כל הקבצים (כרשימה מופרדת בפסיקים), והסכימה נגזרת מ-mybucket/01/b.avro:

bq load \
--source_format=AVRO \
dataset.table \
"gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

כשמייבאים כמה קובצי Avro עם סכימות Avro שונות, כל הסכימות צריכות להיות תואמות לרזולוציית הסכימה של Avro.

כש-BigQuery מזהה את הסכימה, חלק מסוגי הנתונים של Avro מומרים לסוגי נתונים של BigQuery כדי שיהיו תואמים לתחביר של GoogleSQL. מידע נוסף זמין במאמר המרות של Avro.

כדי לספק סכימת טבלה ליצירת טבלאות חיצוניות, מגדירים את המאפיין referenceFileSchemaUri ב-BigQuery API או את הפרמטר
--reference_file_schema_uri בכלי שורת הפקודה של BigQuery לכתובת ה-URL של קובץ רפרנס.

לדוגמה, --reference_file_schema_uri="gs://mybucket/schema.avro".

אפשר גם לייבא סכימה ל-BigQuery על ידי ציון קובץ סכימה בפורמט JSON.

דחיסת Avro

‫BigQuery תומך בקודקים הבאים לדחיסת תוכן של קובצי Avro:

  • Snappy
  • DEFLATE
  • ZSTD

טעינת נתוני Avro לטבלה חדשה

כדי לטעון נתוני Avro מ-Cloud Storage לטבלה חדשה ב-BigQuery, בוחרים באחת מהאפשרויות הבאות:

המסוף

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

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

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

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

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

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

  5. בדף Create table, בקטע Source:

    • בקטע Create table from, בוחרים באפשרות Google Cloud Storage.

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

      בחירת קובץ

    • בשדה פורמט קובץ, בוחרים באפשרות Avro.

  6. בדף Create table, בקטע Destination:

    • בקטע Dataset name, בוחרים את מערך הנתונים המתאים.
    • מוודאים שהשדה Table type מוגדר ל-Native table.
    • בשדה Table name, מזינים את שם הטבלה שיוצרים ב-BigQuery.

  7. בקטע Schema, לא צריך לעשות כלום. הסכימה מתוארת בקובצי Avro.

  8. (אופציונלי) כדי לחלק את הטבלה למחיצות, בוחרים את האפשרויות הרצויות בקטע Partition and cluster settings. מידע נוסף זמין במאמר יצירת טבלאות מחולקות למחיצות.

  9. (אופציונלי) בקטע Partitioning filter, לוחצים על התיבה Require partition filter כדי לדרוש מהמשתמשים לכלול משפט WHERE שמציין את המחיצות שרוצים לשלוח אליהן שאילתות. דרישה למסנן מחיצה יכולה להפחית את העלות ולשפר את הביצועים. למידע נוסף, קראו את המאמר דרישה למסנן מחיצות בשאילתות. האפשרות הזו לא זמינה אם בוחרים באפשרות ללא חלוקה למחיצות.

  10. (אופציונלי) כדי לאסוף באשכולות את הטבלה, מזינים בין אחד לארבעה שמות של שדות בתיבה Clustering order.

  11. (אופציונלי) לוחצים על אפשרויות מתקדמות.

    • בשדה Write preference, משאירים את האפשרות Write if empty מסומנת. האפשרות הזו יוצרת טבלה חדשה וטוענת אליה את הנתונים.
    • בקטע Unknown values, משאירים את התיבה Ignore unknown values לא מסומנת. האפשרות הזו רלוונטית רק לקובצי CSV ו-JSON.
    • בקטע Encryption, לוחצים על Customer-managed key כדי להשתמש במפתח של Cloud Key Management Service. אם משאירים את ההגדרה Google-managed key, הנתונים מוצפנים במצב מנוחה ב-BigQuery.

  12. לוחצים על Create table.

SQL

משתמשים בהצהרת ה-DDL‏ LOAD DATA. בדוגמה הבאה נטען קובץ Avro לטבלה החדשה mytable:

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

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

    LOAD DATA OVERWRITE mydataset.mytable
FROM FILES (
  format = 'avro',
  uris = ['gs://bucket/path/file.avro']);

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

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

BQ

משתמשים בפקודה bq load, מציינים את AVRO באמצעות הדגל --source_format וכוללים URI של Cloud Storage. אפשר לכלול URI יחיד, רשימה מופרדת בפסיקים של מזהי URI, או URI שמכיל תו כללי לחיפוש.

(אופציונלי) מציינים את הדגל --location ומגדירים את הערך למיקום שלכם.

דגלים אופציונליים נוספים:

  • ‫--time_partitioning_type: הפעלת חלוקה למחיצות לפי זמן בטבלה והגדרת סוג המחיצה. הערכים האפשריים הם HOUR,‏ DAY,‏ MONTH ו-YEAR. הדגל הזה הוא אופציונלי כשיוצרים טבלה שמחולקת למחיצות לפי עמודה מסוג DATE, DATETIME או TIMESTAMP. סוג המחיצה שמוגדר כברירת מחדל לחלוקה למחיצות לפי זמן הוא DAY. אי אפשר לשנות את מפרט החלוקה למחיצות בטבלה קיימת.
  • ‫--time_partitioning_expiration: מספר שלם שמציין (בשניות) מתי צריך למחוק מחיצה שמבוססת על זמן. זמן התפוגה מחושב לפי תאריך ה-UTC של המחיצה בתוספת ערך המספר השלם.
  • ‫--time_partitioning_field: העמודה DATE או TIMESTAMP שמשמשת ליצירת טבלה מחולקת למחיצות. אם מפעילים חלוקה למחיצות לפי זמן בלי הערך הזה, נוצרת טבלה מחולקת למחיצות לפי זמני כתיבת הנתונים.
  • ‫--require_partition_filter: כשהאפשרות הזו מופעלת, המשתמשים צריכים לכלול משפט WHERE שמציין את המחיצות שרוצים לשלוח אליהן שאילתות. דרישה למסנן מחיצות יכולה להפחית את העלות ולשפר את הביצועים. מידע נוסף זמין במאמר דרישה למסנן מחיצות בשאילתות.
  • ‫--clustering_fields: רשימה מופרדת בפסיקים של עד ארבעה שמות עמודות שמשמשים ליצירת טבלה מסודרת באשכולות.

  • ‫--destination_kms_key: המפתח של Cloud KMS להצפנת נתוני הטבלה.

    למידע נוסף על טבלאות מחולקות למחיצות:

    מידע נוסף על טבלאות מסודרות באשכולות:

    מידע נוסף על הצפנת טבלאות זמין במאמרים הבאים:

כדי לטעון נתוני Avro ל-BigQuery, מזינים את הפקודה הבאה:

bq --location=location load \
--source_format=format \
dataset.table \
path_to_source

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

  • location הוא המיקום שלך. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ bigqueryrc..
  • format הוא AVRO.
  • ‫dataset הוא מערך נתונים קיים.
  • ‫table הוא שם הטבלה שאליה טוענים את הנתונים.
  • ‫path_to_source הוא URI של Cloud Storage מלא או רשימה מופרדת בפסיקים של מזהי URI. יש גם תמיכה בתווים כלליים לחיפוש.

דוגמאות:

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.avro לטבלה בשם mytable ב-mydataset.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.avro לטבלה מחולקת למחיצות (Partitions) לפי זמני כתיבת הנתונים בשם mytable ב-mydataset.

    bq load \
    --source_format=AVRO \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.avro

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.avro לטבלה חדשה מחולקת למחיצות בשם mytable ב-mydataset. הטבלה מחולקת למחיצות לפי העמודה mytimestamp.

    bq load \
    --source_format=AVRO \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.avro

הפקודה הבאה טוענת נתונים מכמה קבצים ב-gs://mybucket/ לטבלה בשם mytable ב-mydataset. ה-URI של Cloud Storage כולל תו כללי לחיפוש.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

הפקודה הבאה טוענת נתונים מכמה קבצים ב-gs://mybucket/ לטבלה בשם mytable ב-mydataset. הפקודה כוללת רשימה מופרדת בפסיקים של מזהי URI של Cloud Storage עם תווים כלליים לחיפוש.

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

API

  1. יוצרים משימת load שמפנה לנתוני המקור ב-Cloud Storage.

  2. (אופציונלי) מציינים את המיקום במאפיין location בקטע jobReference של משאב המשימה.

  3. המאפיין source URIs חייב להיות מלא, בפורמט gs://bucket/object. כל URI יכול להכיל תו כללי לחיפוש אחד, "*".

  4. מציינים את פורמט הנתונים של Avro על ידי הגדרת המאפיין sourceFormat לערך AVRO.

  5. כדי לבדוק את סטטוס המשימה, מפעילים את jobs.get(job_id), כאשר job_id הוא מזהה המשימה שהוחזר בבקשה הראשונית.

    • אם הערך הוא status.state = DONE, המשימה הושלמה בהצלחה.
    • אם המאפיין status.errorResult קיים, הבקשה נכשלה והאובייקט הזה יכלול מידע שמתאר מה השתבש. אם הבקשה נכשלת, לא נוצרת טבלה ולא נטענים נתונים.
    • אם status.errorResult לא מופיע, המשימה הסתיימה בהצלחה, אבל יכול להיות שהיו כמה שגיאות לא קריטיות, כמו בעיות בייבוא של כמה שורות. שגיאות לא קריטיות מופיעות במאפיין status.errors של אובייקט המשימה שמוחזר.

הערות לגבי ה-API:

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

  • מומלץ ליצור מזהה ייחודי ולהעביר אותו בתור jobReference.jobId כשקוראים ל-jobs.insert כדי ליצור משימת טעינה. הגישה הזו עמידה יותר בפני כשלים ברשת, כי הלקוח יכול לבצע דגימה או לנסות שוב באמצעות מזהה המשימה הידוע.

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

המשך

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Go API.

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Java API.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load Avro data from Cloud Storage into a new BigQuery table
public class LoadAvroFromGCS {

  public static void runLoadAvroFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCS(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCS(String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Avro from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Node.js API.

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvro() {
  // Imports a GCS file into a table with Avro source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {sourceFormat: 'AVRO'},
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Python API.

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(source_format=bigquery.SourceFormat.AVRO)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

חילוץ נתוני JSON מנתוני Avro

יש שתי דרכים לוודא שנתוני Avro נטענים ל-BigQuery כנתוני JSON:

  1. מוסיפים הערות לסכימת Avro עם sqlType שמוגדר ל-JSON. לדוגמה, אם טוענים נתונים עם סכימת Avro הבאה, העמודה json_field נקראת כסוג JSON:

    {
    "type": {"type": "string", "sqlType": "JSON"},
    "name": "json_field"
}

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

אם לא מציינים JSON כסוג בסכימת Avro או בסכימת הטבלה ב-BigQuery, הנתונים ייקראו כ-STRING.

הוספה לטבלה או החלפה של טבלה עם נתוני Avro

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

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

כשאתם טוענים נתונים נוספים לטבלה, יש לכם את האפשרויות הבאות:

אפשרות המסוף דגל של הכלי bq נכס BigQuery API תיאור
כתיבה אם ריק לא נתמך WRITE_EMPTY הנתונים נכתבים רק אם הטבלה ריקה.
הוספה לטבלה ‫--noreplace או --replace=false; אם לא צוין --[no]replace, ברירת המחדל היא append WRITE_APPEND (ברירת המחדל) הוספת הנתונים לסוף הטבלה.
החלפת הטבלה --replace או --replace=true WRITE_TRUNCATE מוחק את כל הנתונים הקיימים בטבלה לפני כתיבת הנתונים החדשים. הפעולה הזו גם מוחקת את סכימת הטבלה, את האבטחה ברמת השורה ואת כל מפתחות Cloud KMS.

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

כדי להוסיף נתוני Avro לטבלה או להחליף אותם:

המסוף

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

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

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

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

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

  5. בדף Create table, בקטע Source:

    • בקטע Create table from, בוחרים באפשרות Cloud Storage.

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

      בחירת קובץ

    • בשדה פורמט קובץ, בוחרים באפשרות Avro.

  6. בדף Create table, בקטע Destination:

    • בקטע Dataset name, בוחרים את מערך הנתונים המתאים.

      בחירת מערך נתונים

    • בשדה Table name, מזינים את שם הטבלה שרוצים להוסיף או להחליף ב-BigQuery.

    • מוודאים שהשדה Table type מוגדר ל-Native table.

  7. בקטע Schema, לא צריך לעשות כלום. הסכימה מתוארת בקובצי Avro.

  8. בקטע Partition and cluster settings, משאירים את ערכי ברירת המחדל. אי אפשר להמיר טבלה לטבלה מחולקת למחיצות או לטבלה מסודרת באשכולות על ידי הוספה או החלפה שלה, ואי אפשר להשתמש במסוף Google Cloud כדי להוסיף או להחליף טבלאות מחולקות למחיצות או טבלאות מסודרות באשכולות במשימת טעינה.

  9. לוחצים על אפשרויות מתקדמות.

    • בקטע Write preference, בוחרים באפשרות Append to table או Overwrite table.
    • בקטע Unknown values, משאירים את התיבה Ignore unknown values לא מסומנת. האפשרות הזו רלוונטית רק לקובצי CSV ו-JSON.
    • בקטע Encryption, לוחצים על Customer-managed key כדי להשתמש במפתח של Cloud Key Management Service. אם משאירים את ההגדרה Google-owned and managed key, הנתונים מוצפנים במצב מנוחה ב-BigQuery.

  10. לוחצים על Create table.

SQL

משתמשים בהצהרת ה-DDL‏ LOAD DATA. בדוגמה הבאה, קובץ Avro נוסף לטבלה mytable:

  1. נכנסים לדף BigQuery במסוף Google Cloud .

    כניסה ל-BigQuery

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

    LOAD DATA INTO mydataset.mytable
FROM FILES (
  format = 'avro',
  uris = ['gs://bucket/path/file.avro']);

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

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

BQ

מזינים את הפקודה bq load עם הדגל --replace כדי להחליף את הטבלה. משתמשים בדגל --noreplace כדי להוסיף נתונים לטבלה. אם לא מציינים דגל, ברירת המחדל היא להוסיף נתונים. מציינים את הדגל --source_format ומגדירים אותו לערך AVRO. מכיוון שהסכימות של Avro מאוחזרות באופן אוטומטי מנתוני המקור שמתארים את עצמם, אין צורך לספק הגדרת סכימה.

(אופציונלי) מציינים את הדגל --location ומגדירים את הערך למיקום שלכם.

דגלים אופציונליים נוספים:

  • ‫--destination_kms_key: המפתח של Cloud KMS להצפנת נתוני הטבלה.
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

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

  • location הוא המיקום שלך. הדגל --location הוא אופציונלי. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ bigqueryrc..
  • format הוא AVRO.
  • ‫dataset הוא מערך נתונים קיים.
  • ‫table הוא שם הטבלה שאליה טוענים את הנתונים.
  • ‫path_to_source הוא URI של Cloud Storage מלא או רשימה מופרדת בפסיקים של מזהי URI. יש גם תמיכה בתווים כלליים לחיפוש.

דוגמאות:

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.avro ומחליפה טבלה בשם mytable ב-mydataset.

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.avro ומוסיפה נתונים לטבלה בשם mytable ב-mydataset.

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

API

  1. יוצרים משימת load שמפנה לנתוני המקור ב-Cloud Storage.

  2. (אופציונלי) מציינים את המיקום במאפיין location בקטע jobReference של משאב המשימה.

  3. המאפיין source URIs צריך להיות מלא, בפורמט gs://bucket/object. אפשר לכלול כמה מזהי URI ברשימה מופרדת בפסיקים. שימו לב שאפשר להשתמש גם בתווים כלליים לחיפוש.

  4. מציינים את פורמט הנתונים על ידי הגדרת המאפיין configuration.load.sourceFormat לערך AVRO.

  5. מציינים את העדפת הכתיבה על ידי הגדרת המאפיין configuration.load.writeDisposition לערך WRITE_TRUNCATE או WRITE_APPEND.

המשך

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Go במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Go API.

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Java במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Java API.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a AVRO file from GCS
public class LoadAvroFromGCSTruncate {

  public static void runLoadAvroFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro";
    loadAvroFromGCSTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadAvroFromGCSTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.avro())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS Avro file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by AVRO file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Node.js במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Node.js API.

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Avro file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.avro
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.avro';

async function loadTableGCSAvroTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'us_states';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const jobConfigurationLoad = {
    load: {
      sourceFormat: 'AVRO',
      writeDisposition: 'WRITE_TRUNCATE',
    },
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), jobConfigurationLoad);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי הוראות ההגדרה של Python במדריך למתחילים של BigQuery באמצעות ספריות לקוח. למידע נוסף, קראו את מאמרי העזרה של BigQuery Python API.

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

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.AVRO,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

טעינת נתוני Avro שחולקו למחיצות ב-Hive

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

המרות של Avro

‫BigQuery ממיר את סוגי הנתונים של Avro לסוגי הנתונים הבאים של BigQuery:

סוגים פרימיטיביים

סוג נתונים של Avro בלי המאפיין logicalType סוג הנתונים ב-BigQuery הערות
null מערכת BigQuery מתעלמת מהערכים האלה
בוליאני בוליאני
int מספר שלם
ארוך מספר שלם
מספר ממשי (float) FLOAT
double FLOAT
בייטים BYTES
מחרוזת מחרוזת רק UTF-8

סוגים לוגיים

כברירת מחדל, BigQuery מתעלם מהמאפיין logicalType ברוב הסוגים ומשתמש במקום זאת בסוג Avro הבסיסי. כדי להמיר סוגים לוגיים של Avro לסוגי הנתונים התואמים ב-BigQuery, מגדירים את הדגל --use_avro_logical_types לערך true באמצעות כלי שורת הפקודה של BigQuery, או מגדירים את המאפיין useAvroLogicalTypes במשאב המשימה כשמפעילים את השיטה jobs.insert כדי ליצור משימת טעינה.

בטבלה הבאה מוצגת ההמרה של סוגים לוגיים של Avro לסוגי נתונים של BigQuery.

סוג לוגי של Avro סוג נתונים ב-BigQuery: סוג לוגי מושבת סוג נתונים ב-BigQuery: סוג לוגי מופעל
תאריך מספר שלם תאריך
time-millis מספר שלם שעה
time-micros מספר שלם (הומר מ-LONG) שעה
timestamp-millis מספר שלם (הומר מ-LONG) TIMESTAMP
timestamp-micros מספר שלם (הומר מ-LONG) TIMESTAMP
local-timestamp-millis מספר שלם (הומר מ-LONG) DATETIME
local-timestamp-micros מספר שלם (הומר מ-LONG) DATETIME
משך זמן BYTES (הומר מ-fixed מסוג גודל 12) BYTES (הומר מסוג fixed בגודל 12)
עשרוני NUMERIC,‏ BIGNUMERIC או STRING (ראו סוג לוגי עשרוני) NUMERIC,‏ BIGNUMERIC או STRING (ראו סוג לוגי עשרוני)

למידע נוסף על סוגי נתונים של Avro, קראו את המפרט של Apache Avro™ 1.8.2.

סוג לוגי של תאריך

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

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

סוג לוגי עשרוני

אפשר להמיר סוגים לוגיים של Decimal לסוגים של NUMERIC,‏ BIGNUMERIC או STRING. הסוג שאליו מתבצעת ההמרה תלוי בפרמטרים של הדיוק והקנה מידה של הסוג הלוגי decimal ובסוגי היעד העשרוניים שצוינו. מציינים את סוג היעד העשרוני באופן הבא:

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

למידע נוסף על הסוג הלוגי decimal של Avro, קראו את המפרט של Apache Avro™ 1.8.2.

סוג לוגי של זמן

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

לדיוק של אלפית השנייה:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

לדיוק של מיקרו-שנייה:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

סוג לוגי של חותמת זמן

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

לדיוק של אלפית השנייה:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

לדיוק של מיקרו-שנייה:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

סוג לוגי של חותמת זמן מקומית

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

לדיוק של אלפית השנייה:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

לדיוק של מיקרו-שנייה:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

סוגים מורכבים

סוג הנתונים של Avro סוג הנתונים ב-BigQuery הערות
הקלטה רשומה
  • המערכת מתעלמת מכתובות אימייל חלופיות
  • המסמך מומר לתיאור שדה
  • ערכי ברירת המחדל מוגדרים בזמן הקריאה
  • המערכת מתעלמת מההזמנה
  • שדות רקורסיביים מושמטים – רק הרמה הראשונה של הסידור הפנימי נשמרת בשדות רקורסיביים
טיפוסים בני מנייה (enum) מחרוזת
  • המחרוזת היא הערך הסמלי של ה-enum
  • המערכת מתעלמת מכתובות אימייל חלופיות
  • המסמך מומר לתיאור שדה
מערך שדות חוזרים אין תמיכה במערכים של מערכים. המערכת מתעלמת ממערכים שמכילים רק סוגי NULL.
thought map<T> רשומה ‫BigQuery ממיר שדה map<T> של Avro לשדה RECORD חוזר שמכיל שני שדות: מפתח וערך. ‫BigQuery מאחסן את המפתח כ-STRING, וממיר את הערך לסוג הנתונים התואם ב-BigQuery.
union
  • שדה שיכול להיות ריק
  • ‫RECORD עם רשימה של שדות שיכולים להיות ריקים
  • כשהאיחוד מכיל רק סוג אחד שאינו null, הוא מומר לשדה שניתן להגדיר כ-null.
  • אחרת, הוא מומר ל-RECORD עם רשימה של שדות שניתן להגדיר כ-null. רק אחד מהשדות האלה יוגדר בזמן הקריאה.
קבוע BYTES
  • המערכת מתעלמת מכתובות אימייל חלופיות
  • המערכת מתעלמת מהגודל