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

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

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

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

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

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

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

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

ייצוא נתונים

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

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

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

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

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

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

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

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

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

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

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}.");
    }
}

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
}

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

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

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

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

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 במסוף Cloud de Confiance :

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

   לדף BigQuery

2. לוחצים על add_box שאילתת 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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
}

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

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

# 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. נכנסים לדף notifications Alerting במסוף Cloud de Confiance :

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

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

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

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