建立資料集

主控台

1. 在 Google Cloud 控制台開啟「BigQuery」頁面。
前往「BigQuery」頁面
2. 在「Explorer」面板中，選取要建立資料集的專案。
3. 展開 more_vert「View actions」 選項，然後按一下「Create dataset」。

4. 在「Create dataset」(建立資料集) 頁面：
1. 針對「Dataset ID」(資料集 ID)，輸入唯一的資料集名稱。
2. 針對「Location type」(位置類型)，選擇資料集的地理位置。資料集在建立之後，該位置就無法改變。
3. 選用：如要建立外部資料集，請選取「Link to an external dataset」。
4. 如果您不需要設定標記和資料表到期時間等其他選項，請按一下「建立資料集」。否則，請展開下列部分，設定其他資料集選項。

資料集的其他選項

1. 選用：展開「標記」部分，即可在資料集中新增標記。
2. 如要套用現有標籤，請按照下列步驟操作：
1. 按一下「選取範圍」旁的下拉式箭頭，然後選擇「目前範圍」「選取目前的機構」或「選取目前的專案」。

或者，您也可以按一下「選取範圍」來搜尋資源，或查看目前的資源清單。

2. 針對「Key 1」和「Value 1」，請從清單中選擇適當的值。
3. 如要手動輸入新代碼，請按照下列步驟操作：
1. 按一下「選取範圍」旁的下拉式箭頭，然後選擇「手動輸入 ID」>「機構」、「專案」或「標記」。
2. 如果您要為專案或機構建立標記，請在對話方塊中輸入 PROJECT_ID 或 ORGANIZATION_ID，然後按一下「儲存」。
3. 針對「Key 1」和「Value 1」，請從清單中選擇適當的值。
4. 如要在表格中新增其他標記，請按一下「新增標記」，然後按照前述步驟操作。
4. 選用：展開「進階選項」部分，設定下列一或多個選項。
1. 如要變更「加密」選項，以便使用您自己的加密編譯金鑰搭配 Cloud Key Management Service，請選取「Cloud KMS 金鑰」。
2. 如要使用不區分大小寫的資料表名稱，請選取「啟用不區分大小寫的資料表名稱」。
3. 如要變更預設定序 規格，請從清單中選擇定序類型。
4. 如要為資料集中的資料表設定到期時間，請選取「啟用資料表到期時間」，然後以天為單位指定「預設資料表存在時間上限」。
5. 如要設定預設捨入模式，請從清單中選擇捨入模式。
6. 如要啟用實體儲存空間計費模式，請從清單中選擇所需計費模式。

變更資料集的計費模式後，變更內容會在 24 小時後生效。

一旦變更資料集的儲存空間計費模式，就必須等待 14 天，才能再次變更儲存空間計費模式。

7. 如要設定資料集的時間回溯期，請從清單中選擇視窗大小。
5. 點選「建立資料集」。

SQL

使用 CREATE SCHEMA 陳述式。

如要在非預設專案中建立資料集，請使用下列格式將專案 ID 新增至資料集 ID：PROJECT_ID.DATASET_ID。

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE SCHEMA PROJECT_ID.DATASET_ID
     OPTIONS (
       default_kms_key_name = 'KMS_KEY_NAME',
       default_partition_expiration_days = PARTITION_EXPIRATION,
       default_table_expiration_days = TABLE_EXPIRATION,
       description = 'DESCRIPTION',
       labels = [('KEY_1','VALUE_1'),('KEY_2','VALUE_2')],
       location = 'LOCATION',
       max_time_travel_hours = HOURS,
       storage_billing_model = BILLING_MODEL);

   請依指示取代下列項目：

   • PROJECT_ID：您的專案 ID
   • DATASET_ID：您要建立的資料集 ID
   • KMS_KEY_NAME：預設 Cloud Key Management Service 金鑰的名稱，用於保護這個資料集中新建立的資料表，除非在建立時提供其他金鑰。您無法在具有此參數集的資料集中建立 Google 加密表格。
   • PARTITION_EXPIRATION：新建分區資料表中分區的預設生命週期 (以天為單位)。預設的分區到期時間沒有最小值。到期時間為分區日期加上整數值。在資料集的分區資料表中所建立的任何分區，都會在分區日期的 PARTITION_EXPIRATION 天後刪除。如果您在建立或更新分區資料表時使用 time_partitioning_expiration 選項，則資料表層級的分區到期時間會覆寫資料集層級的預設分區到期時間。
   • TABLE_EXPIRATION：新建資料表的預設生命週期 (以天為單位)。最小值為 0.042 天 (1 小時)。到期時間為目前時間加整數值。在資料集中建立的任何資料表都會在建立時間後 TABLE_EXPIRATION 天刪除。如果您在建立資料表時未設定資料表到期時間，系統就會套用這個值。
   • DESCRIPTION：資料集說明
   • KEY_1:VALUE_1：您要將哪個鍵/值組合設為此資料集的第一個標籤
   • KEY_2:VALUE_2：您要設為第二個標籤的鍵/值組合
   • LOCATION：資料集的位置。資料集在建立之後，該位置就無法改變。
   • HOURS：新資料集的時間回溯期 (以小時為單位)。HOURS 值必須是介於 48 (2 天) 和 168 (7 天) 之間的整數，以 24 為倍數 (48、72、96、120、144、168) 表示。如果未指定這個選項，預設值為 168 小時。
   • BILLING_MODEL：設定資料集的儲存空間計費模式。將 BILLING_MODEL 值設為 PHYSICAL，即可在計算儲存空間費用時使用實體位元組，或設為 LOGICAL 即可使用邏輯位元組。預設值為 LOGICAL。

     變更資料集的計費模式後，變更內容會在 24 小時後生效。

     一旦變更資料集的儲存空間計費模式，就必須等待 14 天，才能再次變更儲存空間計費模式。

3. 按一下 play_circle「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

bq

如要建立新的資料集，請使用 bq mk 指令搭配 --location 旗標。如需可能參數的完整清單，請參閱 bq mk --dataset 指令參考資料。

如要在非預設專案中建立資料集，請採用下列格式將專案 ID 新增至資料集：PROJECT_ID:DATASET_ID。

bq --location=LOCATION mk \
    --dataset \
    --default_kms_key=KMS_KEY_NAME \
    --default_partition_expiration=PARTITION_EXPIRATION \
    --default_table_expiration=TABLE_EXPIRATION \
    --description="DESCRIPTION" \
    --label=KEY_1:VALUE_1 \
    --label=KEY_2:VALUE_2 \
    --add_tags=KEY_3:VALUE_3[,...] \
    --max_time_travel_hours=HOURS \
    --storage_billing_model=BILLING_MODEL \
    PROJECT_ID:DATASET_ID

更改下列內容：

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

• KMS_KEY_NAME：預設 Cloud Key Management Service 金鑰的名稱，用於保護這個資料集中新建立的資料表，除非在建立時提供其他金鑰。您無法在具有此參數集的資料集中建立 Google 加密表格。

• PARTITION_EXPIRATION：新建分區資料表中分區的預設生命週期 (以秒為單位)。預設的分區到期時間沒有最小值。到期時間為分區日期加上整數值。在資料集的分區資料表中建立的任何分區，都會在分區日期後 PARTITION_EXPIRATION 秒刪除。如果您在建立或更新分區資料表時使用 --time_partitioning_expiration 旗標，則資料表層級的分區到期時間會覆寫資料集層級的預設分區到期時間。

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

• DESCRIPTION：資料集說明

• KEY_1:VALUE_1：您要將哪個鍵/值組合設為此資料集的第一個標籤，而 KEY_2:VALUE_2 則是您要將哪個鍵/值組合設為第二個標籤。

• KEY_3:VALUE_3：您要將其設為資料集標記的鍵/值組合。在同一個標記下方新增多個標記，並在鍵/值組合之間加上逗號。

• HOURS：新資料集的時間回溯期 (以小時為單位)。HOURS 值必須是整數，以 24 的倍數 (48、72、96、120、144、168) 表示，介於 48 (2 天) 和 168 (7 天) 之間。如果未指定這個選項，預設值為 168 小時。

• BILLING_MODEL：設定資料集的儲存空間計費模式。將 BILLING_MODEL 值設為 PHYSICAL，即可在計算儲存空間費用時使用實體位元組；將其設為 LOGICAL，則可使用邏輯位元組。預設為 LOGICAL。

  變更資料集的計費模式後，變更內容會在 24 小時後生效。

  一旦變更資料集的儲存空間計費模式，就必須等待 14 天，才能再次變更儲存空間計費模式。

• PROJECT_ID：您的專案 ID。

• DATASET_ID 是您要建立的資料集 ID。

舉例來說，下列指令會建立名為 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

如要確認資料集已建立完成，請輸入 bq ls 指令。此外，您可以在建立新的資料集時，採用下列格式來建立資料表：bq mk -t dataset.table。如要進一步瞭解如何建立資料表，請參閱「建立資料表」。

Terraform

使用 google_bigquery_dataset 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

建立資料集

以下範例會建立名為 mydataset 的資料集：

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

使用 google_bigquery_dataset 資源建立資料集時，系統會自動將資料集存取權授予所有專案層級基本角色的帳戶成員。如果在建立資料集後執行 terraform show 指令，資料集的 access 區塊會類似以下內容：

如要授予資料集存取權，建議您使用其中一個 google_bigquery_iam 資源 (如以下範例所示)，除非您打算在資料集中建立已授權的物件，例如已授權的檢視畫面。在這種情況下，請使用 google_bigquery_dataset_access 資源。如需範例，請參閱該說明文件。

建立資料集並授予存取權

以下範例會建立名為 mydataset 的資料集，然後使用 google_bigquery_dataset_iam_policy 資源授予存取權。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# Update the user, group, or service account
# provided by the members argument with the
# appropriate principals for your organization.
data "google_iam_policy" "default" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:raha@altostrat.com",
    ]
  }
  binding {
    role = "roles/bigquery.admin"
    members = [
      "user:raha@altostrat.com",
    ]
  }
  binding {
    role = "roles/bigquery.user"
    members = [
      "group:analysts@altostrat.com",
    ]
  }
  binding {
    role = "roles/bigquery.dataViewer"
    members = [
      "serviceAccount:bqcx-1234567891011-abcd@gcp-sa-bigquery-condel.iam.gserviceaccount.com",
    ]
  }
}

resource "google_bigquery_dataset_iam_policy" "default" {
  dataset_id  = google_bigquery_dataset.default.dataset_id
  policy_data = data.google_iam_policy.default.policy_data
}

使用客戶自行管理的加密金鑰建立資料集

以下範例會建立名為 mydataset 的資料集，並使用 google_kms_crypto_key 和 google_kms_key_ring 資源，為資料集指定 Cloud Key Management Service 金鑰。您必須先啟用 Cloud Key Management Service API，才能執行這個範例。

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  default_encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
  depends_on = [google_project_iam_member.service_account_access]
}

resource "google_kms_crypto_key" "crypto_key" {
  name     = "example-key"
  key_ring = google_kms_key_ring.key_ring.id
}

resource "random_id" "default" {
  byte_length = 8
}

resource "google_kms_key_ring" "key_ring" {
  name     = "${random_id.default.hex}-example-keyring"
  location = "us"
}

# Enable the BigQuery service account to encrypt/decrypt Cloud KMS keys
data "google_project" "project" {
}

resource "google_project_iam_member" "service_account_access" {
  project = data.google_project.project.project_id
  role    = "roles/cloudkms.cryptoKeyEncrypterDecrypter"
  member  = "serviceAccount:bq-${data.google_project.project.number}@bigquery-encryption.iam.gserviceaccount.com"
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節中的步驟。

準備 Cloud Shell

1. 啟動 Cloud Shell。

2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

   您只需為每個專案執行這個指令一次，而且可以在任何目錄中執行。

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

   如果您在 Terraform 設定檔中設定明確的值，系統就會覆寫環境變數。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須包含 .tf 副檔名，例如 main.tf。在本教學課程中，檔案稱為 main.tf。

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

2. 如果您正在參考教學課程，可以複製各個章節或步驟中的程式碼範例。

   將範例程式碼複製到新建立的 main.tf 中。

   您可以視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

3. 查看並修改要套用至環境的範例參數。
4. 儲存變更。
5. 初始化 Terraform。這項操作只需對每個目錄執行一次。

   terraform init

   如要使用最新版的 Google 供應器，您可以選擇加入 -upgrade 選項：

   terraform init -upgrade

套用變更

1. 檢查設定，確認 Terraform 要建立或更新的資源符合您的預期：

   terraform plan

   視需要修正設定。

2. 執行下列指令，並在提示中輸入 yes，即可套用 Terraform 設定：

   terraform apply

   等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。

3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

API

請呼叫 datasets.insert 方法，搭配已定義的資料集資源。

C#

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;

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

Go

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// createDataset demonstrates creation of a new dataset using an explicit destination location.
func createDataset(projectID, datasetID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta := &bigquery.DatasetMetadata{
		Location: "US", // See https://cloud.google.com/bigquery/docs/locations
	}
	if err := client.Dataset(datasetID).Create(ctx, meta); err != nil {
		return err
	}
	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

public class CreateDataset {

  public static void runCreateDataset() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    createDataset(datasetName);
  }

  public static void createDataset(String datasetName) {
    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();

      DatasetInfo datasetInfo = DatasetInfo.newBuilder(datasetName).build();

      Dataset newDataset = bigquery.create(datasetInfo);
      String newDatasetName = newDataset.getDatasetId().getDataset();
      System.out.println(newDatasetName + " created successfully");
    } catch (BigQueryException e) {
      System.out.println("Dataset was not created. \n" + e.toString());
    }
  }
}

Node.js

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

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

from google.cloud import bigquery

# 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, with an explicit timeout.
# Raises google.api_core.exceptions.Conflict if the Dataset already
# exists within the project.
dataset = client.create_dataset(dataset, timeout=30)  # Make an API request.
print("Created dataset {}.{}".format(client.project, dataset.dataset_id))

Ruby

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