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

אפשר לטעון נתונים ב-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 נקראת 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 console

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

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

    הדף Object details נפתח.

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

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

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

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

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

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

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

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

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

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

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

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

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

  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

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

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

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

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

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

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

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