‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

אתם יכולים לייצא נתונים מטבלאות ב-BigQuery ל-Cloud Storage בפורמט CSV,‏ JSON,‏ Avro או Parquet לצורך גיבוי, העברה לארכיון או עיבוד בכלים אחרים. אחרי שטוענים את הנתונים ל-BigQuery, אפשר לייצא אותם באמצעות מסוף Google Cloud , כלי שורת הפקודה של BigQuery, ה-API, ספריות לקוח או שיטות ייצוא חלופיות.

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

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

אי אפשר לייצא נתוני טבלה לקובץ מקומי, ל-Google Sheets או ל-Google Drive. מיקום הייצוא היחיד שנתמך הוא Cloud Storage. למידע על שמירת תוצאות שאילתות, ראה הורדה ושמירה של תוצאות שאילתות.
אפשר לייצא עד 1GB של נתונים מטבלה לוגית לקובץ אחד. אם אתם מייצאים יותר מ-1GB של נתונים, השתמשו בתו כללי לחיפוש כדי לייצא את הנתונים למספר קבצים. כשמייצאים נתונים לכמה קבצים, הגודל של הקבצים משתנה. כדי להגביל את גודל הקובץ שמייצאים, אפשר לחלק את הנתונים למחיצות ולייצא כל מחיצה בנפרד. למידע נוסף והמלצות לגבי ייצוא של טבלאות גדולות, ראו שיקולים לייצוא של טבלאות גדולות.
גודל הקובץ שנוצר כשמשתמשים בהצהרה EXPORT DATA לא מובטח.
מספר הקבצים שנוצרים על ידי משימת חילוץ יכול להשתנות.
אי אפשר לייצא נתונים חוזרים ומקוננים בפורמט CSV. אפשר לייצא נתונים מקוננים וחוזרים בפורמטים Avro,‏ JSON ו-Parquet.
כשמייצאים נתונים בפורמט JSON, סוגי הנתונים INT64 (מספר שלם) מקודדים כמחרוזות JSON כדי לשמור על דיוק של 64 ביט כשהנתונים נקראים על ידי מערכות אחרות.
אי אפשר לייצא נתונים מכמה טבלאות במשימת חילוץ אחת.
אי אפשר לבחור סוג דחיסה אחר מלבד GZIP כשמייצאים נתונים באמצעות מסוף Google Cloud .
כשמייצאים טבלה בפורמט 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 בזמן שמשימת החילוץ פועלת לא ייכללו במשימת החילוץ הזו. כדי לייצא את הנתונים החדשים, צריך ליצור משימת חילוץ חדשה.
מספר הדור של Cloud Storage עשוי להשתנות פעם אחת או יותר במהלך תהליך הייצוא. אם אתם מריצים משימה על האובייקט החדש ב-Cloud Storage מיד אחרי הייצוא, אל תציינו מספר דור.

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

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

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

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

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

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

כל אחד מהתפקידים הבאים שמוגדרים מראש ב-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 או ספריות הלקוח

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

המסוף

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

לדף של BigQuery
בחלונית השמאלית, לוחצים על Explorer:

אם החלונית הימנית לא מוצגת, לוחצים על הרחבת החלונית הימנית כדי לפתוח אותה.
בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ואז על מערך הנתונים.
לוחצים על סקירה כללית > טבלאות ובוחרים טבלה.
בחלונית הפרטים, לוחצים על סמל ההעלאה ייצוא / סנכרון > Cloud Storage.
בתיבת הדו-שיח Export to Google Cloud Storage:
- בשדה GCS Location, מחפשים את הקטגוריה, התיקייה או הקובץ שאליהם רוצים לייצא את הנתונים.
- בקטע Export format, בוחרים את הפורמט של הנתונים לייצוא: CSV,‏ JSON (מופרד בשורה חדשה),‏ Avro או Parquet.
- בשדה Compression, בוחרים פורמט דחיסה או בוחרים באפשרות None כדי לא לדחוס את הקובץ.
לוחצים על שמירה כדי לייצא את הטבלה.

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

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

SQL

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

נכנסים לדף BigQuery במסוף Google Cloud .

כניסה ל-BigQuery

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

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

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

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

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

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

יוצרים משימת חילוץ שמפנה לנתוני המקור ב-BigQuery וליעד ב-Cloud Storage.
מציינים את טבלת המקור באמצעות אובייקט ההגדרות sourceTable שמכיל את מזהה הפרויקט, מזהה קבוצת הנתונים ומזהה הטבלה.
המאפיין destination URI(s) צריך להיות מלא, בפורמט gs://bucket/filename.ext. כל URI יכול להכיל תו כללי לחיפוש אחד ('*'), והוא חייב להופיע אחרי שם הקטגוריה.
מציינים את פורמט הנתונים באמצעות הגדרת המאפיין configuration.extract.destinationFormat. לדוגמה, כדי לייצא קובץ JSON, מגדירים את המאפיין הזה לערך NEWLINE_DELIMITED_JSON.
כדי לבדוק את סטטוס המשימה, מפעילים את 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 במדריך למתחילים של 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 :

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

לדף של BigQuery
לוחצים על שאילתת SQL.
מזינים שאילתת GoogleSQL תקינה באזור הטקסט של עורך השאילתות.
לוחצים על Run.
כשהתוצאות מוצגות, לוחצים על Save results > Cloud Storage.
בתיבת הדו-שיח Export to Google Cloud Storage:
- בשדה GCS Location, מחפשים את הקטגוריה, התיקייה או הקובץ שאליהם רוצים לייצא את הנתונים.
- בקטע Export format, בוחרים את הפורמט של הנתונים לייצוא: CSV,‏ JSON (מופרד בשורה חדשה),‏ Avro או Parquet.
- בשדה Compression, בוחרים פורמט דחיסה או בוחרים באפשרות None כדי לא לדחוס את הקובץ.
לוחצים על שמירה כדי לייצא את תוצאות השאילתה.

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

דרכים אחרות לייצא נתונים

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

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

פרטי הייצוא של Avro

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

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

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

אי אפשר להשתמש בפורמט 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)`
Numeric(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)`
JSON	`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 מופיע במאמר הגדרת עמודות בתצוגת עץ ועמודות חוזרות.

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

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

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

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

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

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

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

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

`destinationUris` אפשרויות
‫URI יחיד	אם אתם מייצאים נתוני טבלה בנפח של 1GB או פחות, השתמשו ב-URI יחיד. זו האפשרות הנפוצה ביותר, כי בדרך כלל הנתונים שמייצאים קטנים מהערך המקסימלי של 1GB. האפשרות הזו לא נתמכת בהצהרה `EXPORT DATA`. צריך להשתמש ב-URI אחד עם תו כללי לחיפוש. הגדרת הנכס: `['gs://my-bucket/file-name.json']` יוצר: gs://my-bucket/file-name.json
‫URI עם תו כללי אחד לחיפוש	אפשר להשתמש בתו כללי אחד רק ברכיב שם הקובץ של ה-URI. אם אתם חושבים שהנתונים שאתם מייצאים יהיו גדולים מהערך המקסימלי של 1GB, השתמשו ב-URI עם תו כללי לחיפוש. ‫BigQuery מפצל את הנתונים למספר קבצים על סמך התבנית שסופקה. הגודל של הקבצים המיוצאים משתנה. אם השאילתה כוללת סעיף `ORDER BY`, קבוצת התוצאות שממוינת באופן גלובלי מופצת ברצף בין הקבצים שנוצרו. הגדרת הנכס: `['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 ...

destinationUris אפשרויות

‫URI יחיד

אם אתם מייצאים נתוני טבלה בנפח של 1GB או פחות, השתמשו ב-URI יחיד. זו האפשרות הנפוצה ביותר, כי בדרך כלל הנתונים שמייצאים קטנים מהערך המקסימלי של 1GB. האפשרות הזו לא נתמכת בהצהרה EXPORT DATA. צריך להשתמש ב-URI אחד עם תו כללי לחיפוש.

הגדרת הנכס:

['gs://my-bucket/file-name.json']

יוצר:

gs://my-bucket/file-name.json

‫URI עם תו כללי אחד לחיפוש

אפשר להשתמש בתו כללי אחד רק ברכיב שם הקובץ של ה-URI.

אם אתם חושבים שהנתונים שאתם מייצאים יהיו גדולים מהערך המקסימלי של 1GB, השתמשו ב-URI עם תו כללי לחיפוש. ‫BigQuery מפצל את הנתונים למספר קבצים על סמך התבנית שסופקה. הגודל של הקבצים המיוצאים משתנה. אם השאילתה כוללת סעיף `ORDER BY`, קבוצת התוצאות שממוינת באופן גלובלי מופצת ברצף בין הקבצים שנוצרו.

הגדרת הנכס:

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

קובעים את מספר המחיצות שצריך, ששווה לגודל הכולל של הנתונים חלקי גודל הקובץ שנבחר לייצוא. לדוגמה, אם יש לכם נתונים בנפח של 8,000MB ואתם רוצים שכל קובץ שייצאתם יהיה בנפח של כ-20MB, אתם צריכים 400 מחיצות.
יוצרים טבלה חדשה שמחולקת למחיצות ולאשכולות לפי עמודה חדשה שנוצרה באופן אקראי בשם 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
);
```
לכל מספר שלם i בין 0 ל-n-1, מריצים הצהרת EXPORT DATA בשאילתה הבאה:
```
SELECT * EXCEPT(export_id)
FROM my_dataset.processed_table
WHERE export_id = i;
```

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

Go

כדי לבצע אימות ב-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

כדי לבצע אימות ב-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

כדי לבצע אימות ב-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

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

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

אם אתם משתמשים בשורת החיפוש כדי למצוא את הדף הזה, בחרו בתוצאה שכותרת המשנה שלה היא Monitoring.
בדף Alerting, לוחצים על Create Policy.
בקטע Policy configuration mode, בוחרים באפשרות Code editor (MQL or PromQL).

בעורך השאילתות של 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

אם האפשרות Auto-run לא מופעלת, לוחצים על Run Query.

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

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

הודעת שגיאה

Your usage exceeded quota for ExtractBytesPerDay

האבחון

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

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

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

לחלופין, אפשר לשלוח שאילתה אל 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 שצורכות יותר מ-100GB שעובדו בשבעת הימים האחרונים.

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.

הייצוא נכשל בגלל שגיאה בסכימה בתצוגת עץ

השגיאה הזו מתרחשת כשמנסים לייצא טבלה שמכילה שדות מקוננים או שדות חוזרים, כמו סוגי הנתונים STRUCT או ARRAY, לפורמט קובץ שטוח כמו CSV או JSON מופרד בתו מפריד של שורה חדשה.

הודעת שגיאה

Failed to export: Operation cannot be performed on a nested schema. Field: [COLUMN_NAME]

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

רזולוציה

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

בדוגמה הבאה מוצגת סכימה עם שדות STRUCT בתצוגת עץ ושאילתה שמשטחת אותם לצורך ייצוא. בדוגמה הזו, שאילתת הייצוא נכשלת בגלל השדות בתצוגת עץ בעמודה user_details. אתם יכולים להשתמש בתיקון המוצע כדי לשטח את מבנה הקובץ לשתי עמודות, user_details.name ו-user_details.email.

  -- Schema example:
  root
    ├── id (INTEGER)
    ├── user_details (RECORD / STRUCT, NULLABLE)
    │   ├── name (STRING)
    │   └── email (STRING)
    └── created_at (TIMESTAMP)

  -- Export query:
  SELECT * FROM my_dataset.my_table;

  -- Suggested fix:
  SELECT
      id,
      user_details.name AS user_name,
      user_details.email AS user_email,
      created_at
  FROM
      my_dataset.my_table;

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

  -- Schema example:
  root
    ├── order_id (STRING)
    ├── customer_name (STRING)
    └── line_items (REPEATED / ARRAY of RECORD/STRUCT, NULLABLE)
        ├── product_id (STRING)
        └── quantity (INTEGER)


  -- Export query:
  SELECT * FROM my_dataset.my_orders_table;

  -- Suggested fix:
  SELECT
      t.order_id,
      t.customer_name,
      item.product_id,
      item.quantity
  FROM
      my_dataset.my_orders_table AS t
  LEFT JOIN
      UNNEST(t.line_items) AS item
  ;

לחלופין, אפשר להשתמש ב-ARRAY_TO_STRING() אם צריך לייצג רק מערך, כמו ARRAY<STRING>, כעמודת מחרוזת אחת בקובץ ה-CSV.

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

  -- Schema example:
  root
    ├── user_id (STRING)
    └── interests (REPEATED / ARRAY of STRING, NULLABLE)

  -- Suggested fix:
  SELECT
      user_id,
      ARRAY_TO_STRING(interests, ', ') AS user_interests
  FROM
      my_dataset.my_users_table;

תמחור

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

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

אבטחת טבלאות

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

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

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