建立資料集

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

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

  • 使用 Cloud Console 或 BigQuery 傳統網頁版 UI
  • 使用 bq mk CLI 指令
  • 呼叫 datasets.insert API 方法
  • 使用用戶端程式庫
  • 複製現有的資料集

如要查看複製資料集的步驟 (包括跨地區的複製作業),請參閱複製資料集

資料集的限制

BigQuery 資料集有下列限制:

  • 您只能在建立資料集時設定地理位置。這個位置在資料集建立之後就固定不變了,無法讓您利用 Cloud Console、BigQuery 傳統網頁版 UI、指令列,或是呼叫 patchupdate API 方法來變更。
  • 在單一查詢中參考的所有資料表,都必須存放在相同位置的資料集中。

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

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

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

為資料集命名

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

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

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

資料集名稱不能:

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

所需權限

您至少必須擁有 bigquery.datasets.create 權限,才能建立資料集。以下是擁有 bigquery.datasets.create 權限的預先定義 Cloud IAM 角色:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.user
  • bigquery.admin

如要進一步瞭解 BigQuery 中的 Cloud IAM 角色和權限,請參閱預先定義的角色與權限

建立資料集

如何建立資料集:

主控台

  1. 在 Cloud Console 中開啟 BigQuery 網頁版 UI。

    前往 Cloud Console

  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] (確定)。

CLI

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

如要在非預設專案中建立資料集,請採用下列格式將專案 ID 新增至資料集:project_id:dataset

bq --location=location mk \
--dataset \
--default_table_expiration integer1 \
--default_partition_expiration integer2 \
--description description \
project_id:dataset

其中:

  • location 是資料集的位置。資料集在建立之後,該位置就無法改變。您可以使用 .bigqueryrc 檔案,設定該位置的預設值。

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

  • integer2 是新建立的分區資料表中分區的預設生命週期 (以秒為單位)。預設的分區到期時間沒有最小值。到期時間為分區日期加上該整數值。您在資料集的分區資料表中建立的所有分區,都會在分區日期的 [INTEGER2] 秒之後遭到刪除。如果您在建立或更新分區資料表時使用 --time_partitioning_expiration 旗標,系統會優先採用資料表層級的分區到期時間,而不是資料集層級的預設分區到期時間。

  • description 就是夾在兩個引號中間的資料集說明。

  • 「project_id」是您的專案 ID。

  • dataset 是您要建立的資料集名稱。

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

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

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 and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new 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";

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

  // Create a new dataset
  const [dataset] = await bigquery.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

後續步驟