ייצוא נתוני טבלה ל-Cloud Storage

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

אחרי טעינת הנתונים ל-BigQuery, אפשר לייצא אותם בכמה פורמטים. אפשר לייצא מ-BigQuery עד 1GB של נתונים לוגיים לקובץ יחיד. אם מייצאים יותר מ-‎1 GB של נתונים, צריך לייצא את הנתונים לכמה קבצים. כשמייצאים את הנתונים לכמה קבצים, הגודל של הקבצים משתנה.

אפשר גם לייצא את תוצאות השאילתה באמצעות ההצהרה EXPORT DATA. אפשר להשתמש ב-EXPORT DATA OPTIONS כדי לציין את הפורמט של הנתונים המיוצאים.

לבסוף, אפשר להשתמש בשירות כמו Dataflow כדי לקרוא נתונים מ-BigQuery במקום לייצא אותם מ-BigLake. מידע נוסף על שימוש ב-Dataflow לקריאה מ-BigQuery וכתיבה ל-BigQuery זמין במסמכי התיעוד בנושא קלט/פלט של BigQuery.

מגבלות על ייצוא

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

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

• אי אפשר לייצא נתונים מטבלה לקובץ מקומי, ל-Google Sheets או ל-Google Drive. המיקום היחיד שנתמך לייצוא הוא Cloud Storage. מידע על שמירת תוצאות של שאילתות זמין במאמר הורדה ושמירה של תוצאות שאילתות.
• אפשר לייצא עד 1GB של נתונים לוגיים של טבלה לקובץ יחיד. אם אתם מייצאים יותר מ-1GB של נתונים, אתם יכולים להשתמש בתו כללי כדי לייצא את הנתונים לכמה קבצים. כשמייצאים נתונים לכמה קבצים, הגודל של הקבצים משתנה. כדי להגביל את גודל הקובץ המיוצא, אפשר לחלק את הנתונים ולייצא כל מחיצה.
• אין ערובה לגודל הקובץ שייווצר כשמשתמשים בהצהרה EXPORT DATA.
• מספר הקבצים שנוצרים על ידי עבודת חילוץ יכול להשתנות.
• אי אפשר לייצא נתונים מקוננים וחוזרים בפורמט CSV. יש תמיכה בנתונים מקוננים וחוזרים בייצוא של קובצי Avro,‏ JSON ו-Parquet.
• כשמייצאים נתונים בפורמט JSON, סוגי הנתונים INT64 (מספר שלם) מקודדים כמחרוזות JSON כדי לשמור על דיוק של 64 ביט כשמערכות אחרות קוראות את הנתונים.
• אי אפשר לייצא נתונים מכמה טבלאות במשימת חילוץ אחת.
• כשמייצאים נתונים באמצעות מסוף Google Cloud , אי אפשר לבחור סוג דחיסה אחר מלבד GZIP.
• כשמייצאים טבלה בפורמט JSON, הסמלים <, > ו-& מומרים באמצעות סימון Unicode‏ \uNNNN, כאשר N היא ספרה הקסדצימלית. לדוגמה, profit&loss הופך ל-profit\u0026loss. ההמרה הזו ל-Unicode מתבצעת כדי למנוע פרצות אבטחה.
• סדר הנתונים בטבלה המיוצאת לא מובטח, אלא אם משתמשים בהצהרה EXPORT DATA ומציינים פסקה ORDER BY ב-query_statement.
• ‫BigQuery לא תומך בנתיבי משאבים ב-Cloud Storage שכוללים כמה לוכסנים עוקבים אחרי שני הלכסנים הראשוניים. שמות של אובייקטים ב-Cloud Storage יכולים להכיל כמה תווים עוקבים של קו נטוי ("/"). עם זאת, BigQuery ממיר כמה לוכסנים עוקבים ללוכסן אחד. לדוגמה, נתיב המשאב הבא, למרות שהוא תקין ב-Cloud Storage, לא פועל ב-BigQuery: ‏ gs://bucket/my//object//name.
• נתונים חדשים שנטענו ל-BigQuery בזמן שמשימת החילוץ פועלת לא ייכללו במשימת החילוץ הזו. כדי לייצא את הנתונים החדשים, צריך ליצור משימת חילוץ חדשה.

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

להקצות תפקידים בניהול הזהויות והרשאות הגישה (IAM) שמעניקים למשתמשים את ההרשאות הנדרשות לביצוע כל משימה שמופיעה במאמר הזה.

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

כדי לבצע את המשימות שמתוארות במאמר הזה, נדרשות ההרשאות הבאות.

הרשאות לייצוא נתונים מטבלה ב-BigQuery

כדי לייצא נתונים מטבלה ב-BigQuery, אתם צריכים את הרשאת bigquery.tables.export IAM.

כל אחד מהתפקידים הבאים שמוגדרים מראש ב-IAM כולל את ההרשאה bigquery.tables.export:

• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

הרשאות להפעלת משימת חילוץ

כדי להפעיל עבודת חילוץ, אתם צריכים את הרשאת ה-IAM‏ bigquery.jobs.create.

כל אחד מתפקידי ה-IAM המוגדרים מראש הבאים כולל את ההרשאות שנדרשות להפעלת משימת חילוץ:

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

הרשאות לכתיבת הנתונים בקטגוריה של Cloud Storage

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

• storage.objects.create
• storage.objects.delete

כל אחד מתפקידי ה-IAM המוגדרים מראש הבאים כולל את ההרשאות שנדרשות כדי לכתוב את הנתונים לקטגוריה קיימת של Cloud Storage:

• roles/storage.objectAdmin
• roles/storage.admin

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

פורמטים של ייצוא וסוגי דחיסה

‫BigQuery תומך בפורמטים הבאים של נתונים ובסוגי הדחיסה הבאים של נתונים מיוצאים.

פורמט נתונים	סוגי דחיסה נתמכים	פרטים
CSV	GZIP	אתם יכולים לשלוט בתו המפריד של קובץ ה-CSV בנתונים המיוצאים באמצעות הדגל --field_delimiter של כלי שורת הפקודה של BigQuery או באמצעות מאפיין משימת החילוץ configuration.extract.fieldDelimiter. אין תמיכה בנתונים שהם רכיב בתוך רכיב ובנתונים שחוזרים על עצמם.
JSON	GZIP	יש תמיכה בנתונים בתוך נתונים ובנתונים חוזרים.
Avro	DEFLATE, ‏ SNAPPY	אין תמיכה ב-GZIP בייצוא של Avro. יש תמיכה בנתונים בתוך נתונים ובנתונים חוזרים. פרטים על ייצוא בפורמט Avro
Parquet	SNAPPY, ‏ GZIP, ‏ ZSTD	יש תמיכה בנתונים בתוך נתונים ובנתונים חוזרים. פרטים על ייצוא ל-Parquet

ייצוא נתונים

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

ייצוא נתוני טבלה

אפשר לייצא נתונים מטבלה באמצעות:

• שימוש במסוף Google Cloud
• שימוש בפקודה bq extract בכלי שורת הפקודה של BigQuery
• שליחת עבודת extract באמצעות ה-API או ספריות הלקוח

צריך לבחור אחת מהאפשרויות האלה:

המסוף

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

   לדף BigQuery

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

   

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

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

4. לוחצים על סקירה כללית > טבלאות ובוחרים טבלה.

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

6. בתיבת הדו-שיח Export to Google Cloud Storage (ייצוא אל Google Cloud Storage):

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

7. לוחצים על שמירה כדי לייצא את הטבלה.

כדי לבדוק את התקדמות העבודה, בחלונית Explorer לוחצים על Job history ומחפשים עבודה מסוג EXTRACT.

כדי לייצא תצוגות ל-Cloud Storage, משתמשים בהצהרת EXPORT DATA OPTIONS.

SQL

משתמשים בהצהרה EXPORT DATA. בדוגמה הבאה מיוצאים שדות נבחרים מטבלה בשם mydataset.table1:

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

   כניסה ל-BigQuery

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

   EXPORT DATA
     OPTIONS (
       uri = 'gs://bucket/folder/*.csv',
       format = 'CSV',
       overwrite = true,
       header = true,
       field_delimiter = ';')
   AS (
     SELECT field1, field2
     FROM mydataset.table1
     ORDER BY field1
   );

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

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

BQ

משתמשים בפקודה bq extract עם הדגל --destination_format.

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

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

• ‫--compression: סוג הדחיסה שבה יש להשתמש עבור קבצים מיוצאים.
• ‫--field_delimiter: התו שמציין את הגבול בין העמודות בקובץ הפלט של ייצוא CSV. גם \t וגם tab מותרים לשימוש כמפרידים בין כרטיסיות.
• ‫--print_header: כשמציינים את האפשרות הזו, שורות הכותרת מודפסות בפורמטים שיש להם כותרות, כמו CSV.

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

כאשר:

• ‫location הוא השם של המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ ‎.bigqueryrc.
• ‫format הוא הפורמט של הנתונים המיוצאים: CSV,‏ NEWLINE_DELIMITED_JSON,‏ AVRO או PARQUET.
• ‫compression_type הוא סוג דחיסה נתמך לפורמט הנתונים שלכם. פורמטים של ייצוא וסוגי דחיסה
• ‫delimiter הוא התו שמציין את הגבול בין העמודות בייצוא ל-CSV. ‫\t ו-tab הם שמות מקובלים לכרטיסייה.
• ‫boolean הוא true או false. אם הערך הוא true, שורות הכותרת מודפסות בנתונים המיוצאים אם פורמט הנתונים תומך בכותרות. ערך ברירת המחדל הוא true.
• ‫project_id הוא מזהה הפרויקט.
• ‫dataset הוא השם של מערך נתוני המקור.
• ‫table היא הטבלה שמייצאים. אם משתמשים במעצב מחיצות, צריך להקיף את נתיב הטבלה בגרשיים בודדים או להשתמש בתו $ כתו בריחה.
• ‫bucket הוא השם של קטגוריית Cloud Storage שאליה מייצאים את הנתונים. מערך הנתונים ב-BigQuery וקטגוריית Cloud Storage צריכים להיות באותו מיקום.
• ‫filename.ext הוא השם והסיומת של קובץ הנתונים המיוצא. אפשר לייצא לכמה קבצים באמצעות תו כללי לחיפוש.

דוגמאות:

לדוגמה, הפקודה הבאה מייצאת את mydataset.mytable לקובץ דחוס בפורמט gzip בשם myfile.csv. ‫myfile.csv מאוחסן בקטגוריה של Cloud Storage בשם example-bucket.

bq extract \
--compression GZIP \
'mydataset.mytable' \
gs://example-bucket/myfile.csv

פורמט היעד שמוגדר כברירת מחדל הוא CSV. כדי לייצא ל-JSON או ל-Avro, משתמשים בדגל destination_format ומגדירים אותו ל-NEWLINE_DELIMITED_JSON או ל-AVRO. לדוגמה:

bq extract \
--destination_format NEWLINE_DELIMITED_JSON \
'mydataset.mytable' \
gs://example-bucket/myfile.json

הפקודה הבאה מייצאת את mydataset.mytable לקובץ Avro שדחוס באמצעות Snappy. שם הקובץ הוא myfile.avro. ‫myfile.avro מיוצא לקטגוריה של Cloud Storage בשם example-bucket.

bq extract \
--destination_format AVRO \
--compression SNAPPY \
'mydataset.mytable' \
gs://example-bucket/myfile.avro

הפקודה הבאה מייצאת מחיצה אחת של mydataset.my_partitioned_table לקובץ CSV ב-Cloud Storage:

bq extract \
--destination_format CSV \
'mydataset.my_partitioned_table$0' \
gs://example-bucket/single_partition.csv

API

כדי לייצא נתונים, יוצרים extract משימה וממלאים את הגדרות המשימה.

הערה: אם אתם מייצאים נתונים לפורמט Parquet, יכול להיות שיהיה מהיר יותר להשתמש בתבנית BigQuery export to Parquet (via BigQuery Storage API) במקום לכתוב פתרון בהתאמה אישית.

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

1. יוצרים משימת חילוץ שמפנה לנתוני המקור ב-BigQuery ולמקום היעד ב-Cloud Storage.

2. מציינים את טבלת המקור באמצעות אובייקט ההגדרה sourceTable שמכיל את מזהה הפרויקט, מזהה מערך הנתונים ומזהה הטבלה.

3. המאפיין destination URI(s) צריך להיות מוגדר באופן מלא, בפורמט gs://bucket/filename.ext. כל URI יכול להכיל תו כללי אחד לחיפוש '*', והוא חייב להופיע אחרי שם הקטגוריה.

4. מגדירים את פורמט הנתונים באמצעות המאפיין configuration.extract.destinationFormat. לדוגמה, כדי לייצא קובץ JSON, מגדירים את המאפיין הזה לערך NEWLINE_DELIMITED_JSON.

5. כדי לבדוק את סטטוס המשרה, מתקשרים אל jobs.get(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 BigQueryExtractTable
{
    public void ExtractTable(
        string projectId = "your-project-id",
        string bucketName = "your-bucket-name")
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Define a destination URI. Use a single wildcard URI if you think
        // your exported data will be larger than the 1 GB maximum value.
        string destinationUri = $"gs://{bucketName}/shakespeare-*.csv";
        BigQueryJob job = client.CreateExtractJob(
            projectId: "bigquery-public-data",
            datasetId: "samples",
            tableId: "shakespeare",
            destinationUri: destinationUri
        );
        job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        Console.Write($"Exported table to {destinationUri}.");
    }
}

Go

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

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

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as CSV.
func exportTableAsCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.FieldDelimiter = ","

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

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

import com.google.cloud.RetryOption;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import org.threeten.bp.Duration;

public class ExtractTableToCsv {

  public static void runExtractTableToCsv() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    String bucketName = "my-bucket";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html

    String dataFormat = "CSV";
    extractTableToCsv(projectId, datasetName, tableName, destinationUri, dataFormat);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToCsv(
      String projectId,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat) {
    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(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);

      Job job = table.extract(dataFormat, destinationUri);

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob =
          job.waitFor(
              RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
              RetryOption.totalTimeout(Duration.ofMinutes(3)));
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println(
          "Table export successful. Check in GCS bucket for the " + dataFormat + " file.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \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');

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableToGCS() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as raw CSV.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
  };

  // Export data from the table into a Google Cloud Storage file
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .extract(storage.bucket(bucketName).file(filename), options);

  console.log(`Job ${job.id} created.`);

  // 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;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $bigQuery = new BigQueryClient([
      'projectId' => $projectId,
    ]);
    $dataset = $bigQuery->dataset($datasetId);
    $table = $dataset->table($tableId);
    $destinationUri = "gs://{$bucketName}/{$tableId}.json";
    // Define the format to use. If the format is not specified, 'CSV' will be used.
    $format = 'NEWLINE_DELIMITED_JSON';
    // Create the extract job
    $extractConfig = $table->extract($destinationUri)->destinationFormat($format);
    // Run the job
    $job = $table->runJob($extractConfig);  // Waits for the job to complete
    printf('Exported %s to %s' . PHP_EOL, $table->id(), $destinationUri);
}

Python

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Ruby

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

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

require "google/cloud/bigquery"

def extract_table bucket_name = "my-bucket",
                  dataset_id  = "my_dataset_id",
                  table_id    = "my_table_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table    table_id

  # Define a destination URI. Use a single wildcard URI if you think
  # your exported data will be larger than the 1 GB maximum value.
  destination_uri = "gs://#{bucket_name}/output-*.csv"

  extract_job = table.extract_job destination_uri do |config|
    # Location must match that of the source table.
    config.location = "US"
  end
  extract_job.wait_until_done! # Waits for the job to complete

  puts "Exported #{table.id} to #{destination_uri}"
end

ייצוא מטא-נתונים של טבלה

כדי לייצא מטא-נתונים של טבלה מטבלאות Iceberg, משתמשים בהצהרת ה-SQL הבאה:

EXPORT TABLE METADATA FROM `[[PROJECT_NAME.]DATASET_NAME.]TABLE_NAME`;

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

• ‫PROJECT_NAME: שם הפרויקט של הטבלה. ערך ברירת המחדל הוא הפרויקט שמריץ את השאילתה הזו.
• ‫DATASET_NAME: השם של מערך הנתונים של הטבלה.
• ‫TABLE_NAME: שם הטבלה.

המטא-נתונים המיוצאים נמצאים בתיקייה STORAGE_URI/metadata, כאשר STORAGE_URI הוא מיקום האחסון של הטבלה שהוגדר באפשרויות.

ייצוא תוצאות של שאילתה

כדי לייצא את תוצאות השאילתה ל-Cloud Storage במסוף Google Cloud :

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

   לדף BigQuery

2. לוחצים על שאילתת SQL.

3. מזינים שאילתת GoogleSQL תקינה באזור הטקסט של עורך השאילתות.

4. לוחצים על Run.

5. אחרי שהתוצאות מוחזרות, לוחצים על שמירת התוצאות > Cloud Storage.

6. בתיבת הדו-שיח Export to Google Cloud Storage (ייצוא אל Google Cloud Storage):

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

7. לוחצים על שמירה כדי לייצא את תוצאות השאילתה.

כדי לבדוק את התקדמות העבודה, מרחיבים את החלונית Job history ומחפשים את העבודה עם הסוג EXTRACT.

פרטי ייצוא בפורמט Avro

נתונים בפורמט Avro מוצגים ב-BigQuery בדרכים הבאות:

• קבצי הייצוא שמתקבלים הם קובצי Avro container.
• כל שורה ב-BigQuery מיוצגת כרשומת Avro. נתונים מקוננים מיוצגים על ידי אובייקטים מקוננים של רשומות.
• שדות REQUIRED מיוצגים כסוגי ה-Avro המתאימים. לדוגמה, סוג INTEGER ב-BigQuery ממופה לסוג LONG ב-Avro.
• שדות NULLABLE מיוצגים כאיחוד Avro של הסוג המתאים ושל 'null'.
• שדות REPEATED מיוצגים כמערכי Avro.
• סוגי הנתונים TIMESTAMP מיוצגים כסוג לוגי timestamp-micros (הם מוסיפים הערות לסוג LONG של Avro) כברירת מחדל גם במשימות Extract וגם ב-SQL של Export Data. (חשוב לדעת: אפשר להוסיף use_avro_logical_types=False ל-Export Data Options כדי להשבית את הסוג הלוגי, כך שבמקום זאת ייעשה שימוש בסוג string בעמודת חותמת הזמן, אבל בעבודות Extract תמיד נעשה שימוש בסוג הלוגי Avro).
• סוגי הנתונים DATE מיוצגים כסוג לוגי date (הם מוסיפים הערות לסוגי INT Avro) כברירת מחדל ב-SQL של ייצוא נתונים, אבל מיוצגים כסוג string כברירת מחדל במשימות חילוץ. (הערה: אפשר להוסיף use_avro_logical_types=False ל-Export Data Options כדי להשבית את הסוג הלוגי, או להשתמש בדגל --use_avro_logical_types=True כדי להפעיל את הסוג הלוגי בעבודות Extract).
• סוגי הנתונים TIME מיוצגים כסוג לוגי timestamp-micro (הם מוסיפים הערות לסוגי LONG Avro) כברירת מחדל ב-Export Data SQL, אבל מיוצגים כסוג string כברירת מחדל במשימות Extract. (הערה: אפשר להוסיף use_avro_logical_types=False ל-Export Data Options כדי להשבית את הסוג הלוגי, או להשתמש בדגל --use_avro_logical_types=True כדי להפעיל את הסוג הלוגי במשימות Extract).
• סוגי הנתונים DATETIME מיוצגים כסוגי STRING של Avro (סוג מחרוזת עם סוג לוגי מותאם אישית בשם datetime) כברירת מחדל ב-Export Data SQL, אבל מיוצגים כסוג string כברירת מחדל במשימות Extract. (הערה: אפשר להוסיף use_avro_logical_types=False ל-Export Data Options כדי להשבית את הסוג הלוגי, או להשתמש בדגל --use_avro_logical_types=True כדי להפעיל את הסוג הלוגי בעבודות Extract).
• אין תמיכה בסוגי RANGE בייצוא של Avro.

הערה: הקידוד של מחרוזת הוא בהתאם למפרט RFC 3339 של Internet Engineering Task Force.

סוגי הנתונים NUMERIC(P[, S]) ו-BIGNUMERIC(P[, S]) עם פרמטרים מעבירים את הפרמטרים של סוג הדיוק והקנה מידה שלהם לסוג הלוגי העשרוני של Avro.

זהירות:

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

אי אפשר להשתמש בפורמט Avro בשילוב עם דחיסת GZIP. כדי לדחוס נתוני Avro, משתמשים בכלי שורת הפקודה של BigQuery או ב-API ומציינים אחד מסוגי הדחיסה הנתמכים לנתוני Avro: ‏ DEFLATE או SNAPPY.

פרטי ייצוא של קובצי Parquet

‫BigQuery ממיר סוגי נתונים של GoogleSQL לסוגי הנתונים הבאים של Parquet:

סוג נתונים ב-BigQuery	סוג פרימיטיבי של Parquet	סוג לוגי של Parquet
מספר שלם	INT64	NONE
Numeric	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 38, scale = 9)
מספרי(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
BigNumeric	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 76, scale = 38)
BigNumeric(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
נקודה צפה	FLOAT	NONE
בוליאני	BOOLEAN	NONE
String	BYTE_ARRAY	STRING (UTF8)
בייטים	BYTE_ARRAY	NONE
תאריך	INT32	DATE
תאריך ושעה	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
שעה	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
חותמת הזמן	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
גיאוגרפיה	BYTE_ARRAY	GEOGRAPHY (edges = spherical)

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

זהירות: אם מייצאים סוג DATETIME ל-Parquet, אי אפשר לטעון את קובץ Parquet ישירות בחזרה לאותה סכימת טבלה, כי הערך שהומר לא יתאים לסכימה.

אפשר להשתמש בפתרונות העקיפים הבאים לסוגים DATETIME:

• טוענים את הקובץ לטבלת ביניים. אחר כך משתמשים בשאילתת SQL כדי להמיר את השדה ל-DATETIME ושומרים את התוצאה בטבלה חדשה. מידע נוסף זמין במאמר בנושא שינוי סוג הנתונים של עמודה.
• מספקים סכימה לטבלה באמצעות הדגל --schema בעבודת הטעינה. מגדירים את העמודה של התאריך והשעה כ-col:DATETIME.

הסוג הלוגי GEOGRAPHY מיוצג באמצעות מטא-נתונים של GeoParquet שנוספו לקבצים המיוצאים.

ייצוא נתונים לקובץ אחד או יותר

המאפיין destinationUris מציין את המיקום או המיקומים ושמות הקבצים שאליהם BigQuery צריך לייצא את הקבצים.

‫BigQuery תומך באופרטור יחיד של תו כללי לחיפוש (*) בכל URI. התו הכללי יכול להופיע בכל מקום ברכיב של שם הקובץ. השימוש באופרטור wildcard מורה ל-BigQuery ליצור כמה קבצים מפולחים על סמך התבנית שסופקה. התו הכללי מוחלף במספר (החל מ-0), עם ריפוד משמאל ל-12 ספרות. לדוגמה, אם ה-URI כולל תבנית wildcard בסוף שם הקובץ, ייווצרו קבצים עם התוספת 000000000000 לקובץ הראשון, 000000000001 לקובץ השני וכן הלאה.

בטבלה הבאה מפורטות כמה אפשרויות אפשריות של המאפיין destinationUris:

destinationUris אפשרויות
URI יחיד	אם מייצאים נתונים של טבלה בגודל של 1 GB או פחות, אפשר להשתמש ב-URI יחיד. האפשרות הזו היא התרחיש הנפוץ ביותר לשימוש, כי בדרך כלל הנתונים המיוצאים קטנים מהערך המקסימלי של 1GB. האפשרות הזו לא נתמכת ב- EXPORT DATA, צריך להשתמש בתו כללי לחיפוש של URI יחיד. הגדרת המאפיין: ['gs://my-bucket/file-name.json'] יצירה: gs://my-bucket/file-name.json
תו כללי לחיפוש של URI יחיד	אפשר להשתמש בתו כללי יחיד רק ברכיב של שם הקובץ ב-URI. אם אתם חושבים שהנתונים המיוצאים יהיו גדולים יותר מהערך המקסימלי של 1GB, השתמשו ב-URI עם תו כללי יחיד. ‫BigQuery מפצל את הנתונים לקבצים רבים על סמך התבנית שצוינה. גודל הקבצים המיוצאים משתנה. הגדרת המאפיין: ['gs://my-bucket/file-name-*.json'] יצירה: gs://my-bucket/file-name-000000000000.json gs://my-bucket/file-name-000000000001.json gs://my-bucket/file-name-000000000002.json ... ['gs://my-bucket/*'] יצירה: gs://my-bucket/000000000000 gs://my-bucket/000000000001 gs://my-bucket/000000000002 ...

הגבלת גודל הקובץ המיוצא

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

1. קובעים את מספר המחיצות שצריך, ששווה לגודל הכולל של הנתונים חלקי הגודל של קובץ הייצוא שנבחר. לדוגמה, אם יש לכם 8,000MB של נתונים ואתם רוצים שכל קובץ מיוצא יהיה בערך 20MB, אתם צריכים 400 מחיצות.

2. יוצרים טבלה חדשה עם חלוקה למחיצות ועם אשכולים לפי עמודה חדשה שנוצרה באופן אקראי בשם export_id. בדוגמה הבאה מוצגות הפעולות ליצירת טבלה חדשה processed_table מטבלה קיימת בשם source_table, שנדרשים לה n מחיצות כדי להגיע לגודל הקובץ שנבחר:

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );

3. לכל מספר שלם i בין 0 ל-n-1, מריצים הצהרת EXPORT DATA בשאילתה הבאה:

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;

חילוץ טבלה דחוסה

Go

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

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

import (
	"context"
	"fmt"

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

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as compressed CSV.
func exportTableAsCompressedCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsURI := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.Compression = bigquery.Gzip

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.ExtractJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to extract a compressed table
public class ExtractTableCompressed {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "MY_PROJECT_NAME";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    String compressed = "gzip";
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
    String dataFormat = "CSV";

    extractTableCompressed(
        projectName, datasetName, tableName, destinationUri, dataFormat, compressed);
  }

  public static void extractTableCompressed(
      String projectName,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat,
      String compressed) {
    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(projectName, datasetName, tableName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(tableId, destinationUri)
              .setCompression(compressed)
              .setFormat(dataFormat)
              .build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table extract compressed successful");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \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');

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableCompressed() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as a compressed file.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
    gzip: true,
  };

  // Export data from the table into a Google Cloud Storage file
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .extract(storage.bucket(bucketName).file(filename), options);

  console.log(`Job ${job.id} created.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv.gz")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table("shakespeare")
job_config = bigquery.job.ExtractJobConfig()
job_config.compression = bigquery.Compression.GZIP

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
    job_config=job_config,
)  # API request
extract_job.result()  # Waits for job to complete.

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

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

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

שולחים עבודת חילוץ באמצעות API או ספריות לקוח, ומעבירים מזהה ייחודי בתור jobReference.jobId. הפעולות של Extract Jobs הן אסינכרוניות. בודקים את סטטוס העבודה באמצעות מזהה העבודה הייחודי ששימש ליצירת העבודה. העבודה הושלמה בהצלחה אם status.status הוא DONE. אם status.errorResult מופיע, העבודה נכשלה וצריך לנסות שוב.

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

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

מכיוון שכמות הנתונים שצריך לקרוא קטנה, משתמשים ב-API‏ tabledata.list כדי לאחזר את כל השורות בטבלה בפורמט של מילון JSON. אם יש יותר מדף אחד של נתונים, המאפיין pageToken מוגדר בתוצאות. כדי לאחזר את דף התוצאות הבא, מבצעים עוד קריאה של tabledata.list וכוללים את ערך האסימון כפרמטר pageToken. אם הקריאה ל-API נכשלת עם שגיאת 5xx, צריך לנסות שוב עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff). אי אפשר לנסות שוב את רוב השגיאות מסוג 4xx. כדי להפריד טוב יותר בין BigQuery Export לבין יצירת דוחות, צריך לשמור את התוצאות בדיסק.

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

מידע על מכסות של משימות חילוץ זמין במאמר משימות חילוץ בדף מכסות ומגבלות.

נתוני השימוש במשימות חילוץ זמינים ב-INFORMATION_SCHEMA. רשומת העבודה בJOBS_BY_*טבלאות המערכת של עבודת החילוץ מכילה ערך total_bytes_processed שאפשר להשתמש בו כדי לעקוב אחרי השימוש המצטבר ולוודא שהוא לא חורג מ-50TiB ליום. במאמר סכימת INFORMATION_SCHEMA.JOBS מוסבר איך לשלוח שאילתה לתצוגה INFORMATION_SCHEMA.JOBS כדי לקבל את הערך total_bytes_processed.

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

כדי לראות את השימוש הנוכחי שלכם בשאילתות, בהעלאות, בחילוצים או בהעתקות, אתם יכולים להריץ שאילתה 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()

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

1. נכנסים לדף  Alerting במסוף Google Cloud :

   עוברים אל התראות

   אם משתמשים בסרגל החיפוש כדי למצוא את הדף הזה, בוחרים בתוצאה שכותרת המשנה שלה היא Monitoring.

2. בדף Alerting, לוחצים על Create Policy.

3. בקטע מצב הגדרת מדיניות, בוחרים באפשרות עורך קוד (MQL או PromQL).

4. בעורך השאילתות PromQL, מזינים את השאילתה הבאה:

   (
     sum by (project_id, quota_metric, location) (increase({"serviceruntime.googleapis.com/quota/rate/net_usage", monitored_resource="consumer_quota", service="bigquery.googleapis.com"}[1m]))
     /
     max by (project_id, quota_metric, location) ({"serviceruntime.googleapis.com/quota/limit", monitored_resource="consumer_quota", service="bigquery.googleapis.com", limit_name="ExtractBytesPerDay"})
   ) > 0.01
   

   אם האפשרות הרצה אוטומטית לא מופעלת, לוחצים על הרצת שאילתה.

5. מגדירים את שאר ההתראות ולוחצים על יצירת מדיניות.

לשלבים מפורטים ליצירת מדיניות התראות מבוססת-PromQL, אפשר לעיין במאמר בנושא יצירת מדיניות התראות מבוססת-PromQL (מסוף).

פתרון בעיות

אבחון ופתרון בעיות שקשורות לעבודות חילוץ.

אבחון בעיות באמצעות Logs Explorer

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

resource.type="bigquery_resource"
protoPayload.methodName="jobservice.insert"
(protoPayload.serviceData.jobInsertRequest.resource.jobConfiguration.query.query=~"EXPORT" OR
protoPayload.serviceData.jobCompletedEvent.eventName="extract_job_completed" OR
protoPayload.serviceData.jobCompletedEvent.job.jobConfiguration.query.query=~"EXPORT")

שגיאה שקשורה לחריגה מהמכסה היומית של בייטים לחילוץ

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

הודעת השגיאה

Your usage exceeded quota for ExtractBytesPerDay

אבחון

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

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

• צפייה במכסות של הפרויקט עם קריטריוני סינון כמו Name: Extract bytes per day או Metric: bigquery.googleapis.com/quota/extract/bytes, יחד עם התרשים 'הצגת נתוני השימוש', כדי לראות את מגמת השימוש לאורך כמה ימים.

• אפשר גם להריץ שאילתה ב-INFORMATION_SCHEMA.JOBS_BY_PROJECT כדי לראות את סך הבייטים שחולצו במשך כמה ימים. לדוגמה, השאילתה הבאה מחזירה את סך הבייטים היומי שעובד על ידי משימות EXTRACT בשבעת הימים האחרונים.

  SELECT
  TIMESTAMP_TRUNC(creation_time, DAY) AS day,
  SUM ( total_bytes_processed ) / POW(1024, 3) AS total_gibibytes_processed
  FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
  WHERE
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
  AND job_type = "EXTRACT"
  GROUP BY 1
  ORDER BY 2 DESC

• לאחר מכן, תוכלו לצמצם עוד יותר את התוצאות על ידי זיהוי המשימות הספציפיות שצורכות יותר בייטים מהצפוי. בדוגמה הבאה מוצגים 100 המשימות המובילות EXTRACT שצורכות יותר מ-100 GB שעברו עיבוד במהלך שבעת הימים האחרונים.

  SELECT
  creation_time,
  job_id,
  total_bytes_processed/POW(1024, 3) AS total_gigabytes_processed
  FROM
  `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
  WHERE
  creation_time BETWEEN TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY) AND CURRENT_TIMESTAMP()
  AND job_type="EXTRACT"
  AND total_bytes_processed > (POW(1024, 3) * 100)
  ORDER BY
  total_bytes_processed DESC
  LIMIT 100

אפשר גם להשתמש בכלי לבדיקת משימות עם מסננים כמו Bytes processed more than כדי לסנן משימות עם שימוש גבוה במעבד לתקופה מסוימת.

רזולוציה

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

בקטע ההערות במאמר משימות חילוץ מוסבר על גישות חלופיות לייצוא של יותר מ-50 TiB.

תמחור

מידע על התמחור של ייצוא נתונים מופיע בדף התמחור של BigQuery.

אחרי שהנתונים מיוצאים, אתם מחויבים על אחסון הנתונים ב-Cloud Storage. מידע נוסף מופיע במאמר בנושא תמחור של Cloud Storage.

אבטחת טבלאות

כדי לשלוט בגישה לטבלאות ב-BigQuery, אפשר לעיין במאמר בנושא שליטה בגישה למשאבים באמצעות IAM.

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

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