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

בדף הזה מוסבר איך לטעון נתוני Parquet מ-Cloud Storage ל-BigQuery.

‫Parquet הוא פורמט נתונים מבוסס-עמודות בקוד פתוח, שנמצא בשימוש נרחב בסביבה העסקית של Apache Hadoop.

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

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

למידע על טעינת נתוני Parquet מקובץ מקומי, ראו טעינת נתונים מקבצים מקומיים.

מגבלות

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

  • ‫BigQuery לא מבטיח עקביות נתונים במקורות נתונים חיצוניים. שינויים בנתוני הבסיס בזמן הפעלת שאילתה עלולים לגרום להתנהגות לא צפויה.

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

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

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

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

  • גודל השורה צריך להיות עד 50MB.
  • אם נתוני הקלט מכילים יותר מ-100 עמודות, כדאי להקטין את גודל הדף כך שיהיה קטן מגודל הדף שמוגדר כברירת מחדל (1 * 1,024 * 1,024 בייט). האפשרות הזו שימושית במיוחד אם אתם משתמשים בדחיסה משמעותית.
  • כדי לקבל ביצועים אופטימליים, כדאי לשאוף לגודל של לפחות 16MiB לקבוצת שורות. גודל קטן יותר של קבוצות שורות מגדיל את קלט/פלט ומאט את הטעינות והשאילתות.

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

להקצות תפקידים של ניהול זהויות והרשאות גישה (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, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM אדמין לניהול אחסון (roles/storage.admin) בקטגוריה. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

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

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

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

יצירת מערך נתונים

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

סכימות של Parquet

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

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

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

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

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

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

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

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

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

דחיסה ב-Parquet

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

  • GZip
  • LZO_1C
  • LZO_1X
  • LZ4_RAW
  • Snappy
  • ZSTD

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

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

  • מסוף Google Cloud
  • הפקודה bq load בכלי שורת הפקודה bq
  • השיטה jobs.insert של API והגדרת משימה load
  • ספריות הלקוח

כדי לטעון נתוני Parquet מ-Cloud Storage לטבלה חדשה ב-BigQuery:

המסוף

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

    כניסה לדף BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים.
  3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
  4. בקטע פרטי מערך הנתונים, לוחצים על יצירת טבלה.
  5. בחלונית Create table, מציינים את הפרטים הבאים:
    1. בקטע מקור, בוחרים באפשרות Google Cloud Storage ברשימה יצירת טבלה מ. לאחר מכן, מבצעים את הפעולות הבאות:
      1. בוחרים קובץ מתוך הקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה כתובות URI במסוף Google Cloud , אבל אפשר להשתמש בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה. בוחרים קובץ מקור כדי ליצור טבלה ב-BigQuery
      2. בקטע File format (פורמט קובץ), בוחרים באפשרות Parquet.
    2. בקטע יעד, מציינים את הפרטים הבאים:
      1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
      3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
    3. בקטע Schema (סכימה), לא צריך לבצע פעולה כלשהי. הסכימה מתוארת בעצמה בקובצי Parquet.
    4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות.
    5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
      • בקטע העדפות כתיבה, משאירים את האפשרות כתיבה אם ריק מסומנת. האפשרות הזו יוצרת טבלה חדשה וטוענת לתוכה את הנתונים.
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
    6. לוחצים על יצירת טבלה.

SQL

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

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

    כניסה ל-BigQuery

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

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

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

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

BQ

משתמשים בפקודה bq load, מציינים את PARQUET באמצעות הדגל --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 להצפנה של נתוני הטבלה.

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

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

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

    מידע נוסף על הצפנת טבלאות

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

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

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

  • ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ ‎.bigqueryrc.
  • FORMAT: PARQUET.
  • DATASET: מערך נתונים קיים.
  • ‫TABLE: שם הטבלה שאליה טוענים את הנתונים.
  • ‫PATH_TO_SOURCE: URI של Cloud Storage מוגדר במלואו או רשימה מופרדת בפסיקים של מזהי URI. יש תמיכה גם בתווים כלליים לחיפוש.

דוגמאות:

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

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

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

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

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

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

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

API

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

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

  3. המאפיין source URIs צריך להיות מוגדר במלואו, בפורמט gs://BUCKET/OBJECT. כל URI יכול להכיל תו כללי אחד לחיפוש '*' .

  4. מגדירים את מאפיין sourceFormat לערך PARQUET כדי לציין את פורמט הנתונים Parquet.

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

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

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

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

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

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

Go

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

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

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    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();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \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 Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

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

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

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

  // 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), metadata);

  // 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;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

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

כדי להתחיל עבודת טעינה מ-Cloud Storage, משתמשים בשיטה Client.load_table_from_uri(). כדי להשתמש ב-Parquet, צריך להגדיר את המאפיין LoadJobConfig.source_format למחרוזת PARQUET ולהעביר את הגדרות המשימה כארגומנט job_config לשיטה load_table_from_uri(). 
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.PARQUET,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

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))

הוספה לטבלה או החלפה של נתונים בטבלה באמצעות נתוני Parquet

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

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

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

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

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

אפשר להוסיף נתונים לטבלה או להחליף את הנתונים הקיימים באמצעות אחת מהאפשרויות הבאות:

  • מסוף Google Cloud
  • הפקודה bq load בכלי שורת הפקודה bq
  • השיטה jobs.insert של API והגדרת משימה load
  • ספריות הלקוח

כדי להוסיף נתונים לטבלה או להחליף את הנתונים בטבלה באמצעות נתוני Parquet:

המסוף

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

    כניסה לדף BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים.
  3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
  4. בקטע פרטי מערך הנתונים, לוחצים על יצירת טבלה.
  5. בחלונית Create table, מציינים את הפרטים הבאים:
    1. בקטע מקור, בוחרים באפשרות Google Cloud Storage ברשימה יצירת טבלה מ. לאחר מכן, מבצעים את הפעולות הבאות:
      1. בוחרים קובץ מתוך הקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה כתובות URI במסוף Google Cloud , אבל אפשר להשתמש בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה. בוחרים קובץ מקור כדי ליצור טבלה ב-BigQuery
      2. בקטע File format (פורמט קובץ), בוחרים באפשרות Parquet.
    2. בקטע יעד, מציינים את הפרטים הבאים:
      1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
      3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
    3. בקטע Schema (סכימה), לא צריך לבצע פעולה כלשהי. הסכימה מתוארת בעצמה בקובצי Parquet.
    4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות. אי אפשר להמיר טבלה לטבלה מחולקת או לטבלה מסודרת באשכולות על ידי הוספה או החלפה שלה. Google Cloud מסוף Google Cloud לא תומך בהוספה לטבלאות מחולקות או מקובצות או בהחלפה שלהן בעבודת טעינה.
    5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
      • בקטע Write preference (העדפת כתיבה), בוחרים באפשרות Append to table (הוספה לטבלה) או Overwrite table (החלפת הטבלה).
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
    6. לוחצים על יצירת טבלה.

SQL

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

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

    כניסה ל-BigQuery

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

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

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

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

BQ

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

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

דגלים אופציונליים אחרים:

  • ‫--destination_kms_key: מפתח Cloud KMS להצפנה של נתוני הטבלה.
bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

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

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

דוגמאות:

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

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

API

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

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

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

  4. מגדירים את פורמט הנתונים באמצעות הנכס configuration.load.sourceFormat עם הערך PARQUET.

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

Go

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

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

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    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();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \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 CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * 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 = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // 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), metadata);
  // 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;
  }
}

PHP

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

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

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

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

כדי לצרף את השורות לטבלה קיימת, צריך להגדיר את המאפיין LoadJobConfig.write_disposition לערך WRITE_APPEND.

כדי להחליף את השורות בטבלה קיימת, מגדירים את המאפיין LoadJobConfig.write_disposition לערך WRITE_TRUNCATE. 

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.PARQUET,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
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))

טעינה של נתוני Parquet עם חלוקה למחיצות ב-Hive

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

המרות של קובצי Parquet

בקטע הזה מתואר איך BigQuery מנתח סוגים שונים של נתונים כשמעלים נתוני Parquet.

אפשר להמיר חלק מסוגי הנתונים של Parquet (כמו INT32,‏ INT64,‏ BYTE_ARRAY ו-FIXED_LEN_BYTE_ARRAY) לכמה סוגי נתונים של BigQuery. כדי לוודא ש-BigQuery ממיר את סוגי הנתונים של Parquet בצורה נכונה, צריך לציין את סוג הנתונים המתאים בקובץ Parquet.

לדוגמה, כדי להמיר את סוג הנתונים Parquet INT32 לסוג הנתונים BigQuery DATE, מציינים את הפרטים הבאים:

optional int32 date_col (DATE);

‫BigQuery ממיר סוגי נתונים של Parquet לסוגי הנתונים של BigQuery שמתוארים בקטעים הבאים.

המרות של סוגים

סוג Parquet סוגים לוגיים של Parquet סוג נתונים ב-BigQuery
BOOLEAN ללא בוליאני
INT32 אין, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32) INT64
INT32 DECIMAL NUMERIC,‏ BIGNUMERIC או STRING
INT32 DATE תאריך
INT64 ללא, INTEGER (UINT_64, INT_64) INT64
INT64 DECIMAL NUMERIC,‏ BIGNUMERIC או STRING
INT64 TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS) TIMESTAMP
INT64 TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS) TIMESTAMP
INT96 ללא TIMESTAMP
FLOAT ללא FLOAT64
DOUBLE ללא FLOAT64
BYTE_ARRAY ללא BYTES
BYTE_ARRAY STRING (UTF8) מחרוזת
FIXED_LEN_BYTE_ARRAY DECIMAL NUMERIC,‏ BIGNUMERIC או STRING
FIXED_LEN_BYTE_ARRAY ללא BYTES

קבוצות בתוך קבוצות מומרות לסוגים STRUCT. אין תמיכה בשילובים אחרים של סוגי Parquet וסוגים שהומרו.

סוגים לוגיים לא חתומים

הסוגים UINT_8, UINT_16, UINT_32 ו-UINT_64 של Parquet הם ללא סימן. מערכת BigQuery תתייחס לערכים מהסוגים האלה כאל ערכים לא חתומים כשהיא תטען אותם לעמודה INTEGER חתומה ב-BigQuery. במקרה של UINT_64, אם הערך הלא חתום חורג מהערך המקסימלי של INTEGER שהוא 9,223,372,036,854,775,807, תוחזר שגיאה.

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

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

סוג לוגי של טיפוסים בני מנייה (enum)

אפשר להמיר סוגים לוגיים של Enum ל-STRING או ל-BYTES. מציינים את סוג היעד שהומר באופן הבא:

סוג לוגי של רשימה

אפשר להפעיל היסק סכימה עבור סוגים לוגיים של Parquet LIST. ‫BigQuery בודק אם הצומת LIST נמצא בפורמט סטנדרטי או באחד מהפורמטים שמתוארים בכללי התאימות לאחור:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

אם התשובה היא כן, השדה המתאים לצומת LIST בסכימה שהומרה מטופל כאילו לצומת יש את הסכימה הבאה:

repeated <element-type> <name>

הצמתים list ו-element לא נכללים.

נתונים גיאו-מרחביים

אפשר לטעון קובצי Parquet שמכילים WKT, ‏ WKB בקידוד הקסדצימלי או GeoJSON בעמודה STRING, או WKB בעמודה BYTE_ARRAY, על ידי ציון סכימת BigQuery עם הסוג GEOGRAPHY. מידע נוסף זמין במאמר בנושא טעינת נתונים גיאו-מרחביים.

אפשר גם לטעון קובצי GeoParquet. במקרה כזה, העמודות שמתוארות במטא-נתונים של GeoParquet מפורשות כסוג GEOGRAPHYכברירת מחדל. אפשר גם לטעון את נתוני ה-WKB הגולמיים לעמודה BYTES על ידי ציון סכימה מפורשת. מידע נוסף זמין במאמר בנושא טעינת קובצי GeoParquet.

המרות של שמות עמודות

שם העמודה יכול להכיל אותיות (a-z, A-Z), מספרים (0-9) או קווים תחתונים (_), והוא חייב להתחיל באות או בקו תחתון. אם משתמשים בשמות עמודות גמישים, ב-BigQuery אפשר להתחיל שם של עמודה במספר. יש לנקוט משנה זהירות כשמתחילים עמודות במספר, מכיוון ששימוש בשמות עמודות גמישים עם BigQuery Storage Read API או BigQuery Storage Write API דורש טיפול מיוחד. מידע נוסף על תמיכה בשמות גמישים של עמודות זמין במאמר שמות גמישים של עמודות.

האורך המקסימלי של שמות העמודות הוא 300 תווים. בשמות של עמודות אי אפשר להשתמש באף אחת מהתחיליות הבאות:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER
  • _CHANGE_SEQUENCE_NUMBER
  • _CHANGE_TYPE
  • _CHANGE_TIMESTAMP

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

אם שם הטבלה (לדוגמה, test) זהה לאחד משמות העמודות שלה (לדוגמה, test), הביטוי SELECT מפרש את העמודה test כSTRUCT שמכילה את כל העמודות האחרות בטבלה. כדי להימנע מהתנגשות כזו, אפשר להשתמש באחת מהשיטות הבאות:

  • אל תשתמשו באותו שם לטבלה ולעמודות שלה.

  • אל תשתמשו ב-_field_ כתוספת לשם של עמודה. קידומות שמורות למערכת גורמות לשינוי שם אוטומטי במהלך שאילתות. לדוגמה, השאילתה SELECT _field_ FROM project1.dataset.test מחזירה עמודה בשם _field_1. אם אתם חייבים לשלוח שאילתה לעמודה עם השם הזה, אתם יכולים להשתמש בכינוי כדי לשלוט בפלט.

  • מקצים לטבלה כינוי אחר. לדוגמה, השאילתה הבאה מקצה כינוי לטבלה t לטבלה project1.dataset.test:

    SELECT test FROM project1.dataset.test AS t;

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

    SELECT test.test FROM project1.dataset.test;

שמות גמישים של עמודות

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

שמות עמודות גמישים יכולים להכיל את התווים הבאים:

  • כל אות בכל שפה, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{L}.
  • כל תו מספרי בכל שפה, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{N}.
  • כל תו פיסוק של מחבר, כולל קו תחתון, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{Pc}.
  • מקף או קו מפריד, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{Pd}.
  • כל סימן שמיועד ללוות תו אחר, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode:‏ \p{M}. לדוגמה, סימני הטעמה, אומלאוט או תיבות סוגרות.
  • התווים המיוחדים הבאים:
    • אמפרסנד (&) כמו שהוא מיוצג בביטוי הרגולרי של Unicode‏ \u0026.
    • סימן האחוז (%) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0025.
    • סימן שוויון (=) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003D.
    • סימן פלוס (+) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002B.
    • נקודתיים (:) כמו שמיוצגות על ידי הביטוי הרגולרי של Unicode‏ \u003A.
    • גרש (') כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0027.
    • סימן קטן מ- (<) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003C.
    • הסימן גדול מ- (>) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003E.
    • סימן סולמית (#) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0023.
    • קו אנכי (|) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007c.
    • רווח לבן.

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

  • סימן קריאה (!) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0021.
  • מירכאות (") כמו שמיוצגות על ידי הביטוי הרגולרי של Unicode‏ \u0022.
  • סימן דולר ($) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0024.
  • סוגר שמאלי (() כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0028.
  • סוגר ימני ()) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0029.
  • כוכבית (*) כפי שהיא מיוצגת על ידי הביטוי הרגולרי של Unicode‏ \u002A.
  • פסיק (,) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002C.
  • נקודה (.) כפי שמיוצגת על ידי הביטוי הרגולרי של Unicode‏ \u002E. כשמשתמשים במיפוי תווים של שמות עמודות, הנקודות לא מוחלפות בקו תחתון בשמות העמודות בקובץ Parquet. מידע נוסף זמין במאמר בנושא מגבלות על עמודות גמישות.
  • לוכסן (/) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002F.
  • נקודה ופסיק (;) כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003B.
  • סימן שאלה (?) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003F.
  • הסימן @, שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0040.@
  • סוגר מרובע שמאלי ([) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005B.
  • קו נטוי הפוך (\) כמו שהוא מיוצג בביטוי הרגולרי של Unicode‏ \u005C.
  • סוגר מרובע ימני (]) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005D.
  • סימן גג (^) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005E.
  • סימן הטעם (`) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0060.
  • סוגר מסולסל שמאלי {{) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007B.
  • סוגר מסולסל ימני (}) כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007D.
  • סימן טילדה (~) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007E.

הנחיות נוספות זמינות במאמר שמות עמודות.

התווים המורחבים של העמודות נתמכים גם על ידי BigQuery Storage Read API וגם על ידי BigQuery Storage Write API. כדי להשתמש ברשימה המורחבת של תווי Unicode עם BigQuery Storage Read API, צריך להגדיר דגל. אפשר להשתמש במאפיין displayName כדי לאחזר את שם העמודה. בדוגמה הבאה אפשר לראות איך מגדירים דגל באמצעות לקוח Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

כדי להשתמש ברשימה המורחבת של תווי Unicode עם BigQuery Storage Write API, צריך לספק את הסכימה עם סימון column_name, אלא אם משתמשים באובייקט הכתיבה JsonStreamWriter. בדוגמה הבאה אפשר לראות איך מספקים את הסכימה:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

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

מגבלות

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

  • אי אפשר לטעון קובצי Parquet שמכילים עמודות עם נקודה (.) בשם העמודה.

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

ניפוי באגים בקובץ Parquet

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

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

מידע נוסף זמין במסמכי התיעוד של PyArrow.