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

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

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

מידע על טעינת נתוני CSV מקובץ מקומי זמין במאמר בנושא טעינת נתונים ל-BigQuery ממקור נתונים מקומי.

נסו בעצמכם

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

מתנסים ב-BigQuery בחינם

מגבלות

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

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

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

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

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

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

דחיסת קובץ CSV

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

טעינת נתוני CSV לטבלה

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

המסוף

בלחיצה על תראו לי איך תקבלו הסבר מפורט על המשימה ישירות ב-Cloud Shell Editor:

תראו לי איך

  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. בקטע פורמט קובץ, בוחרים באפשרות CSV.
    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 מנותח באמצעות פורמטי ברירת המחדל.
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע Field delimiter (תו להפרדת שדות), בוחרים את התו שמפריד בין התאים בקובץ ה-CSV: Comma (פסיק), Tab (טאב), Pipe (קו אנכי) או Custom (התאמה אישית). אם בוחרים באפשרות Custom (מותאם אישית), מזינים את המפריד בתיבה Custom field delimiter (מפריד שדות מותאם אישית). ערך ברירת המחדל הוא Comma.
      • בקטע התאמה של עמודת המקור, בוחרים באחת מהאסטרטגיות הבאות שמשמשות להתאמת העמודות שנטענו לסכימה.
        • ‫Default: התנהגות ברירת המחדל נבחרת על סמך אופן אספקת הסכימה. אם ההגדרה 'זיהוי אוטומטי' מופעלת, התנהגות ברירת המחדל היא התאמה של עמודות לפי שם. אחרת, ברירת המחדל היא התאמת העמודות לפי מיקום. הפעולה הזו מתבצעת כדי לשמור על תאימות לאחור.
        • ‫Position: מתאימה עמודות לפי מיקום, בהנחה שהעמודות מסודרות באותו אופן כמו הסכימה.
        • ‫Name: התאמה לפי שם על ידי קריאת שורת הכותרת כשמות העמודות וסידור מחדש של העמודות כך שיתאימו לשמות השדות בסכימה. שמות העמודות נקראים מהשורה האחרונה שדילגתם עליה, על סמך שורות הכותרת שצריך לדלג עליהן.
      • בשדה Header rows to skip (שורות כותרת לדילוג), מזינים את מספר שורות הכותרת שרוצים לדלג עליהן בחלק העליון של קובץ ה-CSV. ערך ברירת המחדל הוא 0.
      • בקטע שבירות שורה במירכאות, מסמנים את התיבה התרת שבירות שורה במירכאות כדי לאפשר קטעי נתונים במירכאות שמכילים תווי שבירת שורה בקובץ CSV. ערך ברירת המחדל הוא false.
      • אם יש שורות לא אחידות, מסמנים את התיבה אפשר שורות לא אחידות כדי לאפשר שורות בקובצי CSV שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים נחשבים כערכי null. אם לא מסמנים את התיבה, המערכת מתייחסת לרשומות שחסרות בהן עמודות בסוף כרשומות פגומות. אם יש יותר מדי רשומות פגומות, המערכת מחזירה שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false.
      • בקטע Null markers (סמני ערך NULL), מזינים רשימה של מחרוזות מותאמות אישית שמייצגות ערך NULL בנתוני CSV.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
    6. לוחצים על יצירת טבלה.

SQL

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

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

    כניסה ל-BigQuery

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

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

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

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

BQ

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

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

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

  • ‫--allow_jagged_rows: אם מציינים את האפשרות הזו, המערכת מקבלת שורות בקובצי CSV שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים נחשבים כערכי null. אם לא מסמנים את התיבה, המערכת מתייחסת לרשומות שחסרות בהן עמודות בסוף כאל רשומות פגומות. אם יש יותר מדי רשומות פגומות, המערכת מחזירה שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false.
  • ‫--allow_quoted_newlines: כשמציינים את האפשרות הזו, אפשר להשתמש בקטעי נתונים עם מרכאות שמכילים תווי שורה חדשה בקובץ CSV. ערך ברירת המחדל הוא false.
  • ‫--field_delimiter: התו שמציין את הגבול בין העמודות בנתונים. אפשר להשתמש ב-\t וב-tab כתווים להפרדה בין עמודות. ערך ברירת המחדל הוא ,.
  • ‫--null_marker: מחרוזת אופציונלית בהתאמה אישית שמייצגת ערך NULL בנתוני CSV.
  • ‫--null_markers: רשימה אופציונלית של מחרוזות מותאמות אישית שמופרדות בפסיקים ומייצגות ערכי NULL בנתוני CSV. אי אפשר להשתמש באפשרות הזו עם הדגל --null_marker.
  • ‫--source_column_match: מציין את האסטרטגיה שמשמשת להתאמת העמודות שנטענו לסכימה. אפשר לציין POSITION כדי להתאים עמודות שנטענו לפי מיקום, בהנחה שהעמודות מסודרות באותו אופן כמו הסכימה. אפשר גם לציין NAME כדי להתאים לפי שם על ידי קריאת שורת הכותרת כשמות העמודות ושינוי הסדר של העמודות כך שיתאים לשמות השדות בסכימה. אם לא מציינים ערך, ברירת המחדל מבוססת על האופן שבו הסכימה מסופקת. אם ההגדרה --autodetect מופעלת, ברירת המחדל היא התאמה בין עמודות לפי שם. אחרת, ברירת המחדל היא התאמה בין עמודות לפי מיקום.
  • ‫--skip_leading_rows: מציין את מספר שורות הכותרת שצריך לדלג עליהן בחלק העליון של קובץ ה-CSV. ערך ברירת המחדל הוא 0.
  • ‫--quote: תו המירכאות שמשמש להקפת רשומות. ערך ברירת המחדל הוא ". כדי לציין שאין תו מרכאות, משתמשים במחרוזת ריקה.
  • ‫--max_bad_records: מספר שלם שמציין את המספר המקסימלי של רשומות פגומות שמותרות לפני שהעבודה כולה נכשלת. ערך ברירת המחדל הוא 0. מוחזרות לכל היותר חמש שגיאות מכל סוג, ללא קשר לערך של --max_bad_records.
  • ‫--ignore_unknown_values: אם מציינים את האפשרות הזו, המערכת מתעלמת מערכים נוספים ולא מוכרים בנתוני CSV או JSON.
  • ‫--time_zone: אזור זמן אופציונלי שמוגדר כברירת מחדל ויחול על ניתוח של ערכי חותמת זמן שלא צוין לגביהם אזור זמן ספציפי בנתוני CSV או JSON.
  • ‫--date_format: מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך בנתוני CSV או JSON.
  • ‫--datetime_format: מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך והשעה בנתוני 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 להצפנה של נתוני הטבלה.

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

    מידע נוסף על הפקודה bq load

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

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

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

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

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

כאשר:

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

דוגמאות:

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

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

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

    bq load \
    --source_format=CSV \
    --skip_leading_rows=2
    mydataset.mytable \
    gs://mybucket/mydata.csv \
    ./myschema.json

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

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

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

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

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

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    gs://mybucket/mydata.csv

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

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

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

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

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

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

API

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

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

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

  4. מגדירים את מאפיין sourceFormat לערך CSV כדי לציין את פורמט הנתונים של קובץ ה-CSV.

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


using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsCsv
{
    public void LoadTableGcsCsv(
        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.csv";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        var destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            // The source format defaults to CSV; line below is optional.
            SourceFormat = FileFormat.Csv,
            SkipLeadingRows = 1
        };
        // Create and run job
        var 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"
)

// importCSVExplicitSchema demonstrates loading CSV data from Cloud Storage into a BigQuery
// table and providing an explicit schema for the data.
func importCSVExplicitSchema(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.csv")
	gcsRef.SkipLeadingRows = 1
	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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Field;
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 CSV data from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcs {

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

  public static void loadCsvFromGcs(
      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();

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, csvOptions).setSchema(schema).build();

      // Load data from a GCS CSV 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("CSV from GCS successfully added during load append job");
      } 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 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.csv';

async function loadCSVFromGCS() {
  // 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: 'CSV',
    skipLeadingRows: 1,
    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.csv';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->skipLeadingRows(1);
$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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

משתמשים בשיטה Client.load_table_from_uri() כדי לטעון נתונים מקובץ CSV ב-Cloud Storage. מספקים הגדרת סכימה מפורשת על ידי הגדרת המאפיין LoadJobConfig.schema לרשימה של אובייקטים מסוג SchemaField.

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"),
    ],
    skip_leading_rows=1,
    # The source format defaults to CSV, so the line below is optional.
    source_format=bigquery.SourceFormat.CSV,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv"

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)  # Make an API request.
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

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

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

require "google/cloud/bigquery"

def load_table_gcs_csv 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.csv"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, skip_leading: 1 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

טעינת נתוני CSV לטבלה שמשתמשת בחלוקה למחיצות לפי עמודות

כדי לטעון נתוני CSV מ-Cloud Storage לטבלה ב-BigQuery שמשתמשת בחלוקה למחיצות לפי זמן שמבוססת על עמודות:

Go

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

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


import (
	"context"
	"fmt"
	"time"

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

// importPartitionedTable demonstrates specifing time partitioning for a BigQuery table when loading
// CSV data from Cloud Storage.
func importPartitionedTable(projectID, destDatasetID, destTableID 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-by-date.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field:      "date",
		Expiration: 90 * 24 * time.Hour,
	}
	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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

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.JobId;
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;
import com.google.cloud.bigquery.TimePartitioning;
import java.time.Duration;
import java.time.temporal.ChronoUnit;
import java.util.UUID;

public class LoadPartitionedTable {

  public static void runLoadPartitionedTable() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    loadPartitionedTable(datasetName, tableName, sourceUri);
  }

  public static void loadPartitionedTable(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      // Configure time partitioning. For full list of options, see:
      // https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#TimePartitioning
      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date")
              .setExpirationMs(Duration.of(90, ChronoUnit.DAYS).toMillis())
              .build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // 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 = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Data successfully loaded into time partitioned table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println(
          "Data not loaded into time partitioned table during load job \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-by-date.csv';

async function loadTablePartitioned() {
  // Load data into a table that uses column-based time partitioning.

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

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const partitionConfig = {
    type: 'DAY',
    expirationMs: '7776000000', // 90 days
    field: 'date',
  };

  const metadata = {
    sourceFormat: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
        {name: 'date', type: 'DATE'},
      ],
    },
    location: 'US',
    timePartitioning: partitionConfig,
  };

  // 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.`);
}

Python

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

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

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
        bigquery.SchemaField("date", "DATE"),
    ],
    skip_leading_rows=1,
    time_partitioning=bigquery.TimePartitioning(
        type_=bigquery.TimePartitioningType.DAY,
        field="date",  # Name of the column to use for partitioning.
        expiration_ms=7776000000,  # 90 days.
    ),
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states-by-date.csv"

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

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

table = client.get_table(table_id)
print("Loaded {} rows to table {}".format(table.num_rows, table_id))

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

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

במסוף 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.

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

המסוף

  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. בקטע פורמט קובץ, בוחרים באפשרות CSV.
    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 מנותח באמצעות פורמטי ברירת המחדל.
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע Field delimiter (תו להפרדת שדות), בוחרים את התו שמפריד בין התאים בקובץ ה-CSV: Comma (פסיק), Tab (טאב), Pipe (קו אנכי) או Custom (התאמה אישית). אם בוחרים באפשרות Custom (מותאם אישית), מזינים את המפריד בתיבה Custom field delimiter (מפריד שדות מותאם אישית). ערך ברירת המחדל הוא Comma.
      • בקטע התאמה של עמודת המקור, בוחרים באחת מהאסטרטגיות הבאות שמשמשות להתאמת העמודות שנטענו לסכימה.
        • ‫Default: התנהגות ברירת המחדל נבחרת על סמך אופן אספקת הסכימה. אם ההגדרה 'זיהוי אוטומטי' מופעלת, התנהגות ברירת המחדל היא התאמה של עמודות לפי שם. אחרת, ברירת המחדל היא התאמת העמודות לפי מיקום. הפעולה הזו מתבצעת כדי לשמור על תאימות לאחור.
        • ‫Position: מתאימה עמודות לפי מיקום, בהנחה שהעמודות מסודרות באותו אופן כמו הסכימה.
        • ‫Name: התאמה לפי שם על ידי קריאת שורת הכותרת כשמות העמודות וסידור מחדש של העמודות כך שיתאימו לשמות השדות בסכימה. שמות העמודות נקראים מהשורה האחרונה שדילגתם עליה, על סמך שורות הכותרת שצריך לדלג עליהן.
      • בשדה Header rows to skip (שורות כותרת לדילוג), מזינים את מספר שורות הכותרת שרוצים לדלג עליהן בחלק העליון של קובץ ה-CSV. ערך ברירת המחדל הוא 0.
      • בקטע שבירות שורה במירכאות, מסמנים את התיבה התרת שבירות שורה במירכאות כדי לאפשר קטעי נתונים במירכאות שמכילים תווי שבירת שורה בקובץ CSV. ערך ברירת המחדל הוא false.
      • אם יש שורות לא אחידות, מסמנים את התיבה אפשר שורות לא אחידות כדי לאפשר שורות בקובצי CSV שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים נחשבים כערכי null. אם לא מסמנים את התיבה, המערכת מתייחסת לרשומות שחסרות בהן עמודות בסוף כרשומות פגומות. אם יש יותר מדי רשומות פגומות, המערכת מחזירה שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false.
      • בקטע Null markers (סמני ערך NULL), מזינים רשימה של מחרוזות מותאמות אישית שמייצגות ערך NULL בנתוני CSV.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
    6. לוחצים על יצירת טבלה.

SQL

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

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

    כניסה ל-BigQuery

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

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

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

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

BQ

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

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

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

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

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

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

  • ‫--allow_jagged_rows: אם מציינים את האפשרות הזו, המערכת מקבלת שורות בקובצי CSV שחסרות בהן עמודות אופציונליות בסוף. הערכים החסרים נחשבים כערכי null. אם לא מסמנים את התיבה, המערכת מתייחסת לרשומות שחסרות בהן עמודות בסוף כאל רשומות פגומות. אם יש יותר מדי רשומות פגומות, המערכת מחזירה שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false.
  • ‫--allow_quoted_newlines: כשמציינים את האפשרות הזו, אפשר להשתמש בקטעי נתונים עם מרכאות שמכילים תווי שורה חדשה בקובץ CSV. ערך ברירת המחדל הוא false.
  • ‫--field_delimiter: התו שמציין את הגבול בין העמודות בנתונים. אפשר להשתמש ב-\t וב-tab כתווים להפרדה בין עמודות. ערך ברירת המחדל הוא ,.
  • ‫--null_marker: מחרוזת אופציונלית בהתאמה אישית שמייצגת ערך NULL בנתוני CSV.
  • ‫--null_markers: רשימה אופציונלית של מחרוזות מותאמות אישית שמופרדות בפסיקים ומייצגות ערכי NULL בנתוני CSV. אי אפשר להשתמש באפשרות הזו עם הדגל --null_marker.
  • ‫--source_column_match: מציין את האסטרטגיה שמשמשת להתאמת העמודות שנטענו לסכימה. אפשר לציין POSITION כדי להתאים עמודות שנטענו לפי מיקום, בהנחה שהעמודות מסודרות באותו אופן כמו הסכימה. אפשר גם לציין NAME כדי להתאים לפי שם. לשם כך, צריך לקרוא את שורת הכותרת כשמות העמודות ולשנות את הסדר של העמודות כך שיתאים לשמות השדות בסכימה. אם לא מציינים ערך, ברירת המחדל תהיה תלויה באופן שבו הסכימה מסופקת. אם ההגדרה --autodetect מופעלת, ברירת המחדל היא התאמה בין עמודות לפי שם. אחרת, ברירת המחדל היא התאמת העמודות לפי המיקום.
  • ‫--skip_leading_rows: מציין את מספר שורות הכותרת שצריך לדלג עליהן בחלק העליון של קובץ ה-CSV. ערך ברירת המחדל הוא 0.
  • ‫--quote: תו המירכאות שמשמש להקפת רשומות. ערך ברירת המחדל הוא ". כדי לציין שאין תו מרכאות, משתמשים במחרוזת ריקה.
  • ‫--max_bad_records: מספר שלם שמציין את המספר המקסימלי של רשומות פגומות שמותרות לפני שהעבודה כולה נכשלת. ערך ברירת המחדל הוא 0. מוחזרות לכל היותר חמש שגיאות מכל סוג, ללא קשר לערך של --max_bad_records.
  • ‫--ignore_unknown_values: אם מציינים את האפשרות הזו, המערכת מתעלמת מערכים נוספים ולא מוכרים בנתוני CSV או JSON.
  • ‫--time_zone: אזור זמן ברירת מחדל אופציונלי שיחול כשמנתחים ערכי חותמת זמן שלא צוין להם אזור זמן ספציפי בנתוני CSV או JSON.
  • ‫--date_format: מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך בנתוני CSV או JSON.
  • ‫--datetime_format: מחרוזת אופציונלית בהתאמה אישית שמגדירה את הפורמט של ערכי התאריך והשעה בנתוני 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

where:

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

דוגמאות:

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

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

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

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

API

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

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

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

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

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

// importCSVTruncate demonstrates loading data from CSV data in Cloud Storage and overwriting/truncating
// data in the existing table.
func importCSVTruncate(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.csv")
	gcsRef.SourceFormat = bigquery.CSV
	gcsRef.AutoDetect = true
	gcsRef.SkipLeadingRows = 1
	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;

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

  public static void runLoadCsvFromGcsTruncate() throws Exception {
    // 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.csv";
    loadCsvFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsTruncate(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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 configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              // 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 loadJob = 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 = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Table is successfully overwritten by CSV file loaded from GCS");
    } 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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

כדי להחליף את השורות בטבלה קיימת, מגדירים את הערך writeDisposition בפרמטר metadata ל-'WRITE_TRUNCATE'.

// 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.csv';

async function loadCSVFromGCSTruncate() {
  /**
   * 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: 'CSV',
    skipLeadingRows: 1,
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // 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הוראות ההגדרה שבמדריך למתחילים של 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.csv';
$loadConfig = $table->loadFromStorage($gcsUri)->skipLeadingRows(1)->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 לקבוע SourceFormat‏ WRITE_TRUNCATE.

import six

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 = six.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.CSV,
    skip_leading_rows=1,
)

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

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

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

פרטים על טעינת נתונים בפורמט CSV

בסעיף הזה מוסבר איך BigQuery מטפל באפשרויות שונות של עיצוב CSV.

קידוד

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

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

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

אם לא מציינים קידוד, או אם מציינים קידוד UTF-8 כשקובץ ה-CSV לא מקודד ב-UTF-8, מערכת BigQuery מנסה להמיר את הנתונים ל-UTF-8. בדרך כלל, אם קובץ ה-CSV מקודד ב-ISO-8859-1, הנתונים ייטענו בהצלחה, אבל יכול להיות שהם לא יהיו בדיוק כמו שציפיתם. אם קובץ ה-CSV מקודד ב-UTF-16BE,‏ UTF-16LE,‏ UTF-32BE או UTF-32LE, יכול להיות שהטעינה תיכשל. כדי למנוע כשלים לא צפויים, צריך לציין את הקידוד הנכון באמצעות הדגל --encoding.

אם BigQuery לא יכול להמיר תו שאינו התו 0ב-ASCII, הוא ממיר את התו לתו החלפה סטנדרטי ב-Unicode: ‏�.

תווי הפרדה בין שדות

התו המפריד בקובצי CSV יכול להיות כל תו של בייט יחיד. אם קובץ המקור משתמש בקידוד ISO-8859-1, כל תו יכול להיות תו מפריד. אם קובץ המקור משתמש בקידוד UTF-8, אפשר להשתמש בכל תו בטווח העשרוני 1-127 (U+0001-U+007F) בלי לבצע שינויים. אפשר להוסיף תו ISO-8859-1 מחוץ לטווח הזה כתו מפריד, ו-BigQuery יפרש אותו בצורה נכונה. עם זאת, אם משתמשים בתו מרובה בייטים כתו מפריד, חלק מהבייטים יפורשו בצורה שגויה כחלק מערך השדה.

בדרך כלל מומלץ להשתמש בתו מפריד סטנדרטי, כמו Tab,‏ | או פסיק. ברירת המחדל היא פסיק.

סוגי נתונים

בוליאני. ‫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 צריכות להיות בפורמט Y-M D H:M:S[.F], כאשר:

  • Y = שנה. הטווח הנתמך הוא 0 עד 10,000.
  • ‫M = חודש. הטווח הנתמך הוא 1-12.
  • ‫D = יום. הטווח הנתמך הוא 1 עד [היום האחרון של החודש שצוין].
  • H = שעה.
  • ‫M = דקה.
  • S = Second (שנייה).
  • ‫[.F] = שבריר של שנייה עד שש ספרות, עם דיוק של מיקרו-שנייה.

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

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

  • 10-6 0 0:0:0
  • 0-0 -5 0:0:0
  • 0-0 0 0:0:1.25

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

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

שעה. העמודות עם סוגי הנתונים 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

RANGE. הפורמט בקובצי CSV הוא: [LOWER_BOUND, UPPER_BOUND), כאשר LOWER_BOUND ו-UPPER_BOUND הם מחרוזות תקינות של DATE, DATETIME או TIMESTAMP. ‫NULL ו-UNBOUNDED מייצגים ערכי התחלה או סיום לא מוגבלים.

הדוגמאות הבאות מציגות ערכים אפשריים של RANGE<DATE> בקובץ CSV:

  • "[2020-01-01, 2021-01-01)"
  • "[UNBOUNDED, 2021-01-01)"
  • "[2020-03-01, NULL)"
  • "[UNBOUNDED, UNBOUNDED)"

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

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

תו מפריד ב-CSV

מערכת BigQuery מזהה את התווים הבאים להפרדה:

  • פסיק ( , )
  • קו אנכי ( | )
  • טאב ( ‎\t )

כותרת CSV

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

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

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

שורות חדשות עם מרכאות בקובץ CSV

‫BigQuery מזהה תווים של שורה חדשה בתוך שדה CSV עם מרכאות, ולא מפרש את התו של השורה החדשה כגבול של שורה.

פתרון בעיות בניתוח

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

בדרך כלל, השגיאות האלה מציינות את ההתחלה של השורה הבעייתית עם היסט של בייט. כדי לגשת לשורה הרלוונטית בקבצים לא דחוסים, אפשר להשתמש ב-gcloud storage עם הארגומנט --recursive.

לדוגמה, מריצים את הפקודה bq load ומופיעה שגיאה:

bq load
    --skip_leading_rows=1 \
    --source_format=CSV \
    mydataset.mytable \
    gs://my-bucket/mytable.csv \
    'Number:INTEGER,Name:STRING,TookOffice:STRING,LeftOffice:STRING,Party:STRING'

השגיאה בפלט אמורה להיראות כך:

Waiting on bqjob_r5268069f5f49c9bf_0000018632e903d7_1 ... (0s)
Current status: DONE
BigQuery error in load operation: Error processing job
'myproject:bqjob_r5268069f5f49c9bf_0000018632e903d7_1': Error while reading
data, error message: Error detected while parsing row starting at position: 1405.
Error: Data between close quote character (") and field separator.
File: gs://my-bucket/mytable.csv
Failure details:
- gs://my-bucket/mytable.csv: Error while reading data,
error message: Error detected while parsing row starting at
position: 1405. Error: Data between close quote character (") and
field separator. File: gs://my-bucket/mytable.csv
- Error while reading data, error message: CSV processing encountered
too many errors, giving up. Rows: 22; errors: 1; max bad: 0; error
percent: 0

על סמך השגיאה הקודמת, יש שגיאת פורמט בקובץ. כדי להציג את תוכן הקובץ, מריצים את הפקודה gcloud storage cat:

gcloud storage cat 1405-1505 gs://my-bucket/mytable.csv --recursive

הפלט אמור להיראות כך:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican
18,Ulysses S. Grant,"March 4, 1869",
...

על סמך הפלט של הקובץ, הבעיה היא גרשיים לא במקום ב-"April 15, "1865.

קבצי CSV דחוסים

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

gcloud storage cat gs://my-bucket/mytable.csv.gz | gunzip - | tail -c +1406 | head -n 1

הפלט אמור להיראות כך:

16,Abraham Lincoln,"March 4, 1861","April 15, "1865,Republican

פתרון בעיות שקשורות למכסות

המידע בקטע הזה יעזור לכם לפתור בעיות שקשורות למכסות או למגבלות בהעלאת קובצי CSV ל-BigQuery.

שגיאות שקשורות למכסת הטעינה של קובצי CSV

אם טוענים קובץ CSV גדול באמצעות הפקודה bq load עם הדגל --allow_quoted_newlines, יכול להיות שתיתקלו בשגיאה הזו.

הודעת השגיאה

Input CSV files are not splittable and at least one of the files is larger than
the maximum allowed size. Size is: ...

רזולוציה

כדי לפתור את שגיאת המכסה הזו:

  • מגדירים את הדגל --allow_quoted_newlines לערך false.
  • מפצלים את קובץ ה-CSV לחלקים קטנים יותר, שכל אחד מהם קטן מ-4GB.

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

אפשרויות CSV

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

מידע נוסף על פורמט CSV זמין ב-RFC 4180.

אפשרות CSV אפשרות מסוף דגל של כלי bq מאפיין BigQuery API תיאור
תו מפריד בין שדות מפריד שדות: פסיק, טאב, קו אנכי, מותאם אישית -F או --field_delimiter fieldDelimiter (Java, Python) (אופציונלי) התו המפריד בין השדות בקובץ CSV. התו המפריד יכול להיות כל תו יחיד בקידוד ISO-8859-1. ‫BigQuery ממיר את המחרוזת לקידוד ISO-8859-1, ומשתמש בבייט הראשון של המחרוזת המקודדת כדי לפצל את הנתונים במצב הבינארי הגולמי שלהם. ‫BigQuery תומך גם ברצף הבריחה ‎ כדי לציין מפריד של טאב. ערך ברירת המחדל הוא פסיק (`,`).
שורות כותרת שורות כותרת לדילוג --skip_leading_rows skipLeadingRows (Java, Python) (אופציונלי) מספר שלם שמציין את מספר שורות הכותרת בנתוני המקור.
התאמה של עמודת המקור התאמה של עמודת המקור: ברירת מחדל, מיקום, שם --source_column_match sourceColumnMatch (Java, Python) (אופציונלי) האפשרות הזו קובעת את האסטרטגיה שמשמשת להתאמת העמודות שנטענו לסכימה. הערכים הנתמכים כוללים:
  • ‫POSITION: התאמות לפי מיקום. באפשרות הזו מניחים שהעמודות מסודרות באותו אופן כמו הסכימה.
  • ‫NAME: התאמות לפי שם. האפשרות הזו קוראת את שורת הכותרת כשמות של עמודות ומסדרת מחדש את העמודות כך שיתאימו לשמות השדות בסכימה. שמות העמודות נקראים מהשורה האחרונה שדילגתם עליה, על סמך המאפיין skipLeadingRows.
אם הערך הזה לא מצוין, ברירת המחדל מבוססת על האופן שבו הסכימה מסופקת. אם ההגדרה 'זיהוי אוטומטי' מופעלת, התנהגות ברירת המחדל היא התאמת עמודות לפי שם. אחרת, ברירת המחדל היא התאמת העמודות לפי המיקום. השינוי הזה נעשה כדי לשמור על תאימות לאחור.
מספר הרשומות הלא תקינות שמותרות מספר השגיאות המותר --max_bad_records maxBadRecords (Java, Python) (אופציונלי) המספר המקסימלי של רשומות פגומות ש-BigQuery יכול להתעלם מהן במהלך הרצת המשימה. אם מספר הרשומות הפגומות גדול מהערך הזה, תוצאת העבודה תהיה שגיאה לא תקינה. ערך ברירת המחדל הוא 0, שמשמעותו שכל הרשומות צריכות להיות תקינות.
תווים של שורה חדשה התרת מעברי שורה במירכאות --allow_quoted_newlines allowQuotedNewlines (Java, Python) (אופציונלי) מציין אם לאפשר קטעי נתונים עם מרכאות שמכילים תווי שורה חדשה בקובץ CSV. ערך ברירת המחדל הוא false.
ערכי null מותאמים אישית ללא --null_marker nullMarker (Java, Python) (אופציונלי) מציין מחרוזת שמייצגת ערך null בקובץ CSV. לדוגמה, אם מציינים את הערך '\N', ‏ BigQuery מפרש את הערך '\N' כערך null כשמעלים קובץ CSV. ערך ברירת המחדל הוא מחרוזת ריקה. אם מגדירים את המאפיין הזה לערך מותאם אישית, BigQuery מציג שגיאה אם יש מחרוזת ריקה בכל סוגי הנתונים, למעט STRING ו-BYTE. בעמודות STRING ו-BYTE, ‏ BigQuery מפרש את המחרוזת הריקה כערך ריק.
עמודות אופציונליות בסוף התרת שורות משוננות --allow_jagged_rows allowJaggedRows (Java, Python) (אופציונלי) אפשר לאשר שורות שחסרות בהן עמודות אופציונליות בסוף. המערכת מתייחסת לערכים החסרים כאל ערכי null. אם הערך הוא false, רשומות שחסרות בהן עמודות בסוף נחשבות לרשומות פגומות, ואם יש יותר מדי רשומות פגומות, מוחזרת שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false. המאפיין הזה רלוונטי רק לקובצי CSV. המערכת מתעלמת ממנו בפורמטים אחרים.
ערכים לא ידועים התעלמות מערכים לא ידועים --ignore_unknown_values ignoreUnknownValues (Java, Python) (אופציונלי) מציין אם BigQuery צריך לאפשר ערכים נוספים שלא מיוצגים בסכימת הטבלה. אם הערך הוא true, המערכת מתעלמת מהערכים המיותרים. אם הערך הוא false, רשומות עם עמודות נוספות נחשבות לרשומות פגומות, ואם יש יותר מדי רשומות פגומות, מוחזרת שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא false. המאפיין sourceFormat קובע מה נחשב ב-BigQuery כערך נוסף:
  • ‫CSV: עמודות בסוף
  • ‫JSON: ערכים עם שמות שלא תואמים לשמות של עמודות
ציטוט תו מירכאות: מירכאות כפולות, מירכאות בודדות, ללא, מותאם אישית --quote quote (Java, Python) (אופציונלי) הערך שמשמש לציטוט של קטעי נתונים בקובץ CSV. ‫BigQuery ממיר את המחרוזת לקידוד ISO-8859-1, ואז משתמש בבייט הראשון של המחרוזת המקודדת כדי לפצל את הנתונים במצב הבינארי הגולמי שלהם. ערך ברירת המחדל הוא מירכאות כפולות ("). אם הנתונים לא מכילים קטעים שמוקפים במירכאות, צריך להגדיר את ערך המאפיין כמחרוזת ריקה. אם הנתונים שלכם מכילים תווי שורה חדשה שמוקפים במירכאות, עליכם גם להגדיר את המאפיין allowQuotedNewlines לערך true. כדי לכלול את תו המירכאות הספציפי בתוך ערך שתחום במירכאות, מוסיפים לפניו תו מירכאות תואם נוסף. לדוגמה, אם רוצים להשתמש בתו בריחה (escape) לתו ברירת המחדל ' " ', צריך להשתמש ב-' "" '.
קידוד ללא -E או --encoding encoding (Java, Python) (אופציונלי) קידוד התווים של הנתונים. הערכים הנתמכים הם: UTF-8,‏ ISO-8859-1,‏ UTF-16BE,‏ UTF-16LE,‏ UTF-32BE או UTF-32LE. ערך ברירת המחדל הוא UTF-8. ‫BigQuery מפענח את הנתונים אחרי שהנתונים הגולמיים הבינאריים פוצלו באמצעות הערכים של המאפיינים quote ו-fieldDelimiter.
תו בקרה של ASCII ללא --preserve_ascii_control_characters ללא (אופציונלי) אם רוצים לאפשר ASCII 0 ותווי בקרה אחרים של ASCII, צריך להגדיר את --preserve_ascii_control_characters לערך true בעבודות הטעינה.
סמני Null סמני Null --null_markers nullMarkers (Java, Python) (אופציונלי) רשימה של מחרוזות מותאמות אישית שמייצגות ערך NULL בנתוני CSV. אי אפשר להשתמש באפשרות הזו עם האפשרות --null_marker.
אזור זמן אזור זמן --time_zone timeZone (Java, Python) (אופציונלי) אזור הזמן שיוגדר כברירת מחדל ויחול על ניתוח של ערכי חותמות זמן שלא צוין עבורם אזור זמן ספציפי. בודקים את השמות התקינים של אזורי הזמן. אם הערך הזה לא מופיע, המערכת מנתחת את ערכי חותמת הזמן ללא אזור זמן ספציפי באמצעות אזור הזמן שמוגדר כברירת מחדל, UTC.
פורמט התאריך פורמט התאריך --date_format dateFormat (Java, Python) (אופציונלי) רכיבי פורמט שמגדירים את הפורמט של ערכי התאריך בקובצי הקלט (לדוגמה, MM/DD/YYYY). אם הערך הזה מופיע, הפורמט הזה הוא פורמט התאריך התואם היחיד. זיהוי אוטומטי של סכימה יקבע גם את סוג העמודה DATE על סמך הפורמט הזה במקום הפורמט הקיים. אם הערך הזה לא מופיע, המערכת מנתחת את השדה 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 מנותח באמצעות פורמטים שמוגדרים כברירת מחדל.