建立資料集

本文件說明如何在 BigQuery 中建立資料集。

您可以透過以下方式建立資料集:

  • 使用 GCP 主控台或 BigQuery 傳統網頁版 UI
  • 使用 CLI 指令 bq mk
  • 呼叫 datasets.insert API 方法

資料集的限制

BigQuery 資料集有下列限制:

  • 您只能在建立時設定地理位置。建立資料集後,位置便無法改變,而且無法在 GCP 主控台、傳統 BigQuery 網頁版 UI、指令列工具,或透過呼叫 patchupdate API 方法進行變更。
  • 在查詢中參考的所有資料表,都必須儲存在同一個位置的資料集中。

  • 複製資料表時,包含來源資料表和目的地資料表的資料集必須位於同一個位置。

  • 每個專案的資料集名稱不得重複。

  • 專案中的資料集接近數千個時,傳統版 UI 的效能會開始降低,列出資料集的速度會變慢。

命名資料集

當您在 BigQuery 中建立資料集時,每個專案的資料集名稱不得重複。資料集名稱:

  • 最多可以包含 1,024 個字元
  • 可以包含字母 (大寫或小寫)、數字和底線

  • 會區分大小寫:mydatasetMyDataset 可以共存於同一個專案中

資料集名稱不能:

  • 包含空格或特殊字元 (例如 -、&、@ 或 %)

所需權限

如要建立資料集,您必須取得提供 bigquery.datasets.create 權限的專案層級原始角色,或預先定義的身分與存取權管理 (IAM) 角色。以下是擁有 bigquery.datasets.create 權限的預先定義專案層級 IAM 角色:

如要深入瞭解 BigQuery 中的 IAM 角色和權限,請參閱存取權控制

建立資料集

如何建立資料集:

主控台

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

    前往 BigQuery 網頁版 UI

  2. 在導覽面板的「Resources」(資源) 部分,選取您的專案名稱。

  3. 在視窗右側的詳細資訊面板中,點選 [Create dataset] (建立資料集)

  4. 在「Create dataset」(建立資料集) 頁面:

    • 針對「Dataset ID」(資料集 ID),輸入唯一的資料集名稱
    • (選填) 針對「Data location」(資料位置),選擇資料集的地理位置。如果這個值的設定維持在「Default」(預設),則位置會設為 US。資料集建立後就無法變更位置。

    • 針對「Default table expiration」(預設資料表到期時間),請選擇下列其中一個選項:

      • [Never] (永不):(預設) 在資料集中建立的資料表永遠不會自動刪除,只能手動刪除。
      • [Number of days after table creation] (資料表建立後的天數):此值決定何時刪除資料集中的新建資料表。如果您在建立資料表時未設定資料表到期時間,系統就會套用這個值。
    • 按一下 [Create dataset] (建立資料集)

傳統版 UI

  1. 在導覽窗格中,按一下專案名稱旁的向下箭號圖示 向下箭號圖示,然後按一下 [Create new dataset] (建立新資料集)

  2. 在「Create Dataset」(建立資料集) 對話方塊中:

    • 針對「Dataset ID」(資料集 ID),輸入唯一的資料集名稱。
    • 針對「Data location」(資料位置),選擇資料集的位置。預設值為 [Unspecified] (未指定),該值會將資料集位置設為 US。資料集建立後就無法變更位置。

    • 針對「Data expiration」,選擇下列其中一個選項:

      • [Never]:(預設) 在資料集中建立的資料表永遠不會自動刪除,只能手動刪除。
      • [In [INTEGER] days]:在資料集中建立的任何資料表都會在建立時間後 [INTEGER] 天刪除。如果您在建立資料表時未設定資料表到期時間,系統就會套用這個值。

        建立資料集

        「Data expiration」是指資料集中新建資料表的預設資料表到期時間。目前在 BigQuery 網頁版 UI 中建立資料集時,無法設定預設分區到期時間。您可以在建立資料集後,使用指令列工具或 API 設定預設的分區到期時間

    • 點選 [OK] (確定)。

指令列

搭配 --location 標記使用 bq mk 指令來建立新的資料集。選用的參數包括 --default_table_expiration--default_partition_expiration--description

如要在預設專案以外的專案中建立資料集,請使用下列格式將專案 ID 新增至資料集名稱:[PROJECT_ID]:[DATASET]

bq --location=[LOCATION] mk --dataset --default_table_expiration [INTEGER] --default_partition_expiration [INTEGER2] --description [DESCRIPTION] [PROJECT_ID]:[DATASET]

其中:

  • [LOCATION] 是資料集的位置。建立資料集後,就無法變更位置。您可以使用 .bigqueryrc 檔案來設定位置的預設值。

  • [INTEGER] 是新建資料表的預設生命週期 (以秒為單位)。最小值是 3600 秒 (1 小時)。到期時間為目前時間加整數值。在資料集中建立的任何資料表都會在建立時間後 [INTEGER] 秒刪除。如果您在建立資料表時未設定資料表到期時間,系統就會套用這個值。

  • [INTEGER2] 是新建分區資料表中分區的預設生命週期 (以秒為單位)。預設的分區到期時間沒有最小值。到期時間為分區日期加整數值。在資料集的分區資料表中所建立的任何分區,都會以分區建立日期為起始點,在 [INTEGER2] 秒後刪除。如果您在建立或更新分區資料表時使用了 --time_partitioning_expiration 標記,則資料表層級的分區到期時間會覆寫資料集層級的預設分區到期時間。

  • [DESCRIPTION] 是置於括號中的資料集說明。

  • [PROJECT_ID] 是您的專案 ID。

  • [DATASET] 是您要建立的資料集名稱。

舉例來說,以下指令會建立名為 mydataset 的資料集,並將資料位置設為 US,資料表的預設到期時間為 3600 秒 (1 小時),說明則為 This is my dataset。這個指令不使用 --dataset 標記,而是改用 -d 捷徑。如果您省略 -d--dataset,則該指令預設會建立資料集。

bq --location=US mk -d --default_table_expiration 3600 --description "This is my dataset." mydataset

您可以輸入 bq ls 指令來確認該資料集是否已成功建立。此外,您可以在建立新的資料集時建立資料表,方法是使用以下格式:bq mk -t [DATASET].[TABLE]。如要深入瞭解如何建立資料表,請參閱建立資料表

API

使用已定義的資料集資源呼叫 datasets.insert 方法。

C#

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

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

public class BigQueryCreateDataset
{
    public BigQueryDataset CreateDataset(
        string projectId = "your-project-id",
        string location = "US"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var createDatasetOptions = new CreateDatasetOptions()
        {
            // Specify the geographic location where the dataset should reside.
            Location = location
        };
        // Create the dataset
        return client.CreateDataset(
            datasetId: "your_new_dataset_id", options: createDatasetOptions);
    }
}

Go

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

// 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")
meta := &bigquery.DatasetMetadata{
	Location: "US", // Create the dataset in the US.
}
if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
	return err
}

Java

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

Dataset dataset = null;
DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();
try {
  // the dataset was created
  dataset = bigquery.create(datasetInfo);
} catch (BigQueryException e) {
  // the dataset was not created
}

Node.js

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

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

async function createDataset() {
  // Creates a new dataset named "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_new_dataset";

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

  // Specify the geographic location where the dataset should reside
  const options = {
    location: 'US',
  };

  // Create a new dataset
  const [dataset] = await bigqueryClient.createDataset(datasetId, options);
  console.log(`Dataset ${dataset.id} created.`);
}

createDataset();

PHP

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

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->createDataset($datasetId);
printf('Created dataset %s' . PHP_EOL, $datasetId);

Python

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

from google.cloud import bigquery

# TODO(developer): Construct a BigQuery client object.
# client = bigquery.Client()

# TODO(developer): Set dataset_id to the ID of the dataset to create.
# dataset_id = "{}.your_dataset".format(client.project)

# Construct a full Dataset object to send to the API.
dataset = bigquery.Dataset(dataset_id)

# TODO(developer): Specify the geographic location where the dataset should reside.
dataset.location = "US"

# Send the dataset to the API for creation.
# Raises google.api_core.exceptions.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset)  # API request
print("Created dataset {}.{}".format(client.project, dataset.dataset_id))

Ruby

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

require "google/cloud/bigquery"

def create_dataset dataset_id = "my_dataset", location = "US"
  bigquery = Google::Cloud::Bigquery.new

  # Create the dataset in a specified geographic location
  bigquery.create_dataset dataset_id, location: location

  puts "Created dataset: #{dataset_id}"
end

後續步驟

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

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

這個網頁