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

טעינת נתונים באצווה ב-BigQuery מאפשרת להטמיע נתונים מ-Cloud Storage או מקובץ מקומי בטבלה חדשה או קיימת, במשימת טעינה אחת. אפשר לטעון קובצי Avro, ערכים מופרדים בפסיקים (CSV), קובצי JSON מופרדים בשורה חדשה, קובצי ORC או קובצי Parquet, וגם קובצי ייצוא של Datastore ו-Firestore שמאוחסנים ב-Cloud Storage. כדי להפוך טעינות חוזרות מ-Cloud Storage ל-BigQuery לאוטומטיות, אתם יכולים להשתמש בשירות העברת הנתונים ל-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, בקשו מהאדמין לתת לכם את התפקיד אדמין של אחסון (roles/storage.admin) ב-IAM בקטגוריה. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

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

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

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

יצירת קבוצת נתונים

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

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

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

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

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

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

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

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

אחזור ה-URI של Cloud Storage

כדי לטעון נתונים ממקור נתונים ב-Cloud Storage, צריך לספק את ה-URI של 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, יכול להיות שתצטרכו להוסיף תו בריחה (escape) לכוכבית בפלטפורמות מסוימות.

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

מגבלות

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

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

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

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

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

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

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

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

המסוף

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

    כניסה לדף BigQuery

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  9. אופציונלי: בקטע Advanced options בוחרים את אופן הכתיבה:

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

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

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 קבצים שבהם נתוני הקובץ נדחסו באמצעות קודק נתמך. עם זאת, אי אפשר לטעון ל-BigQuery קבצים בפורמטים האלה שנדחסו בעצמם, למשל באמצעות הכלי gzip.

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

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

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

בפורמטים אחרים של נתונים, כמו 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 באמצעות מאגר ה-slots המשותף לא כרוכה בתשלום. למידע נוסף, קראו את המאמר תמחור הטמעת נתונים ב-BigQuery.

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

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

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

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

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

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

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