创建数据集

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

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

• 使用 GCP Console 或传统版 BigQuery 网页界面
• 使用 bq mk CLI 命令
• 调用 datasets.insert API 方法
• 使用客户端库

数据集限制

BigQuery 数据集有以下限制：

• 您只能在创建时设置地理位置。创建数据集后，该位置即保持不变，而且无法在 GCP Console、传统版 BigQuery 网页界面、命令行工具中或通过调用 patch 或 update API 方法予以更改。

• 查询中引用的所有表必须存储在数据集中的同一位置。

• 复制表时，包含源表和目标表的数据集必须位于同一位置。

• 每个项目中的数据集名称不得重复。

• 当项目中的数据集接近数千个时，经典版界面的性能会开始下降，列出数据集的速度会变慢。

命名数据集

在 BigQuery 中创建数据集时，您必须保证每个项目中的数据集名称无重复。数据集名称的相关要求如下：

• 最多可以包含 1024 个字符

• 可以包含字母（大写或小写）、数字和下划线

  注意：以下划线开头的数据集在 BigQuery 网页界面和经典版网页界面的导航窗格中处于隐藏状态。即便不可见，您仍然可以查询这些数据集中的表和视图。

• 区分大小写：mydataset 和 MyDataset 在同一个项目中可共存。

数据集名称的禁止事项：

• 不得包含空格或特殊字符，如 -、&、@ 或 %

所需权限

如需创建数据集，您至少必须具有 bigquery.datasets.create 权限。以下预定义的 Cloud IAM 角色具有 bigquery.datasets.create 权限：

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

如需详细了解 BigQuery 中的 Cloud IAM 角色和权限，请参阅访问权限控制。

创建数据集

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

Console

1. 在 GCP Console 中打开 BigQuery 网页界面。

   转到 GCP Console

2. 在导航面板的资源部分，选择您的项目。

3. 在窗口右侧的详细信息面板中，点击创建数据集。

4. 在创建数据集页面上执行以下操作：

   • 对于数据集 ID，输入唯一的数据集名称。

   • （可选）对于数据位置，为数据集选择一个地理位置。如果将值设置为默认，则位置会设置为 US。创建数据集后，位置便无法更改。

     注意：如果您选择 EU 或欧盟的区域作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中定义。

   • 对于默认表到期时间，请选择以下任一选项：

     • 永不：（默认）永不自动删除在数据集中创建的表。您必须手动删除这些表。
     • 创建表后的天数：此值确定何时删除数据集中新创建的表。如果您在创建表时未设置表到期时间，则系统会应用此值。

   • 点击创建数据集。

经典版界面

1. 在导航窗格中，点击项目名称旁边的向下箭头图标 ，然后点击 Create new dataset。

2. 在 Create Dataset 对话框中执行以下操作：

   • 对于数据集 ID，输入唯一的数据集名称。

   • 对于 Data location，为数据集选择一个位置。默认值为 Unspecified，此时数据集位置会设置为 US。创建数据集后，位置便无法更改。

     注意：如果选择 EU 作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中定义。

   • 对于 Data expiration，选择以下选项之一：

     • 永不：（默认）永不自动删除在数据集中创建的表。您必须手动删除这些表。

     • In integer days：在数据集中创建的任何表都会在创建之时起的 integer 天后删除。如果您在创建表时未设置表到期时间，则系统会应用此值。

       数据到期时间是指在数据集中创建的新表的默认表到期时间。在创建数据集时，您当前无法在 BigQuery 网页界面中设置默认分区到期时间。您可以使用命令行工具或 API 在创建数据集后设置默认分区到期时间。

   • 点击 OK。

注意：使用 BigQuery 网页界面创建数据集时，您不能添加说明、标签或默认分区到期时间，但可以在创建数据集后添加说明、标签和默认分区到期时间。

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 文件设置默认位置值。

  注意：如果选择 **EU** 作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据在服务专用条款中定义。

• integer1 是新创建的表的默认生命周期（以秒为单位）。最小值为 3600 秒（一小时）。到期时间以当前时间加上这个整数值为准。在数据集中创建的任何表都会在创建之时起的 [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

注意：使用 CLI 创建数据集时，您不能添加标签，但可以在创建数据集后添加标签。

您可以输入 bq ls 命令来确认数据集是否已创建。另外，您可以使用以下格式在创建新数据集时创建表：bq mk -t dataset.table。如需详细了解如何创建表，请参阅创建表。

API

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

C#

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

在 GitHub 上查看 反馈

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

在 GitHub 上查看 反馈

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

在 GitHub 上查看 反馈

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

在 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

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

在 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

后续步骤

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