從本機資料來源載入資料

您可以使用 GCP 主控台、BigQuery 網頁版 UI、CLI、API,或用戶端程式庫,從可讀取的資料來源 (例如您的本機電腦) 載入資料。當您使用 BigQuery 網頁版 UI 或 CLI 載入資料時,系統會自動建立載入工作。

如需載入本機 CSV 檔案的教學課程,請參閱:

限制

從本機資料來源載入資料時,會受到以下限制:

  • 從本機資料來源載入檔案時,無法使用萬用字元和以逗號分隔的清單。檔案必須個別載入。
  • 使用傳統 BigQuery 網頁版 UI 時,只能從本機資料來源載入 10 MB 以下的檔案,且檔案的資料列數量不得超過 16,000 個。

從本機資料來源載入資料

從本機資料來源載入資料:

主控台

  1. 在 GCP 主控台中開啟 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

  2. 在導覽面板的「Resources」(資源) 區段,展開您的專案並選取資料集。

  3. 在視窗右側的詳細資料面板中,按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。

    建立資料表

  4. 在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中:

    • 在「Create table from」(使用下列資料建立資料表) 部分,選取 [Upload] (上傳)。

      上傳資料表

    • 在「Select file」(選取檔案) 下方,按一下 [Browse] (瀏覽)

      瀏覽檔案

    • 瀏覽至檔案,然後點選 [Open] (開啟)。請注意,本機檔案不支援萬用字元和以半形逗號分隔的清單。

    • 在「File format」(檔案格式) 部分,選取 [CSV]、[JSON (newline delimited)] (JSON (以換行符號分隔))、[Avro]、[Parquet] 或 [ORC]

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中:

    • 在「Dataset name」(資料集名稱) 部分選擇適當的資料集。

      查看資料集

    • 在「Table name」(資料表名稱) 欄位中,輸入您在 BigQuery 中建立資料表時使用的名稱。

    • 確認已將「Table type」(資料表類型) 設為 [Native table] (原生資料表)

  6. 在「Schema」(結構定義) 區段中,輸入結構定義

    • 如果是 CSV 與 JSON 檔案,您可以勾選 [Auto-detect] (自動偵測) 選項來啟用結構定義自動偵測功能。系統會使用來源資料,從 Avro、Parquet 和 ORC 檔案中擷取結構定義資訊。

    • 您也可以使用下列任一種方式,手動輸入結構定義資訊:

      • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

      • 使用 [Add Field] (新增欄位) 手動輸入結構定義

  7. 在「Advanced options」(進階選項) 區段中選取適合的項目,然後按一下 [Create Table] (建立資料表)。如要瞭解可用選項,請參閱 CSV 選項JSON 選項

傳統版 UI

  1. 前往 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

  2. 在導覽面板中,將滑鼠游標懸停在某個資料集上,點選向下箭號圖示 向下箭號圖示圖片,然後按一下 [Create new table] (建立新資料表)。載入資料的程序與建立空白資料表的程序相同。

  3. 在「Create Table」頁面的「Source Data」區段中:

    • 針對「Location」(位置),選取 [File upload] (檔案上傳),按一下 [Choose file] (選擇檔案),瀏覽到檔案,並點選 [Open] (開啟)。請注意,本機檔案不支援萬用字元和以半形逗號分隔的清單。
    • 在「File format」(檔案格式) 部分選取 [(CSV)]、[JSON (newline delimited)] (JSON (以換行符號分隔))、[Avro]、[Parquet] 或 [ORC]
  4. 在「Create Table」(建立表格) 頁面的「Destination Table」(目的地表格) 區段中:

    • 在「Table name」(表格名稱) 部分選擇適當的資料集,然後在表格名稱欄位中,輸入要在 BigQuery 中建立的表格名稱。
    • 確認已將「Table type」(資料表類型) 設為 [Native table] (原生資料表)
  5. 在「Schema」(結構定義) 區段中,輸入結構定義

    • 如果是 CSV 與 JSON 檔案,您可以勾選 [Auto-detect] (自動偵測) 選項來啟用結構定義自動偵測功能。系統會使用來源資料,從 Avro、Parquet 和 ORC 檔案中擷取結構定義資訊。

      自動偵測連結

    • 您也可以使用下列任一種方式,手動輸入結構定義資訊:

      • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

        以 JSON 陣列的形式新增結構定義

      • 使用 [Add Field] (新增欄位) 手動輸入結構定義:

        使用新增欄位新增結構定義

  6. 在「Options」區段中選取適合的項目,然後按一下 [Create Table]。如要瞭解可用選項,請參閱 CSV 選項JSON 選項

CLI

使用 bq load 指令,指定 source_format,並將路徑包含到本機檔案中。提供 --location 標記,並將值設為您的位置

如要載入非預設專案中的資料,請以下列格式將專案 ID 新增至資料集:[PROJECT_ID]:[DATASET]

bq --location=[LOCATION] load --source_format=[FORMAT] [PROJECT_ID]:[DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

其中:

  • [LOCATION] 是您的位置。如果資料位於 USEU 多地區位置,則 --location 是選用標記。例如,如果您在東京地區使用 BigQuery,請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案來設定位置的預設值。
  • [FORMAT]CSVAVROPARQUETORCNEWLINE_DELIMITED_JSON
  • [PROJECT_ID] 是您的專案 ID。
  • [DATASET] 是現有資料集。
  • [TABLE] 是您要載入資料的目標資料表名稱。
  • [PATH_TO_SOURCE] 是本機檔案的路徑。
  • [SCHEMA] 是有效的結構定義。結構定義可以是本機 JSON 檔案,或以內嵌的方式在指令中輸入。您也可以改用 --autodetect 標記而不提供結構定義。

此外,您還可以為選項新增標記,藉此控制 BigQuery 剖析資料的方式。例如,您可以使用 --skip_leading_rows 標記忽略 CSV 檔案中的標題列。詳情請參閱 CSV 選項JSON 選項

範例:

  • 下列指令會將以換行符號分隔的 JSON 檔案 (mydata.json) 從本機載入預設專案中 mydataset 裡名稱為 mytable 的資料表。結構定義是透過名稱為 myschema.json 的本機結構定義檔案定義。mydataset 會在 US 多地區位置中建立。

    bq --location=US load --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable ./mydata.json ./myschema.json
    
  • 下列指令會將 CSV 檔案 (mydata.csv) 從本機載入 myotherprojectmydataset 裡名稱為 mytable 的資料表。結構定義是以內嵌的方式定義 (格式為 [FIELD]:[DATA_TYPE], [FIELD]:[DATA_TYPE])。mydataset 是建立在 asia-northeast1 地區中。

    bq --location=asia-northeast1 load --source_format=CSV myotherproject:mydataset.mytable ./mydata.csv qtr:STRING,sales:FLOAT,year:STRING
    

    附註:在指令列中指定結構定義時,您無法加入 RECORD (STRUCT) 類型和欄位說明,也不能指定欄位模式。所有欄位模式均預設為 NULLABLE。如要加入欄位說明、模式和 RECORD 類型,請改為提供 JSON 結構定義檔案

  • 下列指令會將 CSV 檔案 (mydata.csv) 從本機載入預設專案中 mydataset 裡名稱為 mytable 的資料表。結構定義是透過結構定義自動偵測功能所定義。 mydataset 會在 EU 多地區位置中建立。

    bq --location=EU load --autodetect --source_format=CSV mydataset.mytable ./mydata.csv
    

C#

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 C# 設定說明進行操作。詳情請參閱 BigQuery C# API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請使用 JobCreationOptions 基本類別中適當格式的更新選項類別,而不是使用 UploadCsvOptions

using Google.Cloud.BigQuery.V2;
using System;
using System.IO;

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job.PollUntilCompleted();  // Waits for the job to complete.
            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

Go

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 NewReaderSourceDataFormat 屬性設為適當的格式。

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
f, err := os.Open(filename)
if err != nil {
	return err
}
source := bigquery.NewReaderSource(f)
source.AutoDetect = true   // Allow BigQuery to determine schema.
source.SkipLeadingRows = 1 // CSV has a single header line.

loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Java

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 FormatOptions 設為適當的格式。

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 load 函式的 metadata 參數設為適當格式。

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');

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

async function loadLocalFile() {
  // Imports a local file into a table.

  // Create a client
  const bigqueryClient = new BigQuery();

  // Load data from a local file into the table
  const [job] = await bigqueryClient
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

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

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

PHP

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 PHP 設定說明進行操作。詳情請參閱 BigQuery PHP API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 sourceFormat 設為適當的格式。

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';
// $tableId    = 'The BigQuery table ID';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 LoadJobConfig.source_format 屬性設為適當的格式。

# from google.cloud import bigquery
# client = bigquery.Client()
# filename = '/path/to/file.csv'
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1
job_config.autodetect = True

with open(filename, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.

print("Loaded {} rows into {}:{}.".format(job.output_rows, dataset_id, table_id))

Ruby

在試用這個範例程式之前,請至 BigQuery 快速入門導覽課程:使用用戶端程式庫,按照 Ruby 設定說明進行操作。詳情請參閱 BigQuery Ruby API 參考說明文件

下列程式碼示範如何將本機 CSV 檔案載入到新的 BigQuery 資料表。如要載入另一種格式的本機檔案,請將 Table#load_job 方法的 format 參數設為適當的格式。

require "google/cloud/bigquery"

def load_from_file(
    dataset_id = "your_dataset_id",
    file_path = "path/to/file.csv"
  )
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
    # Must match the destination dataset location.
    config.location     = "US"
  end
  load_job.wait_until_done!  # Waits for table load to complete.

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows into #{table.id}"
end

使用本機檔案附加或覆寫資料表

如果要在資料表中載入額外資料,您可以指定來源檔案或附加查詢結果。如果資料的結構定義與目標資料表或分區的結構定義不符,您可以在附加或覆寫時更新目標資料表或分區的結構定義。

如果您在附加資料時更新結構定義,BigQuery 可讓您:

  • 新增欄位
  • REQUIRED 欄位放寬為 NULLABLE

如果是覆寫資料表,系統一律會覆寫結構定義。覆寫表格時,結構定義更新不受限制。

在主控台或傳統版 BigQuery 網頁版 UI 中,使用 [Write preference] (寫入偏好設定) 選項來指定從來源檔案或從查詢結果載入資料時採取的動作。CLI 與 API 提供下列選項:

主控台選項 傳統版 UI 選項 CLI 標記 BigQuery API 屬性 說明
空白時寫入 空白時寫入 WRITE_EMPTY 資料表空白時才會寫入資料。
附加到表格中 附加到表格中 --noreplace--replace=false;如果未指定 --[no]replace,預設動作為附加 WRITE_APPEND (預設值) 將資料附加至資料表尾端。
覆寫資料表 覆寫資料表 --replace--replace=true WRITE_TRUNCATE 清除資料表中所有現有的資料後再寫入新資料。

如要從本機檔案載入 CSV、JSON、Avro、Parquet 或 ORC 資料並附加到 (或覆寫) BigQuery 資料表:

主控台

  1. 在 GCP 主控台中開啟 BigQuery 網頁版 UI。
    前往 BigQuery 網頁版 UI

  2. 在導覽面板的「Resources」(資源) 區段,展開您的專案並選取資料集。

  3. 在視窗右側的詳細資料面板中,按一下 [Create table] (建立資料表)。載入資料的程序與建立空白資料表的程序相同。

    建立資料表

  4. 在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中:

    • 在「Create table from」(使用下列資料建立資料表) 部分,選取 [Upload] (上傳)。

      上傳資料表

    • 在「Select file」(選取檔案) 下方,按一下 [Browse] (瀏覽)

      瀏覽檔案

    • 瀏覽至檔案,然後點選 [Open] (開啟)。請注意,本機檔案不支援萬用字元和以半形逗號分隔的清單。

    • 在「File format」(檔案格式) 部分,選取 [CSV]、[JSON (newline delimited)] (JSON (以換行符號分隔))、[Avro]、[Parquet] 或 [ORC]

  5. 在「Create table」(建立資料表) 頁面的「Destination」(目的地) 區段中:

    • 在「Dataset name」(資料集名稱) 部分選擇適當的資料集。

      選取資料集

    • 在「Table name」(資料表名稱) 欄位中,輸入您在 BigQuery 中建立資料表時使用的名稱。

    • 確認已將「Table type」(資料表類型) 設為 [Native table] (原生資料表)

  6. 在「Schema」(結構定義) 區段中,輸入結構定義

    • 如果是 CSV 與 JSON 檔案,您可以勾選 [Auto-detect] (自動偵測) 選項來啟用結構定義自動偵測功能。系統會使用來源資料,從 Avro、Parquet 和 ORC 檔案中擷取結構定義資訊。

    • 您也可以使用下列任一種方式,手動輸入結構定義資訊:

      • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

      • 使用 [Add Field] (新增欄位) 手動輸入結構定義

  7. 在「Advance options」(進階選項) 區段的「Write preference」(寫入偏好設定),選擇 [Write if empty] (空白時寫入)、[Append to table] (附加到表格) 或 [Overwrite table] (覆寫資料表)

  8. 按一下 [Create Table] (建立資料表)

傳統版 UI

  1. 在「Create Table」(建立資料表) 頁面的「Source Data」(來源資料) 部分中:
    • 針對「Location」(位置),選取 [File upload] (檔案上傳),按一下 [Choose file] (選擇檔案),瀏覽到檔案,並點選 [Open] (開啟)。請注意,本機檔案不支援萬用字元和以半形逗號分隔的清單。
    • 在「File format」(檔案格式) 部分選取 [(CSV)]、[JSON (newline delimited)] (JSON (以換行符號分隔))、[Avro]、[Parquet] 或 [ORC]
  2. 在「Create Table」(建立表格) 頁面的「Destination Table」(目的地表格) 區段中:
    • 在「Table name」(建立表格) 部分選擇適當的資料集,然後在表格名稱欄位中輸入要附加或覆寫的表格名稱。
    • 確認已將「Table type」(資料表類型) 設為 [Native table] (原生資料表)
  3. 在「Schema」(結構定義) 區段中,輸入結構定義。如要更新結構定義,您可以新增欄位或將欄位從 REQUIRED 變更 (放寬) 為 NULLABLE

    • 如為 JSON 檔案,您可以勾選 [Auto-detect] (自動偵測) 選項來啟用結構定義自動偵測功能。

      自動偵測連結

    • 您也可以使用下列任一種方式,手動輸入結構定義資訊:

      • 按一下 [Edit as text] (以文字形式編輯),然後以 JSON 陣列的形式輸入資料表結構定義:

        以 JSON 陣列的形式新增結構定義

      • 使用 [Add Field] (新增欄位) 手動輸入結構定義:

        使用新增欄位新增結構定義

  4. 在「Options」區段的「Write preference」中,選擇 [Write if empty]、[Append to table] 或 [Overwrite table]

    使用新增欄位新增結構定義

  5. 按一下 [Create Table] (建立資料表)

指令列

輸入 bq load 指令並搭配使用 --replace 標記覆寫資料表。使用 --noreplace 標記可將資料附加至資料表。若未指定任何標記,預設動作為附加資料。提供 --location 標記,並將值設為您的位置

在資料表中附加或覆寫資料時,您可以使用 --schema_update_option 標記,將目標資料表的結構定義更新為新資料的結構定義。下列選項可搭配 --schema_update_option 標記使用:

  • ALLOW_FIELD_ADDITION:新增欄位至結構定義;新欄位不得為 REQUIRED
  • ALLOW_FIELD_RELAXATION:將必填欄位放寬為可以為空值;重複此選項可指定值清單
bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE] [SCHEMA]

其中:

  • [LOCATION] 是您的位置。如果資料位於 USEU 多地區位置,則 --location 是選用標記。例如,如果您在東京地區使用 BigQuery,請將標記的值設為 asia-northeast1。您可以使用 .bigqueryrc 檔案來設定位置的預設值。
  • [DATASET] 是現有資料集。
  • [TABLE] 是您要載入資料的目標資料表名稱。
  • [PATH_TO_SOURCE] 是本機檔案的路徑。請注意,本機檔案不支援萬用字元和以半形逗號分隔的清單。
  • [SCHEMA] 是有效的結構定義。結構定義可以是本機 JSON 檔案,或以內嵌的方式在指令中輸入。您也可以改用 --autodetect 標記而不提供結構定義。

此外,您還可以為 JSON 選項CSV 選項新增標記,藉此控制 BigQuery 剖析資料的方式。

範例:

  • 下列指令會載入 mydata.json 中的資料,並覆寫 mydataset 中名為 mytable 的資料表。結構定義是透過結構定義自動偵測功能定義。mydataset 會在 US 多地區位置中建立。

    bq --location=US load --autodetect --replace --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable ./mydata.json
    
  • 下列指令會載入 mydata.json 中的資料,並將資料附加至 mydataset 中名為 mytable 的資料表。結構定義是透過 JSON 結構定義檔案 myschema.json 定義。mydataset 會在 US 多地區位置中建立。

    bq --location=US load --autodetect --noreplace --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable ./mydata.json ./myschema.json
    
  • 下列指令會載入 mydata.json 中的資料,並將資料附加至 mydataset 中名為 mytable 的資料表。此指令使用了名為 myschema.json 的本機 JSON 結構定義檔案。結構定義包含目標資料表沒有的新欄位。mydataset 會在 EU 多地區位置中建立。

    bq --location=EU load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable ./mydata.json ./myschema.json
    
  • 下列指令會載入 mydata.csv 中的資料,並將資料附加至 mydataset 中名為 mytable 的資料表。此指令使用了名為 myschema.json 的本機 JSON 結構定義檔案。結構定義會將兩個 REQUIRED 欄位變更 (放寬) 為 NULLABLEmydataset 會在 asia-northeast1 地區中建立。

    bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable ./mydata.csv ./myschema.json
    

媒體上傳功能可讓 Google BigQuery API 將資料儲存於雲端,且可提供資料給伺服器使用。使用者想要上傳的資料可能有相片、影片、PDF 檔案、ZIP 檔案或其他任何類型的資料。

上傳選項

Google BigQuery API 可讓您上傳特定類型的二進位資料或媒體。您可以上傳之資料的特性可針對支援媒體上傳的任何方法在參考頁面上指定:

  • 「Maximum upload file size」:您可以使用這個方法儲存的資料量上限。
  • 「Accepted media MIME types」:您可以使用這個方法儲存的二進位資料類型。

您可以透過下列任何一種方式提出上傳要求。透過 uploadType 要求參數指定您要使用的方法。

  • 多部分上傳作業uploadType=multipart。適用於快速移轉少量的檔案與中繼資料;與說明檔案的中繼資料一起移轉檔案,全都在一次要求內完成。
  • 支援續傳的上傳作業uploadType=resumable。適用於可靠的移轉,對於較大檔案特別重要。透過這個方法,您可以使用工作階段啟動要求,其中可以選擇是否包含中繼資料。對於大多數應用程式而言,這都是一種不錯的策略,因為每次上傳只需要增加額外一次 HTTP 要求的成本,這也適用於較小的檔案。

當您上傳媒體時,您會使用特殊 URI。事實上,支援媒體上傳的方法有兩個 URI 端點:

  • /upload URI,適用於媒體。 上傳端點的格式是帶有「/upload」前置字串的標準資源 URI。移轉媒體資料本身時,請使用這個 URI。範例:POST /upload/bigquery/v2/projects/<projectId>/jobs
  • 標準資源 URI,適用於中繼資料。 如果資源中包含任何資料欄位,會使用這些欄位來儲存說明上傳檔案的中繼資料。建立或更新中繼資料值時,您可以使用這個 URI。範例:POST /bigquery/v2/projects/<projectId>/jobs

多部分上傳作業

如果您要與資料一起上傳中繼資料,可以提出一次 multipart/related 要求。如果您要傳送的資料小到足以在連線失敗時再完整上傳一次,這就是個不錯的選擇。

如要使用多部分上傳作業,請向方法的 /upload URI 發出 POST 要求,並新增查詢參數 uploadType=multipart,例如:

POST https://www.googleapis.com/upload/bigquery/v2/projects/<projectId>/jobs?uploadType=multipart

提出多部分上傳要求時使用的頂層 HTTP 標頭包括:

  • Content-Type。設定為多部分/相關並包含您要用來識別要求部分的邊界字串。
  • Content-Length。設定為要求本文中的位元組總數。要求的媒體部分必須小於針對這個方法指定的檔案大小上限。

要求主體的格式為 multipart/related 內容類型 [RFC2387],且剛好包含兩個部分。部分由邊界字串識別,最終邊界字串後跟兩個連字號。

多部分要求的每個部分都需要一個額外的 Content-Type 標頭:

  1. 中繼資料部分:必須先寫,且 Content-Type 必須符合其中一種接受的中繼資料格式。
  2. 媒體部分:必須第二個寫,且 Content-Type 必須符合該方法的其中一種可接受媒體 MIME 類型。

如要瞭解每個方法的可接受媒體 MIME 類型清單,以及上傳檔案的大小限制,請參閱 API 參考資料

附註:如果只要建立或更新中繼資料部分,而不上傳相關聯的資料,則只須傳送 POSTPUT 要求給標準資源端點即可:https://www.googleapis.com/bigquery/v2/projects/<projectId>/jobs

範例:多部分上傳作業

以下範例顯示 Google BigQuery API 的多部分上傳要求。

POST /upload/bigquery/v2/projects/<projectId>/jobs?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

--foo_bar_baz
Content-Type: */*

CSV, JSON, AVRO, PARQUET, or ORC data
--foo_bar_baz--

如果要求成功,伺服器會傳回 HTTP 200 OK 狀態碼與任何中繼資料:

HTTP/1.1 200
Content-Type: application/json

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

支援續傳的上傳作業

如要更可靠地上傳資料檔案,您可以使用支援續傳的上傳通訊協定。這個通訊協定可讓您在通訊問題中斷資料流動過程後繼續上傳作業。如果您要移轉大型檔案,而發生網路中斷或其他某些傳輸問題的可能性很高 (例如當從行動用戶端應用程式上傳時),這種方法特別有用。這也可以在發生網路問題的情況下減少頻寬用量,因為您不需要從頭開始上傳大型檔案。

使用支援續傳的上傳作業的步驟包括:

  1. 啟動可續傳工作階段。對包含中繼資料的上傳 URI 提出初始要求 (若有)。
  2. 儲存可續傳工作階段 URI。儲存在初始要求回應中傳回的工作階段 URI;您會在這個工作階段的剩餘要求中用到它。
  3. 上傳檔案。將媒體檔案傳送到可續傳工作階段 URI。

此外,使用支援續傳的上傳作業的應用程式需要擁有續傳中斷上傳作業的代碼。如果上傳作業中斷,請找出已成功接收多少資料,然後從那一點開始續傳。

注意:上傳 URI 會在一週後失效。

步驟 1:啟動可續傳工作階段

如要啟動可續傳上傳作業,請向方法的 /upload URI 發出 POST 要求,並新增查詢參數 uploadType=resumable,例如:

POST https://www.googleapis.com/upload/bigquery/v2/projects/<projectId>/jobs?uploadType=resumable

針對這個啟動要求,本文為空白或其中只包含中繼資料;您會移轉要在後續要求中上傳之檔案的實際內容。

搭配初始要求使用下列 HTTP 標頭:

  • X-Upload-Content-Type:設定為要在後續要求中移轉的上傳資料媒體 MIME 類型。
  • X-Upload-Content-Length:設定為要在後續要求中移轉的上傳資料位元組數。如果提出這項要求時無法得知長度,您可以省略這個標頭。
  • 如要提供中繼資料,則使用 Content-Type:根據中繼資料的資料類型進行設定。
  • Content-Length:設定為這項初始要求的主體中提供的位元組數。如果您要使用區塊傳輸編碼,就不需要使用這個標頭。

如要瞭解每個方法的可接受媒體 MIME 類型清單,以及上傳檔案的大小限制,請參閱 API 參考資料

範例:可續傳工作階段啟動要求

以下範例顯示如何針對 Google BigQuery API 啟動可續傳工作階段。

POST /upload/bigquery/v2/projects/<projectId>/jobs?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: */*
X-Upload-Content-Length: 2000000

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

附註:針對沒有中繼資料的初始可續傳更新要求,請將要求的主體保留空白,並將 Content-Length 標頭設為 0

下一節將說明如何處理回應。

步驟 2:儲存可續傳工作階段 URI

如果工作階段啟動要求成功,API 伺服器會回應 200 OK HTTP 狀態碼。此外,API 伺服器還會提供指定可續傳工作階段 URI 的 Location 標頭。如以下範例所示,Location 標頭包含 upload_id 查詢參數部分,可提供不重複的上傳 ID 供這個工作階段使用。

範例:可續傳工作階段啟動回應

以下是對步驟 1 中要求的回應:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/bigquery/v2/projects/<projectId>/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

如以上範例回應所示,Location 標頭的值是您將做為 HTTP 端點使用來執行實際檔案上傳或查詢上傳狀態的工作階段 URI。

請複製並儲存工作階段 URI,以便您能夠在後續要求中使用它。

步驟 3:上傳檔案

如要上傳檔案,請傳送 PUT 要求給您在上一個步驟中取得的上傳 URI。上傳要求的格式如下:

PUT session_uri

要在提出可續傳檔案上傳要求時使用的 HTTP 標頭包含 Content-Length。將它設定為您要在這個要求中上傳的位元組數,這通常是上傳檔案大小。

範例:可續傳檔案上傳要求

以下是在目前範例中,上傳完整的 2,000,000 位元組 CSV、JSON、AVRO 或 PARQUET 檔案的可續傳要求。

PUT https://www.googleapis.com/upload/bigquery/v2/projects/<projectId>/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: */*

bytes 0-1999999

如果要求成功,伺服器會回應 HTTP 201 Created,加上與這個資源相關聯的所有中繼資料。如果可續傳工作階段的初始要求曾經是 PUT,如要更新現有資源,成功的回應就會是 200 OK,加上與這個資源相關聯的所有中繼資料。

如果上傳要求中斷,或者您從伺服器收到 HTTP 503 Service Unavailable 或任何其他 5xx 回應,請按照續傳中斷上傳作業一節所述的程序執行。


將檔案切割為片段後上傳

透過可續傳的上傳作業,您可將檔案切割為片段,然後傳送一系列要求來依序上傳每個片段。這不是偏好的方法,因為有一些效能成本與其他要求相關聯,而這通常不需要這個方法。但是,您可能需要使用切割片段的方式來減少在任何單一要求中移轉的資料量。當個別要求有固定的時間限制時,這會很有幫助,對於 Google App Engine 要求的某些類別而言也是如此。它也可以讓您執行一些工作,例如為預設不支援顯示上傳進度的舊版瀏覽器提供上傳進度指示。


續傳中斷上傳作業

如果上傳要求在收到回應之前終止,或者您從伺服器收到 HTTP 503 Service Unavailable 回應,您必須續傳中斷的上傳作業。操作說明如下:

  1. 要求狀態: 向上傳 URI 發出空白的 PUT 要求,查詢上傳作業目前的狀態。針對這項要求,HTTP 標頭應包含指出檔案中目前位置不明的 Content-Range 標頭。比方說,如果您的檔案總長度是 2,000,000,請將 Content-Range 設為 */2000000。如果您不知道檔案的完整大小,請將 Content-Range 設為 */*

    附註:您可以要求區塊之間的狀態,而不只是在上傳中斷時才能要求。例如,當您要讓舊版瀏覽器顯示上傳進度時,這項功能就非常實用。

  2. 取得已上傳的位元組數: 處理狀態查詢的回應。伺服器會在它的回應中使用 Range 標頭來指定到目前為止已經收到哪些位元組。例如,0-299999Range 標頭就指出已經收到檔案的前 300,000 個位元組。
  3. 上傳剩餘資料。 最後,您已經知道要在哪裡續傳要求,請傳送剩餘的資料或目前區塊。請注意,無論是哪一種情況,您都需要將剩餘資料當成單獨的區塊處理,這樣您需要在續傳上傳作業時傳送 Content-Range 標頭。
範例:續傳中斷上傳作業

1) 要求上傳狀態。

以下要求使用 Content-Range 標頭指出 2,000,000 位元組檔案中的目前位置不明。

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) 擷取到目前為止從回應上傳的位元組數。

伺服器的回應會使用 Range 標頭指出到目前為止已經收到檔案的前 43 個位元組。使用 Range 標頭的上限值來確定要在哪裡開始支援續傳的上傳作業。

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

附註:如果上傳作業已完成,狀態回應可能是 201 Created200 OK。如果連線在上傳了所有位元組之後,以及用戶端從伺服器收到回應之前中斷,就可能發生這種情形。

3) 從上次離開的位置續傳上傳作業。

以下要求透過傳送檔案的剩餘位元組 (從位元組 43 開始) 續傳上傳作業。

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

最佳做法

上傳媒體時,瞭解與錯誤處理相關的某些最佳做法很有幫助。

  • 續傳或重試因連線中斷或任何 5xx 錯誤導致失敗的上傳,這些錯誤包括:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • 如果在續傳或重試上傳要求時傳回任何 5xx 伺服器錯誤,請使用指數輪詢策略。如果伺服器超載,就可能發生這些錯誤。在發生大量要求或存在繁重網路流量期間,指數輪詢可協助減輕這一類問題。
  • 其他類型的要求不應透過指數輪詢處理,但您仍可重試其中一些要求。重試這些要求時,請限制重試的次數。例如,您的程式碼可能會限制為在十次或更少次數的重試之後報告錯誤。
  • 執行支援續傳的上傳作業時,請透過從頭開始完整的上傳作業來處理 404 Not Found 錯誤。

指數輪詢

指數輪詢是網路應用程式的標準錯誤處理策略,用戶端可透過這種策略,以逐漸增加的次數定期重試失敗的要求。如果大量要求或繁重的網路流量導致伺服器傳回錯誤,指數輪詢就是處理這類錯誤的一種不錯的策略。相反地,處理與網路流量或回應時間相關的錯誤 (例如授權憑證無效或找不到檔案的錯誤) 並不是很有意義的策略。

在正確的使用之下,指數輪詢可以提升頻寬使用的效率,減少取得成功回應所需的要求數,並最大化並行環境中的要求總處理量。

實作簡單指數輪詢的流程如下:

  1. 對 API 提出要求。
  2. 接收 HTTP 503 回應,這表示您應重試要求。
  3. 等待 1 秒鐘 + random_number_milliseconds 並重試要求。
  4. 接收 HTTP 503 回應,這表示您應重試要求。
  5. 等待 2 秒鐘 + random_number_milliseconds 並重試要求。
  6. 接收 HTTP 503 回應,這表示您應重試要求。
  7. 等待 4 秒鐘 + random_number_milliseconds 並重試要求。
  8. 接收 HTTP 503 回應,這表示您應重試要求。
  9. 等待 8 秒鐘 + random_number_milliseconds 並重試要求。
  10. 接收 HTTP 503 回應,這表示您應重試要求。
  11. 等待 16 秒鐘 + random_number_milliseconds 並重試要求。
  12. 停止。報告或記錄錯誤。

在以上流程中,random_number_milliseconds 是小於或等於 1000 的隨機毫秒數。這是必要的,因為使用較小的隨機延遲有助於更平均地分散負載,並避免對伺服器產生衝擊的可能性。必須在每次等待之後重新定義 random_number_milliseconds 的值。

注意:等待時間一律是 (2 ^ n) + random_number_milliseconds,其中 n 是一開始定義為 0 的單調遞增整數。對於每個疊代 (每次要求),整數 n 會遞增 1。

演算法設定為當 n 為 5 時終止。這個上限可以防止用戶端無限重試,導致總延遲達到約 32 秒而使要求被視為「無法復原的錯誤」。重試上限數偏大並沒有關係,特別是當正在進行大型上傳時;只不過要確保將重試延遲限制在合理的範圍之內,例如,短於一分鐘。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁