创建数据集

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

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

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

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

数据集限制

BigQuery 数据集有以下限制：

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

命名数据集

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

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

注意：在 Cloud Console 中，导航窗格中会隐藏以下划线开头的数据集。即使这些数据集不可见，您仍然可以在这些数据集中查询表和视图。

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

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

所需权限

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

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

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

创建数据集

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

控制台

在 Cloud Console 中打开 BigQuery 页面。

转到 BigQuery 页面
在浏览器面板中，选择您要在其中创建数据集的项目。

注意：默认体验是预览版 Cloud Console。如果您点击隐藏预览功能以转到正式版 Cloud Console，则改为执行以下步骤：在导航面板的资源部分中，选择项目。
在详细信息面板中，点击创建数据集。
在创建数据集页面中执行以下操作：
- 对于数据集 ID，输入唯一的数据集名称。
- （可选）对于数据位置，为数据集选择一个地理位置。如果将值设置为默认，则位置会设置为 US。创建数据集后，就无法再更改此位置。
  
  注意：如果您选择 EU 或欧盟地区作为数据集位置，则核心 BigQuery 客户数据会驻留在欧盟。核心 BigQuery 客户数据是在服务专用条款中定义的。
- 对于默认表到期时间，请选择以下任一选项：
  - 永不：（默认）永不自动删除在数据集中创建的表。您必须手动删除这些表。
  - 创建表后的天数：此值确定何时删除数据集中新创建的表。如果您在创建表时未设置表到期时间，则系统会应用此值。
- 点击创建数据集。

bq

结合使用 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 秒（一小时）。到期时间以当前时间加上这个整数值为准。在数据集中创建的任何表都会在创建之时起的 integer1 秒后删除。如果您在创建表时未设置表到期时间，则系统会应用此值。
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

您可以输入 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 上查看反馈

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

后续步骤

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