创建数据集

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

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

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

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

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

数据集限制

BigQuery 数据集有以下限制：

您只能在创建时设置地理位置。创建数据集后，该位置即保持不变，而且无法通过 Google Cloud 控制台、bq 命令行工具或通过调用 patch 或 update API 方法予以更改。
查询中引用的所有表必须存储在位于同一位置的数据集中。
复制表时，包含源表和目标表的数据集必须位于同一位置。
同一个项目中的数据集名称不得重复。

准备工作

授予为用户提供执行本文档中的每个任务所需权限的 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 个字符。
字母（大写字母或小写字母）、数字和下划线。

注意：在 Google Cloud 控制台中，探索器面板中会隐藏以下划线开头的数据集。即使这些数据集不可见，您仍然可以在这些数据集中查询表和视图。

数据集名称区分大小写：mydataset 和 MyDataset 可以位于同一项目中。

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

创建数据集

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

控制台

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

转到 BigQuery 页面
在探索器面板中，选择您要在其中创建数据集的项目。
展开操作选项，然后点击创建数据集。
在创建数据集页面中执行以下操作：
- 对于数据集 ID，输入唯一的数据集名称。
- 对于数据位置，为数据集选择一个地理位置。创建数据集后，就无法再更改此位置。
  
  注意：如果您选择 EU 或某个欧盟区域作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据是在服务专用条款中定义的。
- 对于默认表过期时间，请选择以下任一选项：
  - 永不：（默认）永不自动删除在数据集中创建的表。您必须手动删除这些表。
  - 创建表后的天数：此值确定何时删除数据集中新创建的表。如果您在创建表时未设置表到期时间，则系统会应用此值。
    
    注意：如果您的项目未与结算帐号关联，则 BigQuery 会自动为您在该项目中创建的数据集设置默认表到期时间。您可以为数据集指定较短的默认表到期时间，但不能指定较长的默认表到期时间。
- 点击创建数据集。

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 = [('LABEL_1','VALUE_1'),('LABEL_2','VALUE_2')],
    location = 'LOCATION',
    max_time_travel_hours = HOURS;
```
替换以下内容：
- PROJECT_ID：您的项目 ID
- DATASET_ID：您要创建的数据集的 ID
- KMS_KEY_NAME：默认 Cloud Key Management Service 密钥的名称，此密钥用于保护此数据集中新创建的表，除非在创建时提供了不同的密钥。您无法使用此参数集在数据集中创建 Google 加密表。
- PARTITION_EXPIRATION：新创建的分区表中的分区的默认生命周期（以秒为单位）。默认分区到期时间没有最小值。到期时间以分区的日期加上这个整数值为准。在数据集的分区表中创建的任何分区都会在分区日期起的 PARTITION_EXPIRATION 秒后删除。如果在创建或更新分区表时提供 time_partitioning_expiration 选项，则表级分区到期时间优先于数据集级默认分区到期时间。
- TABLE_EXPIRATION：新创建的表的默认生命周期（以秒为单位）。最小值为 3600 秒（一小时）。到期时间以当前时间加上这个整数值为准。在数据集中创建的任何表都会在创建之时起的 TABLE_EXPIRATION 秒后删除。如果您在创建表时未设置表到期时间，则系统会应用此值。
- DESCRIPTION：数据集的说明
- LABEL_1:VALUE_1：您想要在此数据集上设置为第一个标签的键值对
- LABEL_2:VALUE_2：您要设置为第二个标签的键值对
- LOCATION：数据集的位置。创建数据集后，此位置无法再更改。
  注意：如果您选择 EU 或某个欧盟区域作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中进行了定义。
- HOURS：新数据集的时间旅行窗口的时长（以小时为单位）。配置时间旅行窗口的功能为预览版。hours 字段必须是 48 到 168 之间的 24 的倍数。如果未指定，则默认为 168。
点击运行。

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

bq

如需创建新数据集，请使用带有 --location 标志的 bq mk 命令。

如需在非默认项目中创建数据集，请按照以下格式将项目 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=LABEL_1:VALUE_1 \
    --label=LABEL_2:VALUE_2 \
    --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：数据集的说明
LABEL_1:VALUE_1：您想要在此数据集上设置为第一个标签的键值对，LABEL_2:VALUE_2 是您要设置为第二个标签的键值对。
HOURS：新数据集的时间旅行窗口的时长（以小时为单位）。配置时间旅行窗口的功能为预览版。HOURS 字段必须是 48 到 168 之间的 24 的倍数。如果未指定，则默认为 168。
BILLING_MODEL：数据集的存储结算模型。设置存储结算模型的功能目前为预览版。您可以将此标志值设置为 LOGICAL 以使用逻辑字节数进行存储结算，也可以设置为 PHYSICAL 以使用物理字节数。
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。如需详细了解如何创建表，请参阅创建表。

API

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

C#

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

在 GitHub 上查看反馈


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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

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