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

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

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

פורמט ndJSON זהה לפורמט JSON Lines.

מגבלות

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

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

כשאתם טוענים קובצי JSON ל-BigQuery, חשוב לשים לב לנקודות הבאות:

• נתוני ה-JSON צריכים להיות מופרדים בתו שורה חדשה, או בפורמט ndJSON. כל אובייקט JSON צריך להיות בשורה נפרדת בקובץ.
• אם אתם משתמשים בדחיסה בפורמט gzip,‏ BigQuery לא יכול לקרוא את הנתונים במקביל. טעינת נתוני JSON דחוסים לתוך BigQuery איטית יותר מטעינת נתונים לא דחוסים.
• אי אפשר לכלול באותה משימת טעינה גם קבצים דחוסים וגם קבצים לא דחוסים.
• הגודל המקסימלי של קובץ gzip הוא 4GB.

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

• אם משתמשים ב-BigQuery API כדי לטעון מספר שלם מחוץ לטווח [‎-2⁵³+1, 2⁵³-1] (בדרך כלל זה אומר מספר גדול מ-9,071,992,547,409,911) אל עמודה של מספר שלם (INT64), צריך להעביר אותו כמחרוזת כדי למנוע פגיעה בנתונים. הבעיה הזו נובעת ממגבלה על גודל מספר שלם ב-JSON או ב-ECMAScript. מידע נוסף זמין בסעיף Numbers ב-RFC 7159.

• כשמעלים נתונים בפורמט CSV או JSON, הערכים בעמודות DATE צריכים להיות מופרדים במקף (-), והתאריך צריך להיות בפורמט הבא: YYYY-MM-DD (שנה-חודש-יום).
• כשמעלים נתוני JSON או CSV, הערכים בעמודות TIMESTAMP צריכים להשתמש במקף (-) או בלוכסן (/) כמפריד בחלק של התאריך בחותמת הזמן, והתאריך צריך להיות באחד מהפורמטים הבאים: YYYY-MM-DD (שנה-חודש-יום) או YYYY/MM/DD (שנה/חודש/יום). החלק של חותמת הזמן שכולל שעות, דקות ושניות (hh:mm:ss) צריך להיות מופרד באמצעות נקודתיים (:).

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

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

להקצות תפקידים של ניהול זהויות והרשאות גישה (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 לאחסון הנתונים.

דחיסת JSON

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

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

כדי לטעון נתוני JSON מ-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 צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה.
   2. בקטע פורמט קובץ, בוחרים באפשרות JSONL (פורמט JSON שמופרד בתו שורה חדשה).
2. בקטע יעד, מציינים את הפרטים הבאים:
   1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
   2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
   3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
3. בקטע Schema (סכימה), מזינים את הגדרת הסכימה. כדי להפעיל את הזיהוי האוטומטי של סכימה, בוחרים באפשרות זיהוי אוטומטי. אפשר להזין את פרטי הסכימה באופן ידני באחת מהשיטות הבאות:
   • אפשרות 1: לוחצים על עריכה כטקסט ומדביקים את הסכימה בצורה של מערך JSON. כשמשתמשים במערך JSON, יוצרים את הסכימה באותו תהליך שבו יוצרים קובץ סכימת JSON. כדי לראות את הסכימה של טבלה קיימת בפורמט JSON, מזינים את הפקודה הבאה:

         bq show --format=prettyjson dataset.table
         

   • אפשרות 2: לוחצים על הוספת שדה ומזינים את סכימת הטבלה. מציינים את השם, הסוג, והמצב של כל שדה.
4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות.
5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
   • בקטע העדפות כתיבה, משאירים את האפשרות כתיבה אם ריק מסומנת. האפשרות הזו יוצרת טבלה חדשה וטוענת לתוכה את הנתונים.
   • בקטע מספר השגיאות המותר, מאשרים את ערך ברירת המחדל 0 או מזינים את המספר המקסימלי של שורות שמכילות שגיאות שאפשר להתעלם מהן. אם מספר השורות עם השגיאות גדול מהערך הזה, העבודה תסתיים בהודעה invalid ותיכשל. האפשרות הזו רלוונטית רק לקובצי CSV ו-JSON.
   • בשדה אזור זמן, מזינים את אזור הזמן שיוגדר כברירת מחדל ויחול על ניתוח של ערכי חותמות זמן שלא צוין לגביהם אזור זמן ספציפי. כאן אפשר למצוא שמות נוספים של אזורי זמן תקינים. אם הערך הזה לא מופיע, המערכת מנתחת את ערכי חותמת הזמן ללא אזור זמן ספציפי באמצעות אזור הזמן שמוגדר כברירת מחדל, UTC.
   • בקטע Date Format (פורמט תאריך), מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי התאריך בקובצי הקלט. השדה הזה צריך להיות בפורמט בסגנון SQL (לדוגמה, MM/DD/YYYY). אם הערך הזה מופיע, זהו פורמט התאריך היחיד שתואם. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATE על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה DATE מנותח באמצעות פורמטי ברירת המחדל.
   • בשדה פורמט תאריך ושעה, מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי התאריך והשעה בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה מופיע, זהו פורמט התאריך והשעה היחיד שמתאים. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATETIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה DATETIME מנותח באמצעות פורמטים שמוגדרים כברירת מחדל.
   • בשדה Time Format (פורמט שעה), מזינים את רכיבי הפורמט שמגדירים איך ערכי השעה מעוצבים בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, HH24:MI:SS.FF3). אם הערך הזה קיים, זהו פורמט הזמן היחיד שתואם. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIME מנותח באמצעות פורמטי ברירת המחדל.
   • בשדה Timestamp Format (פורמט חותמת הזמן), מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי חותמת הזמן בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה קיים, הפורמט הזה הוא פורמט חותמת הזמן התואם היחיד. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIMESTAMP על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIMESTAMP מנותח באמצעות פורמטי ברירת המחדל.
   • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
   • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
6. לוחצים על יצירת טבלה.

הערה: כשמעלים נתונים לטבלה ריקה באמצעות מסוףGoogle Cloud , אי אפשר להוסיף תווית, תיאור, תאריך תפוגה לטבלה או תאריך תפוגה למחיצה.

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

SQL

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

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

   כניסה ל-BigQuery

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

   LOAD DATA OVERWRITE mydataset.mytable
   (x INT64,y STRING)
   FROM FILES (
     format = 'JSON',
     uris = ['gs://bucket/path/file.json']);

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

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

BQ

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

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

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

• ‫--max_bad_records: מספר שלם שמציין את המספר המקסימלי של רשומות פגומות שמותרות לפני שהעבודה כולה נכשלת. ערך ברירת המחדל הוא 0. מוחזרות לכל היותר חמש שגיאות מכל סוג, ללא קשר לערך של --max_bad_records.
• ‫--ignore_unknown_values: אם מציינים את האפשרות הזו, המערכת מתעלמת מערכים נוספים ולא מוכרים בנתוני CSV או JSON.
• ‫--time_zone: (תצוגה מקדימה) אזור זמן ברירת מחדל אופציונלי שיחול על ניתוח של ערכי חותמות זמן שלא צוין עבורם אזור זמן ספציפי בנתוני CSV או JSON.
• ‫--date_format: (תצוגה מקדימה) מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך בנתוני CSV או JSON.
• ‫--datetime_format: (תצוגה מקדימה) מחרוזת מותאמת אישית אופציונלית שמגדירה את הפורמט של ערכי DATETIME בנתוני CSV או JSON.
• ‫--time_format: (תצוגה מקדימה) מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי TIME בנתוני CSV או JSON.
• ‫--timestamp_format: (תצוגה מקדימה) מחרוזת מותאמת אישית אופציונלית שמגדירה את הפורמט של ערכי חותמת הזמן בנתוני CSV או JSON.
• ‫--autodetect: אם מציינים את האפשרות הזו, המערכת מפעילה זיהוי אוטומטי של סכימה לנתוני CSV ו-JSON.
• ‫--time_partitioning_type: הפעלת חלוקה למחיצות (partitioning) לפי זמן בטבלה והגדרת סוג המחיצה. הערכים האפשריים הם 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 להצפנה של נתוני הטבלה.

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

  • יצירת טבלאות עם חלוקה למחיצות

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

  • יצירה של טבלאות מקובצות ושימוש בהן

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

  • הגנה על נתונים באמצעות מפתחות Cloud KMS

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

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

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

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

דוגמאות:

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.json לטבלה בשם mytable ב-mydataset. הסכימה מוגדרת בקובץ סכימה מקומי בשם myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

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

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.json לטבלה מחולקת למחיצות בשם mytable ב-mydataset. הטבלה מחולקת למחיצות (Partitions) לפי העמודה mytimestamp. הסכימה מוגדרת בקובץ סכימה מקומי בשם myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

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

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.json לטבלה בשם mytable ב-mydataset. הסכימה מוגדרת בשורה בפורמט FIELD:DATA_TYPE, FIELD:DATA_TYPE.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    qtr:STRING,sales:FLOAT,year:STRING

הערה: כשמציינים את הסכימה באמצעות הכלי bq, אי אפשר לכלול סוג RECORD (STRUCT), אי אפשר לכלול תיאור של שדה ואי אפשר לציין את מצב השדה. כל מצבי השדות מוגדרים כברירת מחדל לNULLABLE. כדי לכלול תיאורים של שדות, מצבים וסוגים של RECORD, צריך לספק קובץ סכימת JSON במקום זאת.

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

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata*.json

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

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    "gs://mybucket/00/*.json","gs://mybucket/01/*.json" \
    ./myschema

API

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

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

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

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

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

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

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

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

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

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

C#‎

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

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

כדי להתחיל עבודת טעינה מ-Cloud Storage, משתמשים בשיטה BigQueryClient.CreateLoadJob(). כדי להשתמש ב-JSONL, יוצרים אובייקט CreateLoadJobOptions ומגדירים את המאפיין SourceFormat שלו ל-FileFormat.NewlineDelimitedJson.

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(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.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

משתמשים בשיטה LoadJobConfiguration.builder(tableId, sourceUri) כדי להתחיל עבודת טעינה מ-Cloud Storage. כדי להשתמש בפורמט JSON שמופרד בתו שורה חדשה, צריך להשתמש ב-LoadJobConfiguration.setFormatOptions(FormatOptions.json()).

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadJsonFromGCS() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON 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("Json 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 json file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

  /**
   * 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: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    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.json';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->sourceFormat('NEWLINE_DELIMITED_JSON');
$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(). כדי להשתמש ב-JSONL, צריך להגדיר את המאפיין LoadJobConfig.source_format למחרוזת NEWLINE_DELIMITED_JSON ולהעביר את הגדרות המשימה כארגומנט 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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    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))

Ruby

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

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

כדי להתחיל משימת טעינה מ-Cloud Storage, משתמשים בשיטה Dataset.load_job(). כדי להשתמש ב-JSONL, מגדירים את הפרמטר format לערך "json".

require "google/cloud/bigquery"

def load_table_gcs_json dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "json" do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

טעינת נתוני JSON מוטמעים וחוזרים

‫BigQuery תומך בטעינת נתונים מקוננים וחוזרים מפורמטים של מקורות שתומכים בסכימות מבוססות-אובייקטים, כמו JSON,‏ Avro,‏ ORC,‏ Parquet,‏ Firestore ו-Datastore.

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

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

• id
• first_name
• last_name
• dob (תאריך לידה)
• ‫addresses (שדה בתוך שדה ושדה חוזר)
  • addresses.status (נוכחי או קודם)
  • addresses.address
  • addresses.city
  • addresses.state
  • addresses.zip
  • ‫addresses.numberOfYears (מספר השנים בכתובת)

קובץ נתוני ה-JSON ייראה כך. שימו לב שהשדה address מכיל מערך של ערכים (מסומן על ידי [ ]).

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]}
{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}

הסכימה של הטבלה הזו תיראה כך:

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "addresses",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
            {
                "name": "status",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "address",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "city",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "state",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "zip",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "numberOfYears",
                "type": "STRING",
                "mode": "NULLABLE"
            }
        ]
    }
]

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

טעינה של נתוני JSON חצי מובְנים

‫BigQuery תומך בטעינת נתונים חצי מובנים, שבהם שדה יכול לקבל ערכים מסוגים שונים. בדוגמה הבאה מוצגים נתונים דומים לדוגמה הקודמת של נתוני JSON מוטמעים וחוזרים, אבל השדה address יכול להיות STRING, STRUCT או ARRAY:

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","address":"123 First Avenue, Seattle WA 11111"}

{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","address":{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}}

{"id":"3","first_name":"Bob","last_name":"Doe","dob":"1982-01-10","address":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}, "321 Main Street Hoboken NJ 44444"]}

אפשר לטעון את הנתונים האלה ל-BigQuery באמצעות הסכימה הבאה:

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "address",
        "type": "JSON",
        "mode": "NULLABLE"
    }
]

השדה address נטען בעמודה מסוג JSON, שמאפשרת לו להכיל את הסוגים המעורבים בדוגמה. אפשר להטמיע נתונים כ-JSON בין אם הם מכילים סוגים מעורבים ובין אם לא. לדוגמה, אפשר לציין JSON במקום STRING כסוג של השדה first_name. מידע נוסף מופיע במאמר עבודה עם נתוני JSON ב-GoogleSQL.

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

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

במסוף 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
• ספריות הלקוח

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

המסוף

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 צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה.
   2. בקטע פורמט קובץ, בוחרים באפשרות JSONL (פורמט JSON שמופרד בתו שורה חדשה).
הערה: אפשר לשנות את הסכימה של הטבלה כשמוסיפים לה נתונים או מחליפים את הנתונים הקיימים. מידע נוסף על שינויים נתמכים בסכימה במהלך פעולת טעינה זמין במאמר שינוי סכימות של טבלאות.
2. בקטע יעד, מציינים את הפרטים הבאים:
   1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
   2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
   3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
3. בקטע Schema (סכימה), מזינים את הגדרת הסכימה. כדי להפעיל את הזיהוי האוטומטי של סכימה, בוחרים באפשרות זיהוי אוטומטי. אפשר להזין את פרטי הסכימה באופן ידני באחת מהשיטות הבאות:
   • אפשרות 1: לוחצים על עריכה כטקסט ומדביקים את הסכימה בצורה של מערך JSON. כשמשתמשים במערך JSON, יוצרים את הסכימה באותו תהליך שבו יוצרים קובץ סכימת JSON. כדי לראות את הסכימה של טבלה קיימת בפורמט JSON, מזינים את הפקודה הבאה:

         bq show --format=prettyjson dataset.table
         

   • אפשרות 2: לוחצים על הוספת שדה ומזינים את סכימת הטבלה. מציינים את השם, הסוג, והמצב של כל שדה.
   הערה: אפשר לשנות את הסכימה של הטבלה כשמוסיפים לה נתונים או מחליפים אותם. מידע נוסף על שינויים נתמכים בסכימה במהלך פעולת טעינה זמין במאמר בנושא שינוי סכימות של טבלאות.
4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות. אי אפשר להמיר טבלה לטבלה מחולקת או לטבלה מסודרת באשכולות על ידי הוספה או החלפה שלה. Google Cloud מסוף Google Cloud לא תומך בהוספה לטבלאות מחולקות או מקובצות או בהחלפה שלהן בעבודת טעינה.
5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
   • בקטע Write preference (העדפת כתיבה), בוחרים באפשרות Append to table (הוספה לטבלה) או Overwrite table (החלפת הטבלה).
   • בקטע מספר השגיאות המותר, מאשרים את ערך ברירת המחדל 0 או מזינים את המספר המקסימלי של שורות שמכילות שגיאות שאפשר להתעלם מהן. אם מספר השורות עם השגיאות גדול מהערך הזה, העבודה תסתיים בהודעה invalid ותיכשל. האפשרות הזו רלוונטית רק לקובצי CSV ו-JSON.
   • בשדה אזור זמן, מזינים את אזור הזמן שיוגדר כברירת מחדל ויחול על ניתוח של ערכי חותמות זמן שלא צוין לגביהם אזור זמן ספציפי. כאן אפשר למצוא שמות נוספים של אזורי זמן תקינים. אם הערך הזה לא מופיע, המערכת מנתחת את ערכי חותמת הזמן ללא אזור זמן ספציפי באמצעות אזור הזמן שמוגדר כברירת מחדל, UTC.
   • בקטע Date Format (פורמט תאריך), מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי התאריך בקובצי הקלט. השדה הזה צריך להיות בפורמט בסגנון SQL (לדוגמה, MM/DD/YYYY). אם הערך הזה מופיע, זהו פורמט התאריך היחיד שתואם. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATE על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה DATE מנותח באמצעות פורמטי ברירת המחדל.
   • בשדה פורמט תאריך ושעה, מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי התאריך והשעה בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה מופיע, זהו פורמט התאריך והשעה היחיד שמתאים. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATETIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה DATETIME מנותח באמצעות פורמטים שמוגדרים כברירת מחדל.
   • בשדה Time Format (פורמט שעה), מזינים את רכיבי הפורמט שמגדירים איך ערכי השעה מעוצבים בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, HH24:MI:SS.FF3). אם הערך הזה קיים, זהו פורמט הזמן היחיד שתואם. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIME מנותח באמצעות פורמטי ברירת המחדל.
   • בשדה Timestamp Format (פורמט חותמת הזמן), מזינים את רכיבי הפורמט שמגדירים את הפורמט של ערכי חותמת הזמן בקובצי הקלט. הפורמט שצריך להזין בשדה הזה הוא פורמט בסגנון SQL (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה קיים, הפורמט הזה הוא פורמט חותמת הזמן התואם היחיד. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIMESTAMP על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIMESTAMP מנותח באמצעות פורמטי ברירת המחדל.
   • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
   • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
6. לוחצים על יצירת טבלה.

SQL

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

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

   כניסה ל-BigQuery

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

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

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

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

BQ

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

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

מציינים את הדגל --replace כדי להחליף את הטבלה. משתמשים בדגל --noreplace כדי לצרף נתונים לטבלה. אם לא מציינים דגל, ברירת המחדל היא הוספת נתונים.

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

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

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

• ‫--max_bad_records: מספר שלם שמציין את המספר המקסימלי של רשומות פגומות שמותרות לפני שהעבודה כולה נכשלת. ערך ברירת המחדל הוא 0. מוחזרות לכל היותר חמש שגיאות מכל סוג, ללא קשר לערך של --max_bad_records.
• ‫--ignore_unknown_values: אם מציינים את האפשרות הזו, המערכת מתעלמת מערכים נוספים ולא מוכרים בנתוני CSV או JSON.
• ‫--time_zone: (תצוגה מקדימה) אזור זמן ברירת מחדל אופציונלי שיחול על ניתוח של ערכי חותמות זמן שלא צוין עבורם אזור זמן ספציפי בנתוני CSV או JSON.
• ‫--date_format: (תצוגה מקדימה) מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך בנתוני CSV או JSON.
• ‫--datetime_format: (תצוגה מקדימה) מחרוזת מותאמת אישית אופציונלית שמגדירה את הפורמט של ערכי DATETIME בנתוני CSV או JSON.
• ‫--time_format: (תצוגה מקדימה) מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי TIME בנתוני CSV או JSON.
• ‫--timestamp_format: (תצוגה מקדימה) מחרוזת מותאמת אישית אופציונלית שמגדירה את הפורמט של ערכי חותמת הזמן בנתוני CSV או JSON.
• ‫--autodetect: אם מציינים את האפשרות הזו, המערכת מפעילה זיהוי אוטומטי של סכימה לנתוני CSV ו-JSON.
• ‫--destination_kms_key: מפתח Cloud KMS להצפנה של נתוני הטבלה.

bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

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

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

דוגמאות:

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

    bq load \
    --autodetect \
    --replace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

הפקודה הבאה טוענת נתונים מ-gs://mybucket/mydata.json ומצרפת נתונים לטבלה בשם mytable ב-mydataset. הסכימה מוגדרת באמצעות קובץ סכימת JSON – myschema.

    bq load \
    --noreplace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

API

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

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

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

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

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

// importJSONTruncate demonstrates loading data from newline-delimeted JSON data in Cloud Storage
// and overwriting/truncating data in the existing table.
func importJSONTruncate(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.json")
	gcsRef.SourceFormat = bigquery.JSON
	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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

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

  public static void runLoadJsonFromGCSTruncate() {
    // 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.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCSTruncate(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCSTruncate(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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.json())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON 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 JSON 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 JSON file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCSTruncate() {
  /**
   * 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: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    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), 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.json';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('NEWLINE_DELIMITED_JSON')->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

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

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי 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.NEWLINE_DELIMITED_JSON,
)

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

Ruby

כדי להחליף את השורות בטבלה קיימת, מגדירים את הפרמטר write של Table.load_job() לערך "WRITE_TRUNCATE".

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

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

require "google/cloud/bigquery"

def load_table_gcs_json_truncate dataset_id = "your_dataset_id",
                                 table_id   = "your_table_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "json",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

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

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

פרטים על טעינת נתוני JSON

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

סוגי נתונים

בוליאני. ‫BigQuery יכול לנתח כל אחת מהזוגות הבאים של נתונים בוליאניים: 1 או 0, true או false, ‏ t או f, ‏ yes או no, ‏ y או n (כל האפשרויות לא תלויות באותיות רישיות). זיהוי אוטומטי של סכימה מזהה באופן אוטומטי את כל הערכים האלה חוץ מ-0 ו-1.

בייטים. עמודות עם סוגי BYTES חייבות להיות בקידוד Base64.

תאריך. הפורמט של עמודות עם סוג DATE חייב להיות YYYY-MM-DD.

תאריך ושעה. הפורמט של עמודות עם סוגי DATETIME צריך להיות YYYY-MM-DD HH:MM:SS[.SSSSSS].

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

• טקסט מוכר (WKT)
• Well-known binary (WKB)‎
• GeoJSON

אם משתמשים ב-WKB, הערך צריך להיות מקודד הקסדצימלית.

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

• WKT: POINT(1 2)
• ‫GeoJSON: { "type": "Point", "coordinates": [1, 2] }
• WKB מקודד הקסדצימלית: 0101000000feffffffffffef3f0000000000000040

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

אינטרוול. העמודות עם סוגי INTERVAL צריכות להיות בפורמט ISO 8601 ‏PYMDTHMS, כאשר:

• ‫P = מציין שהערך מייצג משך זמן. חובה לכלול את ההצהרה הזו תמיד.
• Y = שנה
• M = חודש
• ‫D = יום
• ‫T = מציין את החלק של משך הזמן שמתייחס לשעה. חובה לכלול את ההצהרה הזו תמיד.
• H = שעה
• ‫M = Minute
• S = Second (שנייה). אפשר לציין את השניות כערך שלם או כערך חלקי עם עד שש ספרות, ברמת דיוק של מיקרו-שנייה.

כדי לציין ערך שלילי, מוסיפים מקף (-) לפני המספר.

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

• P-10000Y0M-3660000DT-87840000H0M0S
• P0Y0M0DT0H0M0.000001S
• P10000Y0M3660000DT87840000H0M0S

כדי לטעון נתונים מסוג INTERVAL, צריך להשתמש בפקודה bq load ובדגל --schema כדי לציין סכימה. אי אפשר להעלות נתוני INTERVAL באמצעות המסוף.

שעה. העמודות עם סוגי הנתונים TIME צריכות להיות בפורמט HH:MM:SS[.SSSSSS].

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

• אפשר לעצב את החלק של התאריך בפורמט YYYY-MM-DD או YYYY/MM/DD.

• הפורמט של חותמת הזמן צריך להיות HH:MM[:SS[.SSSSSS]] (השניות והשברירים של השניות הם אופציונליים).

• התאריך והשעה צריכים להיות מופרדים ברווח או באות T.

• אפשר להוסיף אחרי התאריך והשעה את הסטייה משעון UTC או את המזהה של אזור הזמן UTC ‏ (Z). מידע נוסף זמין במאמר בנושא אזורי זמן.

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

• 2018-08-19 12:11
• 2018-08-19 12:11:35
• 2018-08-19 12:11:35.22
• 2018/08/19 12:11
• 2018-07-05 12:54:00 UTC
• 2018-08-19 07:11:35.220 -05:00
• 2018-08-19T12:11:35.220Z

אם מספקים סכימה, מערכת BigQuery מקבלת גם את הזמן של תקופת Unix בשביל ערכי חותמת זמן. עם זאת, המערכת לא מזהה את המקרה הזה בזיהוי אוטומטי של סכימה, ומטפלת בערך כסוג מספרי או מחרוזת.

דוגמאות לערכים של חותמת זמן של מערכת Unix:

• 1534680695
• 1.534680695e12

מערך (שדה חוזר). הערך חייב להיות מערך JSON או null. ‫JSON null מומר ל-SQL NULL. המערך עצמו לא יכול להכיל ערכים.null

זיהוי אוטומטי של סכימות

בקטע הזה מוסבר איך זיהוי סכימה אוטומטי פועל כשמעלים קובצי JSON.

שדות בתוך שדות ושדות חוזרים ב-JSON

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

המרה של מחרוזת

אם מפעילים זיהוי אוטומטי של סכימה, מערכת BigQuery ממירה מחרוזות לערכים בוליאניים, מספריים או מסוג תאריך/שעה, אם אפשר. לדוגמה, באמצעות נתוני ה-JSON הבאים, זיהוי הסכימה האוטומטי ממיר את השדה id לעמודה INTEGER:

{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}

סוגי קידוד

נתוני JSON ב-BigQuery צריכים להיות בקידוד UTF-8. אם יש לכם קובצי JSON עם סוגי קידוד נתמכים אחרים, אתם צריכים לציין במפורש את הקידוד באמצעות הדגל --encoding כדי ש-BigQuery ימיר את הנתונים ל-UTF-8.

‫BigQuery תומך בסוגי הקידוד הבאים לקובצי JSON:

• UTF-8
• ISO-8859-1
• ‫UTF-16BE (UTF-16 Big Endian)
• UTF-16LE (UTF-16 Little Endian)
• UTF-32BE (UTF-32 Big Endian)
• ‫UTF-32LE (UTF-32 Little Endian)

אפשרויות JSON

כדי לשנות את האופן שבו BigQuery מנתח נתוני JSON, צריך לציין אפשרויות נוספות במסוף Google Cloud , בכלי שורת הפקודה של BigQuery, ב-API או בספריות הלקוח.

אפשרות JSON	אפשרות מסוף	דגל של כלי bq	מאפיין BigQuery API	תיאור
מספר הרשומות הלא תקינות שמותרות	מספר השגיאות המותר	--max_bad_records	maxBadRecords (Java, Python)	(אופציונלי) המספר המקסימלי של רשומות פגומות ש-BigQuery יכול להתעלם מהן בזמן הרצת המשימה. אם מספר הרשומות הפגומות גדול מהערך הזה, תוצאת העבודה תהיה שגיאה לא תקינה. ערך ברירת המחדל הוא 0, שמשמעותו שכל הרשומות צריכות להיות תקינות.
ערכים לא ידועים	התעלמות מערכים לא ידועים	--ignore_unknown_values	ignoreUnknownValues (Java, Python)	(אופציונלי) מציין אם BigQuery צריך לאפשר ערכים נוספים שלא מיוצגים בסכמת הטבלה. אם הערך הוא true, המערכת מתעלמת מהערכים המיותרים. אם הערך הוא false, רשומות עם עמודות נוספות נחשבות לרשומות פגומות, ואם יש יותר מדי רשומות פגומות, מוחזרת שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false. המאפיין `sourceFormat` קובע מה נחשב ב-BigQuery כערך נוסף: CSV: עמודות נגררות, JSON: ערכים עם שמות שלא תואמים לשמות של עמודות.
קידוד	ללא	-E או --encoding	encoding (Python)	(אופציונלי) קידוד התווים של הנתונים. הערכים הנתמכים הם: UTF-8,‏ ISO-8859-1,‏ UTF-16BE,‏ UTF-16LE,‏ UTF-32BE או UTF-32LE. ערך ברירת המחדל הוא UTF-8.
אזור זמן	אזור זמן	--time_zone	timeZone (Java, Python)	(אופציונלי) אזור הזמן שמוגדר כברירת מחדל, שמוחל כשמנתחים ערכי חותמות זמן שלא צוין להם אזור זמן ספציפי. בודקים את השמות התקינים של אזורי הזמן. אם הערך הזה לא מופיע, המערכת מנתחת את ערכי חותמת הזמן ללא אזור זמן ספציפי באמצעות אזור הזמן שמוגדר כברירת מחדל, UTC.
פורמט התאריך	פורמט התאריך	--date_format	dateFormat (Java, Python)	(אופציונלי) רכיבי פורמט שמגדירים את הפורמט של ערכי התאריך בקובצי הקלט (לדוגמה, MM/DD/YYYY). אם הערך הזה מופיע, הפורמט הזה הוא פורמט התאריך התואם היחיד. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATE על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, המערכת מנתחת את שדה התאריך באמצעות פורמטים שמוגדרים כברירת מחדל.
פורמט של תאריך ושעה	פורמט של תאריך ושעה	--datetime_format	datetimeFormat (Java, Python)	(אופציונלי) רכיבי פורמט שמגדירים את הפורמט של ערכי התאריך והשעה בקובצי הקלט (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה מופיע, הפורמט הזה הוא הפורמט היחיד של תאריך ושעה שנתמך. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATETIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה DATETIME מנותח באמצעות פורמטי ברירת המחדל.
פורמט השעה	פורמט השעה	--time_format	timeFormat (Java, Python)	(אופציונלי) רכיבי פורמט שמגדירים את הפורמט של ערכי השעה בקובצי הקלט (לדוגמה, HH24:MI:SS.FF3). אם הערך הזה קיים, הפורמט הזה הוא הפורמט התואם היחיד של השעה. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIME על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIME מנותח באמצעות פורמטי ברירת המחדל.
הפורמט של חותמת הזמן	הפורמט של חותמת הזמן	--timestamp_format	timestampFormat (Java, Python)	(אופציונלי) Format elements שמגדירים את הפורמט של ערכי חותמת הזמן בקובצי הקלט (לדוגמה, MM/DD/YYYY HH24:MI:SS.FF3). אם הערך הזה קיים, הפורמט הזה הוא הפורמט היחיד של חותמת הזמן שנתמך. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה TIMESTAMP על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, השדה TIMESTAMP מנותח באמצעות פורמטים שמוגדרים כברירת מחדל.

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

• למידע על טעינת נתוני JSON מקובץ מקומי, ראו טעינת נתונים מקבצים מקומיים.
• למידע נוסף על יצירה, הטמעה ושליחת שאילתות של נתוני JSON, ראו עבודה עם נתוני JSON ב-GoogleSQL.