创建数据集

本文档介绍如何在 BigQuery 中创建数据集。

您可以通过以下方式创建数据集：

使用 Google Cloud 控制台。
使用 SQL 查询。
在 bq 命令行工具中使用 bq mk 命令。
调用 datasets.insert API 方法。
使用客户端库。
复制现有数据集。

如需查看复制数据集的步骤（包括跨区域复制），请参阅复制数据集。

如需了解如何查询公共数据集中的表，请参阅使用 Google Cloud 控制台查询公共数据集。

数据集限制

BigQuery 数据集有以下限制：

数据集位置只能在创建时设置。创建数据集后，就无法再更改其位置。
查询中引用的所有表必须存储在位于同一位置的数据集中。
复制表时，包含源表和目标表的数据集必须位于同一位置。
各个项目的数据集名称不得重复。
如果您更改了数据集的存储空间结算模式，则必须等待 14 天才能再次更改存储空间结算模式。
如果您的任何现有旧版固定费率槽承诺位于数据集所在的区域，则无法将数据集加入物理存储空间结算。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 Identity and Access Management (IAM) 角色。

所需权限

如需创建数据集，您需要拥有 bigquery.datasets.create IAM 权限。

以下每个预定义 IAM 角色都包含创建数据集所需的权限：

roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.user
roles/bigquery.admin

如需详细了解 BigQuery 中的 IAM 角色，请参阅预定义的角色和权限。

命名数据集

在 BigQuery 中创建数据集时，每个项目的数据集名称不得重复。数据集名称可以包含以下内容：

不超过 1024 个字符。
字母（大写字母或小写字母）、数字和下划线。

默认情况下，数据集名称区分大小写。mydataset 和 MyDataset 可以位于同一项目中，除非其中一个不区分大小写。

数据集名称不能包含空格或特殊字符，例如 -、&、@ 或 %。

隐藏的数据集

隐藏的数据集是指名称以下划线开头的数据集。您可以按照与任何其他数据集中相同的方式查询隐藏数据集中的表和视图。隐藏的数据集具有以下限制：

在 Google Cloud 控制台的探索器面板中处于隐藏状态。
不会显示在任何 INFORMATION_SCHEMA 视图中。
不能与关联的数据集搭配使用。
不会显示在 Data Catalog 中。

创建数据集

要创建数据集，请执行以下操作：

控制台

在 Google Cloud 控制台中打开 BigQuery 页面。

转到 BigQuery 页面
在探索器面板中，选择您要在其中创建数据集的项目。
展开操作选项，然后点击创建数据集：
在创建数据集页面中执行以下操作：
- 对于数据集 ID，输入唯一的数据集名称。
- 对于位置类型，为数据集选择一个地理位置。创建数据集后，就无法再更改此位置。
  
  注意：如果您选择 EU 或某个欧盟区域作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据是在服务专用条款中定义的。
- 可选：如果您希望此数据集中的表过期，请选择启用表过期时间，然后指定默认表存在时间上限（以天为单位）。
  
  注意：如果您的项目未与结算账号关联，则 BigQuery 会自动为您在该项目中创建的数据集设置默认表过期时间。您可以为数据集指定较短的默认表过期时间，但不能指定较长的默认表过期时间。
- 可选：如果您要使用客户管理的加密密钥 (CMEK)，请展开高级选项，然后选择客户管理的加密密钥 (CMEK)。
- 可选：如果您要使用不区分大小写的表名称，请展开高级选项，然后选择启用不区分大小写的表名称。
- 可选：如果您要使用默认排序规则，请展开高级选项，选择启用默认排序规则，然后选择要使用的默认排序规则。
- 可选：如果您要使用默认舍入模式，请展开高级选项，然后选择要使用的默认舍入模式。
- 可选：如果您要启用物理存储结算模式，请展开高级选项，然后选择启用物理存储结算模式。
  
  更改数据集的结算模式后，更改需要 24 小时才能生效。
  
  更改数据集的存储结算模式后，您必须等待 14 天才能再次更改存储结算模式。
- 可选：如果您要设置数据集的时间旅行窗口，请展开高级选项，然后选择要使用的时间旅行窗口。
- 点击创建数据集。

SQL

使用 CREATE SCHEMA 语句。

如需在非默认项目中创建数据集，请按照以下格式将项目 ID 添加到数据集 ID：PROJECT_ID.DATASET_ID。

在 Google Cloud 控制台中，进入 BigQuery 页面。

转到 BigQuery
在查询编辑器中，输入以下语句：
```
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 天（一小时）。到期时间以当前时间加上这个整数值部分为准。在数据集中创建的任何表都会在自创建之时起的 TABLE_EXPIRATION 天后删除。如果您在创建表时未设置表到期时间，则系统会应用此值。
- DESCRIPTION：数据集的说明
- KEY_1:VALUE_1：您想要在此数据集上设置为第一个标签的键值对
- KEY_2:VALUE_2：您要设置为第二个标签的键值对
- LOCATION：数据集的位置。创建数据集后，此位置无法再更改。
  注意：如果您选择 EU 或某个欧盟区域作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中进行了定义。
- HOURS：新数据集的时间旅行窗口的时长（以小时为单位）。 HOURS 值必须是 48（2 天）到 168（7 天）之间以 24 的倍数（48、72、96、120、144、168）表示的整数。如果未指定此选项，则默认值为 168 小时。
- BILLING_MODEL：设置数据集的存储结算模式。您可以将 BILLING_MODEL 值设置为 PHYSICAL 以在计算存储费用时使用物理字节，或设置为 LOGICAL 以使用逻辑字节。默认值为 LOGICAL。
  更改数据集的结算模式后，更改需要 24 小时才能生效。
  
  更改数据集的存储结算模式后，您必须等待 14 天才能再次更改存储结算模式。
点击运行。

如需详细了解如何运行查询，请参阅运行交互式查询。

bq

如需创建新数据集，请使用带有 --location 标志的 bq mk 命令。如需查看完整的潜在参数列表，请参阅 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 文件设置位置的默认值。

注意：如果您选择 EU 作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中进行了定义。
KMS_KEY_NAME：默认 Cloud Key Management Service 密钥的名称，此密钥用于保护此数据集中新创建的表，除非在创建时提供了不同的密钥。您无法使用此参数集在数据集中创建 Google 加密表。
PARTITION_EXPIRATION：新创建的分区表中的分区的默认生命周期（以秒为单位）。默认分区到期时间没有最小值。过期时间以分区的日期加上这个整数值为准。在数据集分区表中创建的任何分区都会在分区的日期起的 PARTITION_EXPIRATION 秒后删除。如果在创建或更新分区表时提供 --time_partitioning_expiration 标志，则表级分区到期时间优先于数据集级默认分区到期时间。
TABLE_EXPIRATION：新创建的表的默认生命周期（以秒为单位）。最小值为 3600 秒（一小时）。到期时间以当前时间加上这个整数值为准。在数据集中创建的任何表都会在创建之时起的 TABLE_EXPIRATION 秒后删除。如果您在创建表时未设置表过期时间，则系统会应用此值。
DESCRIPTION：数据集的说明
KEY_1:VALUE_1：您想要在此数据集上设置为第一个标签的键值对，KEY_2:VALUE_2 是您要设置为第二个标签的键值对。
KEY_3:VALUE_3：您要将其设置为数据集标记的键值对。在同一标志下添加多个标记，并在键值对之间使用英文逗号。
HOURS：新数据集的时间旅行窗口的时长（以小时为单位）。 HOURS 值必须是 48（2 天）到 168（7 天）之间以 24 的倍数（48、72、96、120、144、168）表示的整数。如果未指定此选项，则默认值为 168 小时。
BILLING_MODEL：设置数据集的存储结算模式。您可以将 BILLING_MODEL 值设置为 PHYSICAL 以在计算存储费用时使用物理字节，或设置为 LOGICAL 以使用逻辑字节。默认值为 LOGICAL。

更改数据集的结算模式后，更改需要 24 小时才能生效。

更改数据集的存储结算模式后，您必须等待 14 天才能再次更改存储结算模式。
PROJECT_ID：您的项目 ID。
DATASET_ID 是您要创建的数据集的 ID。

例如，以下命令会创建一个名为 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。如需详细了解如何创建表，请参阅创建表。

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 块类似于如下所示：

访问使用 Terraform 创建的数据集的块。

如需授予对数据集的访问权限，建议您使用 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

启动 Cloud Shell。
设置要在其中应用 Terraform 配置的默认 Google Cloud 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

将示例代码复制到新创建的 main.tf 中。

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

API

使用已定义的数据集资源调用 datasets.insert 方法。

C#

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 C# 设置说明进行操作。如需了解详情，请参阅 BigQuery C# API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。


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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 BigQuery Go API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Java 设置说明进行操作。如需了解详情，请参阅 BigQuery Java API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

// 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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Ruby 设置说明进行操作。如需了解详情，请参阅 BigQuery Ruby API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

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

数据集安全性

如需控制对 BigQuery 中数据集的访问权限，请参阅控制对数据集的访问权限。如需了解数据加密，请参阅静态加密。

后续步骤

如需详细了解如何列出项目中的数据集，请参阅列出数据集。
如需详细了解数据集元数据，请参阅获取有关数据集的信息。
如需详细了解如何更改数据集属性，请参阅更新数据集。
如需详细了解如何创建和管理标签，请参阅创建和管理标签。

自行试用

如果您是 Google Cloud 新手，请创建一个账号来评估 BigQuery 在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费试用 BigQuery