טעינת נתונים באצווה

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

  • Avro
  • ערכים מופרדים בפסיקים (‎CSV)
  • ‫JSON (מופרד בתו שורה חדשה)
  • ORC
  • Parquet
  • ייצוא של Datastore שמאוחסן ב-Cloud Storage
  • ייצוא של Firestore שמאוחסן ב-Cloud Storage

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

נסו בעצמכם

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

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

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

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

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

‫BigQuery תומך בטעינת נתונים מכל אחת ממחלקות האחסון הבאות ב-Cloud Storage:

  • רגילה
  • Nearline
  • Coldline
  • העברה לארכיון

כדי ללמוד איך לטעון נתונים ל-BigQuery, אפשר לעיין בדף שמתאים לפורמט הנתונים שלכם:

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

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

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

אחזור URI של Cloud Storage

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

נתיב המשאב ב-Cloud Storage מכיל את שם הקטגוריה של Cloud Storage ואת האובייקט (שם הקובץ). לדוגמה, אם שם הקטגוריה של Cloud Storage הוא mybucket ושם קובץ הנתונים הוא myfile.csv, נתיב המשאב יהיה gs://mybucket/myfile.csv.

‫BigQuery לא תומך בנתיבי משאבים ב-Cloud Storage שכוללים כמה לוכסנים רצופים אחרי שני הלכסנים הראשוניים. שמות של אובייקטים ב-Cloud Storage יכולים להכיל כמה לוכסנים רצופים (/). עם זאת, BigQuery ממיר כמה לוכסנים רצופים ללוכסן יחיד. לדוגמה, נתיב המשאב הבא, למרות שהוא תקין ב-Cloud Storage, לא פועל ב-BigQuery:‏ gs://bucket/my//object//name.

כדי לאחזר את נתיב המשאב ב-Cloud Storage:

  1. פותחים את מסוף Cloud Storage.

    מסוף Cloud Storage

  2. עוברים למיקום של האובייקט (הקובץ) שמכיל את נתוני המקור.

  3. לוחצים על שם האובייקט.

    הדף Object details נפתח.

  4. מעתיקים את הערך שמופיע בשדה gsutil URI, שמתחיל ב-gs://.

בייצוא של Google Datastore אפשר לציין רק URI אחד, והוא חייב להסתיים ב-.backup_info או ב-.export_metadata.

תמיכה בתווים כלליים לחיפוש במזהי URI של Cloud Storage

אם הנתונים שלכם מפוצלים לכמה קבצים, אתם יכולים להשתמש בתו כללי של כוכבית (*) כדי לבחור כמה קבצים. השימוש בתו הכללי לחיפוש כוכבית צריך להיות בהתאם לכללים הבאים:

  • הכוכבית יכולה להופיע בתוך שם האובייקט או בסוף שם האובייקט.
  • אין תמיכה בשימוש בכמה כוכביות. לדוגמה, הנתיב gs://mybucket/fed-*/temp/*.csv לא תקין.
  • אי אפשר להשתמש בכוכבית עם שם הקטגוריה.

דוגמאות:

  • בדוגמה הבאה מוצג איך בוחרים את כל הקבצים בכל התיקיות שמתחילות בקידומת gs://mybucket/fed-samples/fed-sample:

    gs://mybucket/fed-samples/fed-sample*

  • בדוגמה הבאה אפשר לראות איך בוחרים רק קבצים עם הסיומת .csv בתיקייה בשם fed-samples ובכל תיקיות המשנה של fed-samples:

    gs://mybucket/fed-samples/*.csv

  • בדוגמה הבאה מוצג איך לבחור קבצים עם תבנית שמות של fed-sample*.csv בתיקייה בשם fed-samples. בדוגמה הזו לא נבחרו קבצים בתיקיות משנה של fed-samples.

    gs://mybucket/fed-samples/fed-sample*.csv

כשמשתמשים בכלי שורת הפקודה של BigQuery, יכול להיות שיהיה צורך להשתמש בתו בריחה לכוכבית בפלטפורמות מסוימות.

אי אפשר להשתמש בתו כללי של כוכבית כשמטעינים נתוני ייצוא של Datastore או Firestore מ-Cloud Storage.

מגבלות

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

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

יכול להיות שיש מגבלות נוספות בהתאם לפורמט של נתוני המקור ב-Cloud Storage. למידע נוסף:

טעינת נתונים מקבצים מקומיים

אפשר לטעון נתונים ממקור נתונים שניתן לקריאה (כמו המחשב המקומי) באמצעות אחת מהאפשרויות הבאות:

  • מסוף Google Cloud
  • הפקודה bq load בכלי שורת הפקודה bq
  • ‫API
  • ספריות הלקוח

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

כדי לטעון נתונים מחנויות מקומיות:

המסוף

  1. פותחים את הדף BigQuery במסוף Google Cloud .

    לדף BigQuery

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

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

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

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

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

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

    • בקטע יצירת טבלה מ, בוחרים באפשרות העלאה.
    • בקטע בחירת קובץ, לוחצים על עיון.
    • מחפשים את הקובץ ולוחצים על פתיחה. שימו לב: אי אפשר להשתמש בתווים כלליים לחיפוש וברשימות מופרדות בפסיקים בקבצים מקומיים.
    • בקטע פורמט קובץ, בוחרים באפשרות CSV,‏ JSON (מופרד בתו שורה חדשה),‏ Avro,‏ Parquet או ORC.

  6. בדף יצירת טבלה, בקטע יעד:

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

  7. בקטע Schema (סכימה), מזינים את הגדרת הסכימה.

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

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

      • לוחצים על עריכה כטקסט ומזינים את סכימת הטבלה כמערך JSON:

      • משתמשים באפשרות הוספת שדה כדי להזין את הסכימה באופן ידני.

  8. בוחרים את הפריטים הרלוונטיים בקטע אפשרויות מתקדמות. מידע על האפשרויות הזמינות מופיע במאמרים בנושא אפשרויות ל-CSV ואפשרויות ל-JSON.

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

    • כתיבה אם ריק: כתיבת הנתונים רק אם הטבלה ריקה.
    • הוספה לטבלה: הוספת הנתונים לסוף הטבלה. זוהי הגדרת ברירת המחדל.
    • ‫Overwrite table (החלפת הטבלה): כל הנתונים הקיימים בטבלה יימחקו לפני כתיבת הנתונים החדשים.

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

BQ

משתמשים בפקודה bq load, מציינים את source_format וכוללים את הנתיב לקובץ המקומי.

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

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

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

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

  • ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, צריך להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
  • FORMAT: CSV, AVRO, PARQUET, ORC, או NEWLINE_DELIMITED_JSON.
  • project_id: מזהה הפרויקט.
  • dataset: מערך נתונים קיים.
  • ‫table: שם הטבלה שאליה טוענים את הנתונים.
  • ‫path_to_source: הנתיב לקובץ המקומי.
  • ‫schema: סכימה תקינה. הסכימה יכולה להיות קובץ JSON מקומי, או שאפשר להקליד אותה בשורה כחלק מהפקודה. אפשר גם להשתמש בדגל --autodetect במקום לספק הגדרת סכימה.

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

דוגמאות:

הפקודה הבאה טוענת קובץ JSON מקומי שמופרד בתו שורה חדשה (mydata.json) לטבלה בשם mytable ב-mydataset בפרויקט שמוגדר כברירת מחדל. הסכימה מוגדרת בקובץ סכימה מקומי בשם myschema.json.

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

הפקודה הבאה טוענת קובץ CSV מקומי (mydata.csv) לטבלה בשם mytable ב-mydataset ב-myotherproject. הסכימה מוגדרת בשורה בפורמט FIELD:DATA_TYPE, FIELD:DATA_TYPE.

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

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

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

C#‎

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

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

בדוגמת הקוד הבאה מוסבר איך לטעון קובץ CSV מקומי לטבלה חדשה ב-BigQuery. כדי לטעון קובץ מקומי בפורמט אחר, משתמשים במחלקה של אפשרויות העדכון לפורמט המתאים ממחלקת הבסיס JobCreationOptions במקום ב-UploadCsvOptions.


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

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.

            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

המשך

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

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

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

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename 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()

	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

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

Java

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

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

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

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

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

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

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

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function loadLocalFile() {
  // Imports a local file into a table.

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

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

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

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

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';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('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. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

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

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

with open(file_path, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_id, job_config=job_config)

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

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

Ruby

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

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

בדוגמת הקוד הבאה מוסבר איך לטעון קובץ CSV מקומי לטבלה חדשה ב-BigQuery. כדי לטעון קובץ מקומי בפורמט אחר, צריך להגדיר את הפרמטר format של השיטה Table#load_job לפורמט המתאים.

require "google/cloud/bigquery"

def load_from_file dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

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

מגבלות

טעינת נתונים מחנויות מקומיות כפופה למגבלות הבאות:

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

טעינת קיבולת המשרה

בדומה למצב על פי דרישה של שאילתות, כברירת מחדל, עבודות טעינה משתמשות במאגר משותף של משבצות. אם עבודת טעינה משתמשת במאגר המשותף, ההזמנה default-pipeline מוצגת בפרטי העבודה. ‫BigQuery לא מבטיח את הקיבולת הזמינה של המאגר המשותף הזה או את קצב העברת הנתונים של עבודת הטעינה.

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

טעינת נתונים דחוסים ולא דחוסים

בפורמטים Avro,‏ Parquet ו-ORC,‏ BigQuery תומך בטעינת קבצים שבהם הנתונים דחוסים באמצעות codec נתמך. עם זאת, BigQuery לא תומך בטעינת קבצים בפורמטים האלה שנדחסו בעצמם, למשל באמצעות כלי השירות gzip.

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

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

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

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

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

הוספה לטבלה או החלפה של טבלה

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

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

  • הוספת שדות חדשים
  • הגדרת השדות REQUIRED לערך NULLABLE

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

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

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

מדיניות בנושא מכסה

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

צפייה בשימוש הנוכחי במכסה

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

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

תמחור

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

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

תרחיש שימוש לדוגמה

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

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

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

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

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