创建和使用表

本文档介绍了如何在 BigQuery 中创建和使用标准（内置）表。如需了解如何创建其他表类型，请参阅以下内容：

创建表后，您可执行以下操作：

  • 控制对表数据的访问权限
  • 获取有关表的信息
  • 列出数据集中的表
  • 获取表元数据

如需详细了解如何管理表（包括更新表属性、复制表和删除表），请参阅管理表。

准备工作

在 BigQuery 中创建表之前，请先进行以下操作：

表命名

在 BigQuery 中创建表时，数据集中每个表的名称都必须具有唯一性。表名称可：

  • 包含的字符总数不超过 1024 个 UTF-8 字节。
  • 包含类别 L（字母）、M（符号）、N（数字）、Pc（连接符，包括下划线）、Pd（短划线）、Zs（空格）中的 Unicode 字符。如需了解详情，请参阅常规类别。

以下是有效表名称的所有示例：table 01、ग्राहक、00_お客様、étudiant-01。

注意事项：

  • 默认情况下，表名称区分大小写。mytable 和 MyTable 可以位于同一数据集中，除非它们属于关闭区分大小写的数据集。
  • 某些表名称和表名称前缀已被预留。如果您收到错误，表示您的表名称或前缀已被预留，请选择其他名称并重试。

  • 如果您在序列中添加多个点运算符 (.)，则系统会隐式删除重复的运算符。

    例如，project_name....dataset_name..table_name

    会变为 project_name.dataset_name.table_name

创建表

您可以通过以下方式在 BigQuery 中创建表：

  • 使用 Google Cloud 控制台或 bq 命令行工具 bq mk 命令手动创建。
  • 调用 tables.insert API 方法以编程方式创建。
  • 使用客户端库。
  • 使用查询结果。
  • 通过定义引用外部数据源的表。
  • 在加载数据时。
  • 使用 CREATE TABLE 数据定义语言 (DDL) 语句。

所需权限

如需创建表，您需要拥有以下 IAM 权限：

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.jobs.create

此外，您可能需要拥有 bigquery.tables.getData 权限才能访问您写入表中的数据。

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

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin（包括 bigquery.jobs.create 权限）
  • roles/bigquery.user（包括 bigquery.jobs.create 权限）
  • roles/bigquery.jobUser（包括 bigquery.jobs.create 权限）

此外，如果您拥有 bigquery.datasets.create 权限，则可以在您创建的数据集中创建和更新表。

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

创建具有架构定义的空表

您可以通过以下方式创建具有架构定义的空表：

  • 使用 Google Cloud 控制台输入架构。
  • 使用 bq 命令行工具以内嵌方式提供架构。
  • 使用 bq 命令行工具提交 JSON 架构文件。
  • 调用 API 的 tables.insert 方法时，在表资源中提供架构。

如需详细了解如何指定表架构，请参阅指定架构。

创建表后，您可以向表加载数据，或通过写入查询结果来填充表。

如需创建具有架构定义的空表，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在浏览器窗格中，展开您的项目，然后选择数据集。
  3. 在数据集信息部分中，点击 创建表。
  4. 在创建表面板中，指定以下详细信息：
    1. 在来源部分，在基于以下数据源创建表列表中选择空表。
    2. 在目标部分，指定以下详细信息：
      1. 在数据集部分，选择您要在其中创建表的数据集。
      2. 在表字段中，输入您要创建的表的名称。
      3. 确认表类型字段是否设置为原生表。
    3. 在架构部分，输入架构定义。您可以使用以下任一方法手动输入架构信息：
      • 选项 1：点击以文本形式修改，并以 JSON 数组的形式粘贴架构。使用 JSON 数组时，您要使用与创建 JSON 架构文件相同的流程生成架构。您可以输入以下命令，以 JSON 格式查看现有表的架构：
            bq show --format=prettyjson dataset.table
      • 选项 2：点击 添加字段，然后输入表架构。指定每个字段的名称、类型和模式。
    4. 可选：指定分区和聚簇设置。如需了解详情，请参阅创建分区表和创建和使用聚簇表。
    5. 可选：如果要使用客户管理的加密密钥，在高级选项部分，选择使用客户管理的加密密钥 (CMEK) 选项。默认情况下，BigQuery 会使用 Google 管理的密钥对以静态方式存储的客户内容进行加密。
    6. 点击创建表。

SQL

以下示例会创建一个名为 newtable 的表，该表将于 2023 年 1 月 1 日到期：

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中，输入以下语句：

    CREATE TABLE mydataset.newtable (
  x INT64 OPTIONS (description = 'An optional INTEGER field'),
  y STRUCT <
    a ARRAY <STRING> OPTIONS (description = 'A repeated STRING field'),
    b BOOL
  >
) OPTIONS (
    expiration_timestamp = TIMESTAMP '2023-01-01 00:00:00 UTC',
    description = 'a table that expires in 2023',
    labels = [('org_unit', 'development')]);

  3. 点击 运行。

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

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 使用带有 --table 或 -t 标志的 bq mk 命令。您可以内嵌方式或通过 JSON 架构文件提供表的架构信息。可选参数包括：

    • --expiration
    • --description
    • --time_partitioning_field
    • --time_partitioning_type
    • --range_partitioning
    • --clustering_fields
    • --destination_kms_key
    • --label

    此处未演示 --time_partitioning_field、--time_partitioning_type、--range_partitioning、--clustering_fields 和 --destination_kms_key。如需详细了解这些可选参数，请访问以下链接：

    • 如需详细了解 --time_partitioning_field、--time_partitioning_type 和 --range_partitioning，请参阅分区表。
    • 如需详细了解 --clustering_fields，请参阅聚簇表。
    • 如需详细了解 --destination_kms_key，请参阅客户管理的加密密钥。

    如果您要在非默认项目中创建表，请按以下格式将相应项目 ID 添加到数据集中：project_id:dataset。

    如需在具有架构定义的现有数据集中创建空表，请输入以下命令：

    bq mk \
--table \
--expiration integer \
--description description \
--label key_1:value_1 \
--label key_2:value_2 \
project_id:dataset.table \
schema

    替换以下内容：

    • integer 是表的默认生命周期（以秒为单位）。最小值为 3600 秒（一小时）。到期时间以当前世界协调时间 (UTC) 加上这个整数值为准。如果您在创建表时设置了该表的到期时间，则系统会忽略数据集的默认表到期时间设置。
    • description 是加引号的表说明。
    • key_1：value_1 和 key_2：value_2 是指定标签的键值对。
    • project_id 是项目 ID。
    • dataset 是您的项目中的数据集。
    • table 是您要创建的表的名称。
    • schema 是采用 field:data_type,field:data_type 格式的内嵌架构定义，或者是本地机器上 JSON 架构文件的路径。

    使用命令行指定架构时，您不能添加 RECORD (STRUCT) 类型和列说明，也不能指定列的模式。所有模式均默认为 NULLABLE。如需添加说明、模式和 RECORD 类型，请改为提供 JSON 架构文件。

    示例：

    输入以下命令，使用内嵌架构定义创建表。该命令会在默认项目的 mydataset 中创建一个名为 mytable 的表。表到期时间设为 3600 秒（1 小时），说明设为 This is my table，标签设为 organization:development。该命令使用 -t 快捷键代替 --table。该架构以内嵌方式指定为：qtr:STRING,sales:FLOAT,year:STRING。

    bq mk \
 -t \
 --expiration 3600 \
 --description "This is my table" \
 --label organization:development \
 mydataset.mytable \
 qtr:STRING,sales:FLOAT,year:STRING

    输入以下命令以使用 JSON 架构文件创建表。该命令会在默认项目的 mydataset 中创建一个名为 mytable 的表。表到期时间设为 3600 秒（1 小时），说明设为 This is my table，标签设为 organization:development。架构文件的路径为 /tmp/myschema.json。

    bq mk \
 --table \
 --expiration 3600 \
 --description "This is my table" \
 --label organization:development \
 mydataset.mytable \
 /tmp/myschema.json

    输入以下命令以使用 JSON 架构文件创建表。该命令会在 myotherproject 的 mydataset 中创建一个名为 mytable 的表。表到期时间设为 3600 秒（1 小时），说明设为 This is my table，标签设为 organization:development。架构文件的路径为 /tmp/myschema.json。

    bq mk \
 --table \
 --expiration 3600 \
 --description "This is my table" \
 --label organization:development \
 myotherproject:mydataset.mytable \
 /tmp/myschema.json

    创建表后，您可以更新表的到期时间、说明和标签，也可以修改架构定义。

Terraform

使用 google_bigquery_table 资源。

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

创建表

以下示例创建了一个名为 mytable 的表。

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"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

创建表并授予访问权限

以下示例创建一个名为 mytable 的表，然后使用 google_bigquery_table_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"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

}

data "google_iam_policy" "default" {
  binding {
    role = "roles/bigquery.dataOwner"
    members = [
      "user:raha@altostrat.com",
    ]
  }
}

resource "google_bigquery_table_iam_policy" "policy" {
  dataset_id  = google_bigquery_table.default.dataset_id
  table_id    = google_bigquery_table.default.table_id
  policy_data = data.google_iam_policy.default.policy_data
}

使用客户管理的加密密钥创建表

以下示例创建了一个名为 mytable 的表，并且还会使用 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

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

resource "google_bigquery_table" "default" {
  dataset_id          = google_bigquery_dataset.default.dataset_id
  table_id            = "mytable"
  deletion_protection = false # set to "true" in production

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "mode": "NULLABLE",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  }
]
EOF

  encryption_configuration {
    kms_key_name = google_kms_crypto_key.crypto_key.id
  }

  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 显示“应用完成！”消息。

  3. 打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

API

使用已定义的表资源调用 tables.insert 方法。

C#

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

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


using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

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

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); 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.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table 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 createTable() {
  // Creates a new table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const schema = 'Name:string, Age:integer, Weight:float, IsMagic:boolean';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created.`);
}

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';
// $tableId = 'The BigQuery table ID';
// $fields = [
//    [
//        'name' => 'field1',
//        'type' => 'string',
//        'mode' => 'required'
//    ],
//    [
//        'name' => 'field2',
//        'type' => 'integer'
//    ],
//];

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$schema = ['fields' => $fields];
$table = $dataset->createTable($tableId, ['schema' => $schema]);
printf('Created table %s' . PHP_EOL, $tableId);

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Ruby

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

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

require "google/cloud/bigquery"

def create_table dataset_id = "my_dataset"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "my_table"

  table = dataset.create_table table_id do |updater|
    updater.string  "full_name", mode: :required
    updater.integer "age",       mode: :required
  end

  puts "Created table: #{table_id}"
end

创建没有架构定义的空表

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.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create a table without schema
public class CreateTableWithoutSchema {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createTableWithoutSchema(datasetName, tableName);
  }

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

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(Schema.of());
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

基于查询结果创建表

如需基于查询结果创建表，请将结果写入一个目标表。

控制台

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

    转到 BigQuery 页面

  2. 在浏览器面板中，展开您的项目并选择数据集。

  3. 输入有效的 SQL 查询。

  4. 点击更多，然后选择查询设置。

    查询设置

  5. 选择为查询结果设置目标表选项。

    设置目标位置

  6. 在目标部分，选择要在其中创建表的数据集，然后选择表 ID。

  7. 在目标表的写入设置部分，选择以下选项之一：

    • 只写入空白表 - 仅在表为空时才将查询结果写入表。
    • 附加到表 - 将查询结果附加到现有表。
    • 覆盖表 - 使用查询结果覆盖名称相同的现有表。

  8. 可选：对于数据位置，请选择您的位置。

  9. 要更新查询设置，请点击保存。

  10. 点击运行。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果您在运行查询之前忘记指定目标表，可以点击编辑器上方的保存结果按钮，将缓存结果表复制到永久表。

SQL

以下示例使用 CREATE TABLE 语句从公共 bikeshare_trips 表中的数据创建 trips 表：

  1. 在 Google Cloud 控制台中，转到 BigQuery 页面。

    转到 BigQuery

  2. 在查询编辑器中，输入以下语句：

    CREATE TABLE mydataset.trips AS (
  SELECT
    bike_id,
    start_time,
    duration_minutes
  FROM
    bigquery-public-data.austin_bikeshare.bikeshare_trips
);

  3. 点击 运行。

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

如需了解详情，请参阅从现有表创建新表。

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 输入 bq query 命令，并指定 --destination_table 标志以根据查询结果创建永久表。指定 use_legacy_sql=false 标志以使用 GoogleSQL 语法。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 ID 添加到数据集名称：project_id:dataset。

    可选：提供 --location 标志并将其值设置为您所在的位置。

    如需控制现有目标表的写入处置方式，请指定以下可选标志之一：

    • --append_table：如果目标表存在，指定该标志可将查询结果附加到该表。

    • --replace：如果目标表存在，指定该标志可使用查询结果覆盖该表。

      bq --location=location query \
--destination_table project_id:dataset.table \
--use_legacy_sql=false 'query'

      替换以下内容：

    • location 是用于处理查询的位置的名称。--location 标志是可选的。例如，如果您在东京区域使用 BigQuery，可将该标志的值设置为 asia-northeast1。您可以使用 .bigqueryrc 文件设置位置的默认值。

    • project_id 是项目 ID。

    • dataset 是数据集名称，该数据集包含您要向其中写入查询结果的表。

    • table 是您要向其中写入查询结果的表的名称。

    • query 是采用 GoogleSQL 语法的查询。

      如果未指定“写入处置方式”标志，则默认行为是仅在表为空时写入结果。如果表已存在且非空，则系统会返回以下错误：`BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1': Already Exists: Table project_id:dataset.table。

      示例：

      输入以下命令可将查询结果写入 mydataset 中名为 mytable 的目标表。该数据集属于默认项目。由于命令中未指定“写入处置方式”标志，因此该表必须为新表或空表。否则，系统将返回 Already exists 错误。该查询从美国名字数据公共数据集中检索数据。

      bq query \
--destination_table mydataset.mytable \
--use_legacy_sql=false \
'SELECT
name,
number
FROM
`bigquery-public-data`.usa_names.usa_1910_current
WHERE
gender = "M"
ORDER BY
number DESC'

      输入以下命令可使用查询结果覆盖 mydataset 中名为 mytable 的目标表。该数据集属于默认项目。该命令使用 --replace 标志覆盖目标表。

      bq query \
--destination_table mydataset.mytable \
--replace \
--use_legacy_sql=false \
'SELECT
name,
number
FROM
`bigquery-public-data`.usa_names.usa_1910_current
WHERE
gender = "M"
ORDER BY
number DESC'

      输入以下命令可将查询结果附加到 mydataset 中名为 mytable 的目标表。该数据集属于 my-other-project，而非默认项目。该命令使用 --append_table 标志将查询结果附加到目标表。

      bq query \
--append_table \
--use_legacy_sql=false \
--destination_table my-other-project:mydataset.mytable \
'SELECT
name,
number
FROM
`bigquery-public-data`.usa_names.usa_1910_current
WHERE
gender = "M"
ORDER BY
number DESC'

      各示例的输出如下所示。为了方便阅读，部分输出已被截断。

      Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE
+---------+--------+
|  name   | number |
+---------+--------+
| Robert  |  10021 |
| John    |   9636 |
| Robert  |   9297 |
| ...              |
+---------+--------+

API

如需将查询结果保存到永久表中，请调用 jobs.insert 方法，配置 query 作业，并添加 destinationTable 属性的值。如需控制现有目标表的写入处置方式，请配置 writeDisposition 属性。

如需控制查询作业的处理位置，请在作业资源的 jobReference 部分中指定 location 属性。

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryWithDestination demonstrates saving the results of a query to a specific table by setting the destination
// via the API properties.
func queryWithDestination(w io.Writer, projectID, destDatasetID, destTableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query("SELECT 17 as my_col")
	q.Location = "US" // Location must match the dataset(s) referenced in query.
	q.QueryConfig.Dst = client.Dataset(destDatasetID).Table(destTableID)
	// Run the query and print results when the query job is completed.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

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

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

如需将查询结果保存到永久表中，请在 QueryJobConfiguration 中将目标表设置为所需的 TableId。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;

public class SaveQueryToTable {

  public static void runSaveQueryToTable() {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    String destinationTable = "MY_TABLE";
    String destinationDataset = "MY_DATASET";

    saveQueryToTable(destinationDataset, destinationTable, query);
  }

  public static void saveQueryToTable(
      String destinationDataset, String destinationTableId, String query) {
    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();

      // Identify the destination table
      TableId destinationTable = TableId.of(destinationDataset, destinationTableId);

      // Build the query job
      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDestinationTable(destinationTable).build();

      // Execute the query.
      bigquery.query(queryConfig);

      // The results are now saved in the destination table.

      System.out.println("Saved query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Saved query did not run \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function queryDestinationTable() {
  // Queries the U.S. given names dataset for the state of Texas
  // and saves results to permanent table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Create destination table reference
  const dataset = bigquery.dataset(datasetId);
  const destinationTable = dataset.table(tableId);

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    destination: destinationTable,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  console.log(`Job ${job.id} started.`);
  console.log(`Query results loaded to table ${destinationTable.id}`);
}

Python

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

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

如需将查询结果保存到永久表中，请创建 QueryJobConfig 并将目标设置为所需的 TableReference。将作业配置传递给查询方法。 
from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the destination table.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.QueryJobConfig(destination=table_id)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.
query_job.result()  # Wait for the job to complete.

print("Query results loaded to the table {}".format(table_id))

创建引用外部数据源的表

外部数据源是可以直接从 BigQuery 查询的数据源，即使数据未存储在 BigQuery 存储中也是如此。例如，您可能在其他 Google Cloud 数据库、Cloud Storage 中的文件或其他云产品中拥有您想在 BigQuery 中分析但尚未准备好进行迁移的数据。

如需了解详情，请参阅外部数据源简介。

在加载数据时创建表

将数据加载到 BigQuery 时，可以将数据加载到新的表或分区中，也可以覆盖或附加到现有的表或分区。无需在加载数据前创建空表。您可以同时创建新表和加载数据。

将数据加载到 BigQuery 时，可以提供表或分区架构；对于支持的数据格式，可以使用架构自动检测。

要详细了解如何加载数据，请参阅将数据加载到 BigQuery 简介。

控制对表的访问权限

如需配置对表和视图的访问权限，您可以在以下级层为实体授予 IAM 角色，这些级层按照允许的资源范围从大到小依次排列：

您还可以使用以下方法限制表中的数据访问权限：

对受 IAM 保护的任何资源的访问权限具有附加性。例如，如果某个实体没有项目等较高级层的访问权限，您可以在数据集级层向该实体授予访问权限，然后该实体便将有权访问该数据集中的表和视图。同样，如果实体没有较高级层或数据集级层的访问权限，您可以在表或视图级层向该实体授予访问权限。

在 Google Cloud 资源层次结构中授予更高级层（例如项目、文件夹或组织级层）的 IAM 角色，使实体可访问一组广泛的资源。例如，在项目级为实体授予角色会为该实体提供整个项目中所有数据集的访问权限。

在数据集级层授予角色可指定允许实体对该特定数据集中的表和视图执行的操作，即使实体没有更高级层的访问权限也可执行这些操作。如需详细了解如何配置数据集级层的访问权限控制，请参阅控制对数据集的访问权限。

在表或视图级层授予角色可指定允许实体对特定表和视图执行的操作，即使实体没有更高级层的访问权限也可执行这些操作。如需了解如何配置表级层的访问权限控制，请参阅控制对表和视图的访问权限。

您还可以创建 IAM 自定义角色。如果创建自定义角色，则您授予的权限取决于您希望实体能够执行的具体操作。

您无法对受 IAM 保护的任何资源设置“拒绝”权限。

如需详细了解角色和权限，请参阅 IAM 文档中的了解角色以及 BigQuery IAM 角色和权限。

获取表的相关信息

您可以通过以下方式获取表的相关信息或元数据：

  • 使用 Google Cloud 控制台。
  • 使用 bq 命令行工具 bq show 命令。
  • 调用 tables.get API 方法。
  • 使用客户端库。
  • 查询 INFORMATION_SCHEMA 视图（Beta 版。

所需权限

如需获取有关表的信息，您至少必须获得 bigquery.tables.get 权限。以下预定义的 IAM 角色包含 bigquery.tables.get 权限：

  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataOwner
  • bigquery.dataEditor
  • bigquery.admin

此外，如果用户具有 bigquery.datasets.create 权限，则当该用户创建数据集时，系统会为其授予该数据集的 bigquery.dataOwner 访问权限。借助 bigquery.dataOwner 访问权限，用户可以检索表元数据。

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

获取表信息

要获取表的相关信息，请执行以下操作：

控制台

  1. 在导航面板的资源部分中，展开您的项目，然后选择数据集。

  2. 点击数据集名称，将其展开。此时会显示数据集中的表和视图。

  3. 点击表名称。

  4. 在详细信息面板中，点击详细信息以显示表的说明和表信息。

  5. （可选）切换到架构标签页以查看表的架构定义。

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 发出 bq show 命令可显示所有表信息。使用 --schema 标志可仅显示表的架构信息。--format 标志可用于控制输出。

    如果您要获取非默认项目中的表信息，请按以下格式将相应项目 ID 添加到数据集：project_id:dataset。

    bq show \
--schema \
--format=prettyjson \
project_id:dataset.table

    其中：

    • project_id 是您的项目 ID。
    • dataset 是数据集的名称。
    • table 是表的名称。

    示例：

    输入以下命令可显示 mydataset 中有关 mytable 的所有信息。mydataset 属于默认项目。

    bq show --format=prettyjson mydataset.mytable

    输入以下命令可显示 mydataset 中有关 mytable 的所有信息。mydataset 在 myotherproject 中，不在默认项目中。

    bq show --format=prettyjson myotherproject:mydataset.mytable

    输入以下命令可仅显示 mydataset 中有关 mytable 的架构信息。mydataset 属于 myotherproject，而非默认项目。

    bq show --schema --format=prettyjson myotherproject:mydataset.mytable

API

调用 tables.get 方法并提供所有相关参数。

Go

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

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

import (
	"context"
	"fmt"
	"io"

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

// printTableInfo demonstrates fetching metadata from a table and printing some basic information
// to an io.Writer.
func printTableInfo(w io.Writer, projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
	if err != nil {
		return err
	}
	// Print basic information about the table.
	fmt.Fprintf(w, "Schema has %d top-level fields\n", len(meta.Schema))
	fmt.Fprintf(w, "Description: %s\n", meta.Description)
	fmt.Fprintf(w, "Rows in managed storage: %d\n", meta.NumRows)
	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.Table;
import com.google.cloud.bigquery.TableId;

public class GetTable {

  public static void runGetTable() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery_public_data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    getTable(projectId, datasetName, tableName);
  }

  public static void getTable(String projectId, String datasetName, String tableName) {
    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();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      Table table = bigquery.getTable(tableId);
      System.out.println("Table info: " + table.getDescription());
    } catch (BigQueryException e) {
      System.out.println("Table not retrieved. \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function getTable() {
  // Retrieves table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Retrieve table reference
  const dataset = bigquery.dataset(datasetId);
  const [table] = await dataset.table(tableId).get();

  console.log('Table:');
  console.log(table.metadata.tableReference);
}
getTable();

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';
//$tableId   = 'The BigQuery table ID';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);

Python

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

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


from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)  # Make an API request.

# View table properties
print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)
print("Table schema: {}".format(table.schema))
print("Table description: {}".format(table.description))
print("Table has {} rows".format(table.num_rows))

使用 INFORMATION_SCHEMA 获取表信息

INFORMATION_SCHEMA 是一系列视图，可让您访问数据集、例程、表、视图、作业、预留、流式数据的相关元数据。

您可以查询以下视图以获取表信息：

  • 使用 INFORMATION_SCHEMA.TABLES 和 INFORMATION_SCHEMA.TABLE_OPTIONS 视图检索关于项目中的表和视图的元数据。
  • 使用 INFORMATION_SCHEMA.COLUMNS 和 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图检索关于表中的列（字段）的元数据。
  • 使用 INFORMATION_SCHEMA.TABLE_STORAGE 视图检索关于表当前和历史存储空间用量的元数据。

TABLES 和 TABLE_OPTIONS 视图还包含关于视图的概要信息。如需查看详细信息，请改为查询 INFORMATION_SCHEMA.VIEWS 视图。

TABLES 视图

查询 INFORMATION_SCHEMA.TABLES 视图时，查询结果为数据集中的每个表或视图返回一行。如需详细了解视图，请改为查询 INFORMATION_SCHEMA.VIEWS 视图。

INFORMATION_SCHEMA.TABLES 视图具有如下架构：

列名 数据类型 值
table_catalog STRING 该数据集所属项目的项目 ID。
table_schema STRING 包含表或视图的数据集的名称，也称为 datasetId。
table_name STRING 表或视图的名称，也称为 tableId。
table_type STRING 表类型；以下项之一：
is_insertable_into STRING YES 或 NO，具体取决于表是否支持 DML INSERT 语句
is_typed STRING 值始终为 NO
creation_time TIMESTAMP 表的创建时间
base_table_catalog STRING 对于表克隆和表快照，此字段为基表的项目。仅适用于 table_type 设置为 CLONE 或 SNAPSHOT 的表。
base_table_schema STRING 对于表克隆和表快照，此字段为基表的数据集。仅适用于 table_type 设置为 CLONE 或 SNAPSHOT 的表。
base_table_name STRING 对于表克隆和表快照，此字段为基表的名称。仅适用于 table_type 设置为 CLONE 或 SNAPSHOT 的表。
snapshot_time_ms TIMESTAMP 对于表克隆和表快照，在基表上运行克隆或快照操作的时间创建这个表。如果使用时间旅行，则此字段包含时间旅行时间戳。否则，snapshot_time_ms 字段与 creation_time 字段相同。仅适用于 table_type 设置为 CLONE 或 SNAPSHOT 的表。
replica_source_catalog STRING 对于具体化视图副本，这是基础具体化视图的项目。
replica_source_schema STRING 对于具体化视图副本，此字段为基本具体化视图的数据集。
replica_source_name STRING 对于具体化视图副本，此字段为基本具体化视图的名称。
replication_status STRING 对于具体化视图副本，从基础具体化视图到具体化视图副本的复制状态；以下项之一：
  • REPLICATION_STATUS_UNSPECIFIED
  • ACTIVE：复制正在进行，没有出现错误
  • SOURCE_DELETED：来源具体化视图已删除
  • PERMISSION_DENIED：来源具体化视图尚未在包含创建具体化视图的查询中使用的来源 Amazon S3 BigLake 表的数据集上授权。
  • UNSUPPORTED_CONFIGURATION：副本的前提条件（来源具体化视图授权除外）存在问题。
replication_error STRING 如果 replication_status 表明具体化视图副本存在复制问题，则 replication_error 会提供有关该问题的更多详细信息。
ddl STRING 可用于重新创建表的 DDL 语句，例如 CREATE TABLE 或 CREATE VIEW
default_collation_name STRING 默认排序规则规范的名称（如果存在），否则为 NULL。
upsert_stream_apply_watermark TIMESTAMP 对于使用变更数据捕获 (CDC) 的表，这是上次应用行修改的时间。如需了解详情，请参阅监控表插入/更新操作进度。

示例

示例 1：

以下示例会检索名为 mydataset 的数据集中所有表的表元数据。返回的元数据包括默认项目的 mydataset 中所有类型的表。

mydataset 包含以下表：

  • mytable1：标准 BigQuery 表
  • myview1：BigQuery 视图

如需对非默认项目运行查询，请按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应的项目 ID 添加到数据集，例如 `myproject`.mydataset.INFORMATION_SCHEMA.TABLES。

SELECT
  table_catalog, table_schema, table_name, table_type,
  is_insertable_into, creation_time, ddl
FROM
  mydataset.INFORMATION_SCHEMA.TABLES;

结果类似于以下内容。为改善可读性，结果中没有保留某些列。

+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |                     ddl                     |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
| myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 | CREATE TABLE `myproject.mydataset.mytable1` |
|                |               |                |            |                    |                     | (                                           |
|                |               |                |            |                    |                     |   id INT64                                  |
|                |               |                |            |                    |                     | );                                          |
| myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 | CREATE VIEW `myproject.mydataset.myview1`   |
|                |               |                |            |                    |                     | AS SELECT 100 as id;                        |
+----------------+---------------+----------------+------------+--------------------+---------------------+---------------------------------------------+
示例 2：

以下示例从 INFORMATION_SCHEMA.TABLES 视图中检索类型为 CLONE 或 SNAPSHOT 的所有表的元数据。返回的元数据包括默认项目的 mydataset 中的表。

如需对非默认项目运行查询，请按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应的项目 ID 添加到数据集，例如 `myproject`.mydataset.INFORMATION_SCHEMA.TABLES。

  SELECT
    table_name, table_type, base_table_catalog,
    base_table_schema, base_table_name, snapshot_time_ms
  FROM
    mydataset.INFORMATION_SCHEMA.TABLES
  WHERE
    table_type = 'CLONE'
  OR
    table_type = 'SNAPSHOT';

结果类似于以下内容。为改善可读性，结果中没有保留某些列。

  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | table_name   | table_type | base_table_catalog | base_table_schema | base_table_name | snapshot_time_ms    |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+
  | items_clone  | CLONE      | myproject          | mydataset         | items           | 2018-10-31 22:40:05 |
  | orders_bk    | SNAPSHOT   | myproject          | mydataset         | orders          | 2018-11-01 08:22:39 |
  +--------------+------------+--------------------+-------------------+-----------------+---------------------+

示例 3：

以下示例从 census_bureau_usa 数据集中 population_by_zip_2010 表的 INFORMATION_SCHEMA.TABLES 视图中检索 table_name 和 ddl 列。此数据集是 BigQuery 公共数据集计划的一部分。

由于您查询的表属于其他项目，因此您应按以下格式将相应项目 ID 添加到数据集：`project_id`.dataset.INFORMATION_SCHEMA.view。在此示例中，该值为 `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES。

SELECT
  table_name, ddl
FROM
  `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES
WHERE
  table_name = 'population_by_zip_2010';

结果类似于以下内容：

+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|       table_name       |                                                                                                            ddl                                                                                                             |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| population_by_zip_2010 | CREATE TABLE `bigquery-public-data.census_bureau_usa.population_by_zip_2010`                                                                                                                                               |
|                        | (                                                                                                                                                                                                                          |
|                        |   geo_id STRING OPTIONS(description="Geo code"),                                                                                                                                                                           |
|                        |   zipcode STRING NOT NULL OPTIONS(description="Five digit ZIP Code Tabulation Area Census Code"),                                                                                                                          |
|                        |   population INT64 OPTIONS(description="The total count of the population for this segment."),                                                                                                                             |
|                        |   minimum_age INT64 OPTIONS(description="The minimum age in the age range. If null, this indicates the row as a total for male, female, or overall population."),                                                          |
|                        |   maximum_age INT64 OPTIONS(description="The maximum age in the age range. If null, this indicates the row as having no maximum (such as 85 and over) or the row is a total of the male, female, or overall population."), |
|                        |   gender STRING OPTIONS(description="male or female. If empty, the row is a total population summary.")                                                                                                                    |
|                        | )                                                                                                                                                                                                                          |
|                        | OPTIONS(                                                                                                                                                                                                                   |
|                        |   labels=[("freebqcovid", "")]                                                                                                                                                                                             |
|                        | );                                                                                                                                                                                                                         |
+------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

TABLE_OPTIONS 视图

当您查询 INFORMATION_SCHEMA.TABLE_OPTIONS 视图时，对于数据集中的每个表或视图，查询结果都会为每个选项返回一行结果。如需详细了解视图，请改为查询 INFORMATION_SCHEMA.VIEWS 视图。

INFORMATION_SCHEMA.TABLE_OPTIONS 视图具有如下架构：

列名 数据类型 值
TABLE_CATALOG STRING 该数据集所属项目的项目 ID
TABLE_SCHEMA STRING 包含表或视图的数据集的名称，也称为 datasetId
TABLE_NAME STRING 表或视图的名称，也称为 tableId
OPTION_NAME STRING 选项表中的一个名称值
OPTION_TYPE STRING 选项表中的一个数据类型值
OPTION_VALUE STRING 选项表中的一个值选项
选项表
OPTION_NAME OPTION_TYPE OPTION_VALUE
partition_expiration_days FLOAT64 分区表中所有分区的默认生命周期（以天为单位）
expiration_timestamp TIMESTAMP 此表的到期时间
kms_key_name STRING 用于加密表的 Cloud KMS 密钥的名称
friendly_name STRING 表的描述性名称
description STRING 表的说明
labels ARRAY<STRUCT<STRING, STRING>> 一组 STRUCT，表示表的标签
require_partition_filter BOOL 对于表执行的查询是否需要分区过滤条件
enable_refresh BOOL 此标志表示是否为具体化视图启用自动刷新
refresh_interval_minutes FLOAT64 具体化视图的刷新频率

对于外部表，可以使用以下选项：

选项
allow_jagged_rows

BOOL

如果为 true，则表示允许末尾处缺少可选列的行。

适用于 CSV 数据。
allow_quoted_newlines

BOOL

如果为 true，则表示文件中允许引号括起来的数据部分中包含换行符。

适用于 CSV 数据。
bigtable_options

STRING

仅在创建 Bigtable 外部表时才需要。

指定 Bigtable 外部表的架构（采用 JSON 格式）。

如需查看 Bigtable 表定义选项列表，请参阅 REST API 参考文档中的 BigtableOptions。
compression

STRING

数据源的压缩类型。支持的值包括：GZIP。如果未指定，则数据源未压缩。

适用于 CSV 和 JSON 数据。
decimal_target_types

ARRAY<STRING>

确定如何转换 Decimal 类型。相当于 ExternalDataConfiguration.decimal_target_types

示例：["NUMERIC", "BIGNUMERIC"]。
description

STRING

此表的说明。
enable_list_inference

BOOL

如果为 true，则专门为 Parquet LIST 逻辑类型使用架构推断。

适用于 Parquet 数据。
enable_logical_types

BOOL

如果为 true，则将 Avro 逻辑类型转换为相应的 SQL 类型。如需了解详情，请参阅逻辑类型。

适用于 Avro 数据。
encoding

STRING

数据的字符编码。支持的值包括：UTF8（或 UTF-8）、ISO_8859_1（或 ISO-8859-1）。

适用于 CSV 数据。
enum_as_string

BOOL

如果为 true，则默认将 Parquet ENUM 逻辑类型推断为 STRING 而不是 BYTES。

适用于 Parquet 数据。
expiration_timestamp

TIMESTAMP

此表的到期时间。如果未指定，则该表不会过期。

示例："2025-01-01 00:00:00 UTC"。
field_delimiter

STRING

CSV 文件中的字段的分隔符。

适用于 CSV 数据。
format

STRING

外部数据的格式。 支持的 CREATE EXTERNAL TABLE 值包括：AVRO、CLOUD_BIGTABLE、CSV、DATASTORE_BACKUP、DELTA_LAKE（预览版）、GOOGLE_SHEETS、NEWLINE_DELIMITED_JSON（或 JSON）、ORC、PARQUET。

支持的 LOAD DATA 值包括：AVRO、CSV、DELTA_LAKE（预览版）、NEWLINE_DELIMITED_JSON（或 JSON）、ORC、PARQUET。

值 JSON 相当于 NEWLINE_DELIMITED_JSON。
hive_partition_uri_prefix

STRING

分区键编码开始之前所有源 URI 的通用前缀。仅适用于 Hive 分区的外部表。

适用于 Avro、CSV、JSON、Parquet、ORC 数据。

示例："gs://bucket/path"。
file_set_spec_type

STRING

指定如何解读加载作业和外部表的源 URI。目前为预览版。

支持的值包括：

  • FILE_SYSTEM_MATCH。通过列出对象存储中的文件来扩展源 URI。如果未设置 FileSetSpecType，则这是默认行为。
  • NEW_LINE_DELIMITED_MANIFEST。表示提供的 URI 是以换行符分隔的清单文件，每行一个 URI。清单文件不支持通配符 URI。

例如，如果您的源 URI 为 "gs://bucket/path/file" 且 file_set_spec_type 为 FILE_SYSTEM_MATCH，则该文件会直接用作数据文件。如果 file_set_spec_type 为 NEW_LINE_DELIMITED_MANIFEST，则文件中的每一行都会被解读为指向一个数据文件的 URI。
ignore_unknown_values

BOOL

如果为 true，则系统会忽略表架构中不存在的额外值，而不返回错误。

适用于 CSV 和 JSON 数据。
json_extension

STRING

对于 JSON 数据，指示特定的 JSON 交换格式。如果未指定，BigQuery 会以通用 JSON 记录的形式读取数据。

支持的值包括：
GEOJSON。以换行符分隔的 GeoJSON 数据。如需了解详情，请参阅根据以换行符分隔的 GeoJSON 文件创建外部表。
max_bad_records

INT64

读取数据时要忽略的错误记录数上限。

适用于 CSV、JSON 和 Google 表格数据。
max_staleness

INTERVAL

适用于 BigLake 表和对象表。

指定对表执行的操作是否使用缓存的元数据，以及操作使用的缓存元数据的新鲜度。

如需停用元数据缓存，请指定 0。这是默认设置。

如需启用元数据缓存，请指定 30 分钟到 7 天之间的间隔时间字面量值。例如，指定 INTERVAL 4 HOUR 表示 4 小时过时间隔时间。使用此值时，如果缓存的元数据在过去 4 小时内刷新，则对表执行的操作会使用缓存的元数据。如果缓存的元数据早于该值，则操作会回退到从 Cloud Storage 检索元数据。
metadata_cache_mode

STRING

适用于 BigLake 表和对象表。

指定表的元数据缓存是自动刷新还是手动刷新。

如果设置为 AUTOMATIC，元数据缓存会按系统定义的间隔时间刷新，通常在 30 到 60 分钟之间。

如果要根据您确定的时间表刷新元数据缓存，请设置为 MANUAL。在这种情况下，您可以调用 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系统过程来刷新缓存。

如果 max_staleness 设置为大于 0 的值，您必须设置 metadata_cache_mode。
null_marker

STRING

表示 CSV 文件中 NULL 值的字符串。

适用于 CSV 数据。
object_metadata

STRING

仅在创建对象表时是必需的。

在创建对象表时，请将此选项的值设置为 SIMPLE。
preserve_ascii_control_characters

BOOL

如果为 true，则系统会保留嵌入的 ASCII 控制字符，即 ASCII 表中的前 32 个字符（范围从“\x00”到“\x1F”）。

适用于 CSV 数据。
projection_fields

STRING

要加载的实体属性的列表。

适用于 Datastore 数据。
quote

STRING

用于括起 CSV 文件中数据部分的字符串。如果您的数据包含括起的换行符，另请将 allow_quoted_newlines 属性设置为 true。

适用于 CSV 数据。
reference_file_schema_uri

STRING

用户提供的包含表架构的参考文件。

适用于 Parquet/ORC/AVRO 数据。

示例："gs://bucket/path/reference_schema_file.parquet"。
require_hive_partition_filter

BOOL

如果为 true，则对此表进行的所有查询都需要分区过滤条件，该过滤条件可用于在读取数据时清除分区。仅适用于 Hive 分区的外部表。

适用于 Avro、CSV、JSON、Parquet、ORC 数据。
sheet_range

STRING

要查询的 Google 表格的电子表格范围。

适用于 Google 表格数据。

示例：“sheet1!A1:B20”。
skip_leading_rows

INT64

读取数据时要跳过的文件顶部行数。

适用于 CSV 和 Google 表格数据。
uris

对于非 Bigtable 表的外部表（包括对象表）：

ARRAY<STRING>

外部数据位置的完全限定 URI 数组。 每个 URI 都可以包含一个星号 (*) 通配符，该通配符必须位于存储桶名称之后。如果指定以多个文件为目标的 uris 值，则所有这些文件都必须共享一个兼容的架构。

以下示例展示了有效的 uris 值：

  • ['gs://bucket/path1/myfile.csv']
  • ['gs://bucket/path1/*.csv']
  • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

对于 Bigtable 表：

STRING

标识用作数据源的 Bigtable 表的 URI；只能指定一个 Bigtable URI。

示例：https://googleapis.com/bigtable/projects/project_id/instances/instance_id[/appProfiles/app_profile]/tables/table_name

如需详细了解如何构建 Bigtable URI，请参阅检索 Bigtable URI。

示例

示例 1：

以下示例通过查询 INFORMATION_SCHEMA.TABLE_OPTIONS 视图来检索默认项目 (myproject) 中的 mydataset 中的所有表的默认表到期时间。

如需对非默认项目运行查询，请按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应的项目 ID 添加到数据集，例如 `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS。

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'expiration_timestamp';

结果类似于以下内容：

  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | table_catalog  | table_schema  | table_name |     option_name      | option_type |             option_value             |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+
  | myproject      | mydataset     | mytable1   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2020-01-16T21:12:28.000Z" |
  | myproject      | mydataset     | mytable2   | expiration_timestamp | TIMESTAMP   | TIMESTAMP "2021-01-01T21:12:28.000Z" |
  +----------------+---------------+------------+----------------------+-------------+--------------------------------------+

示例 2：

以下示例检索 mydataset 中包含测试数据的所有表的元数据。该查询使用 description 选项中的值查找在说明的任何位置包含“test”的表。mydataset 位于默认项目 myproject 中。

如需对非默认项目运行查询，请按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应的项目 ID 添加到数据集，例如 `myproject`.mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS。

  SELECT
    *
  FROM
    mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
  WHERE
    option_name = 'description'
    AND option_value LIKE '%test%';

结果类似于以下内容：

  +----------------+---------------+------------+-------------+-------------+--------------+
  | table_catalog  | table_schema  | table_name | option_name | option_type | option_value |
  +----------------+---------------+------------+-------------+-------------+--------------+
  | myproject      | mydataset     | mytable1   | description | STRING      | "test data"  |
  | myproject      | mydataset     | mytable2   | description | STRING      | "test data"  |
  +----------------+---------------+------------+-------------+-------------+--------------+

COLUMNS 视图

查询 INFORMATION_SCHEMA.COLUMNS 视图时，查询为表中的每一列（字段）返回一行结果。

INFORMATION_SCHEMA.COLUMNS 视图具有如下架构：

列名 数据类型 值
TABLE_CATALOG STRING 该数据集所属项目的项目 ID
TABLE_SCHEMA STRING 包含表的数据集的名称，也称为 datasetId
TABLE_NAME STRING 表或视图的名称，也称为 tableId
COLUMN_NAME STRING 列的名称
ORDINAL_POSITION INT64 表中列的偏移量，从 1 开始计数；如果列为伪列（例如 _PARTITIONTIME 或 _PARTITIONDATE），则值为 NULL
IS_NULLABLE STRING YES 或 NO，具体取决于列的模式是否允许使用 NULL 值
DATA_TYPE STRING 列的 GoogleSQL 数据类型
IS_GENERATED STRING 值始终为 NEVER
GENERATION_EXPRESSION STRING 值始终为 NULL
IS_STORED STRING 值始终为 NULL
IS_HIDDEN STRING YES 或 NO，具体取决于列是否为伪列，例如 _PARTITIONTIME 或 _PARTITIONDATE
IS_UPDATABLE STRING 值始终为 NULL
IS_SYSTEM_DEFINED STRING YES 或 NO，具体取决于列是否为伪列，例如 _PARTITIONTIME 或 _PARTITIONDATE
IS_PARTITIONING_COLUMN STRING YES 或 NO，具体取决于列是否为分区列
CLUSTERING_ORDINAL_POSITION INT64 表的聚簇列中列的偏移量，从 1 开始计数；如果表不是聚簇表，则值为 NULL
COLLATION_NAME STRING 排序规则规范的名称（如果存在）；否则为 NULL

如果传入了 STRING 或 ARRAY<STRING>，则会返回排序规则规范（如果存在）；否则返回 NULL。
COLUMN_DEFAULT STRING 列的默认值（如果存在）；否则，值为 NULL
ROUNDING_MODE STRING 如果字段类型为参数化的 NUMERIC 或 BIGNUMERIC，则为写入到字段的值采用的舍入模式；否则，值为 NULL

示例

以下示例从 census_bureau_usa 数据集内 population_by_zip_2010 表的 INFORMATION_SCHEMA.COLUMNS 视图中检索元数据。此数据集是 BigQuery 公共数据集计划的一部分。

由于您查询的表属于 bigquery-public-data 项目，因此您应按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应项目 ID 添加到数据集；例如 `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.TABLES。

以下列会从查询结果中排除，因为它们目前预留供将来使用：

  • IS_GENERATED
  • GENERATION_EXPRESSION
  • IS_STORED
  • IS_UPDATABLE
  SELECT
    * EXCEPT(is_generated, generation_expression, is_stored, is_updatable)
  FROM
    `bigquery-public-data`.census_bureau_usa.INFORMATION_SCHEMA.COLUMNS
  WHERE
    table_name = 'population_by_zip_2010';

结果类似于以下内容。为改善可读性，结果中没有保留某些列。

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       table_name       | column_name | ordinal_position | is_nullable | data_type | is_hidden | is_system_defined | is_partitioning_column | clustering_ordinal_position |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
| population_by_zip_2010 | zipcode     |                1 | NO          | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | geo_id      |                2 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | minimum_age |                3 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | maximum_age |                4 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | gender      |                5 | YES         | STRING    | NO        | NO                | NO                     |                        NULL |
| population_by_zip_2010 | population  |                6 | YES         | INT64     | NO        | NO                | NO                     |                        NULL |
+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+

COLUMN_FIELD_PATHS 视图

当您查询 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图时，查询为嵌套在 RECORD（或 STRUCT）列中的每一列返回一行结果。

INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图具有如下架构：

列名 数据类型 值
TABLE_CATALOG STRING 该数据集所属项目的项目 ID
TABLE_SCHEMA STRING 包含表的数据集的名称，也称为 datasetId
TABLE_NAME STRING 表或视图的名称，也称为 tableId
COLUMN_NAME STRING 列的名称
FIELD_PATH STRING 嵌套在 `RECORD` 或 `STRUCT` 列中的列的路径
DATA_TYPE STRING 列的 GoogleSQL 数据类型
DESCRIPTION STRING 列的说明
COLLATION_NAME STRING 排序规则规范的名称（如果存在）；否则为 NULL

如果传入了 STRUCT 中的 STRING、ARRAY<STRING> 或 STRING 字段，则返回排序规则规范（如果存在）；否则返回 NULL。
ROUNDING_MODE STRING 如果将精度和标度应用于参数化的 NUMERIC 或 BIGNUMERIC 值，则为要采用的舍入模式；否则，值为 NULL。

示例

以下示例从 github_repos 数据集内 commits 表的 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图中检索元数据。此数据集是 BigQuery 公共数据集计划的一部分。

由于您查询的表属于 bigquery-public-data 项目，因此您应按 `project_id`.dataset.INFORMATION_SCHEMA.view 格式将相应项目 ID 添加到数据集；例如 `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS。

commits 表包含以下嵌套列以及嵌套和重复列：

  • author：嵌套的 RECORD 列
  • committer：嵌套的 RECORD 列
  • trailer：嵌套且重复的 RECORD 列
  • difference：嵌套且重复的 RECORD 列

要查看有关 author 和 difference 列的元数据，请运行以下查询。

SELECT
  *
FROM
  `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE
  table_name = 'commits'
  AND (column_name = 'author' OR column_name = 'difference');

结果类似于以下内容。为改善可读性，结果中没有保留某些列。

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | table_name | column_name |     field_path      |                                                                      data_type                                                                      | description |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | commits    | author      | author              | STRUCT<name STRING, email STRING, time_sec INT64, tz_offset INT64, date TIMESTAMP>                                                                  | NULL        |
  | commits    | author      | author.name         | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.email        | STRING                                                                                                                                              | NULL        |
  | commits    | author      | author.time_sec     | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.tz_offset    | INT64                                                                                                                                               | NULL        |
  | commits    | author      | author.date         | TIMESTAMP                                                                                                                                           | NULL        |
  | commits    | difference  | difference          | ARRAY<STRUCT<old_mode INT64, new_mode INT64, old_path STRING, new_path STRING, old_sha1 STRING, new_sha1 STRING, old_repo STRING, new_repo STRING>> | NULL        |
  | commits    | difference  | difference.old_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.new_mode | INT64                                                                                                                                               | NULL        |
  | commits    | difference  | difference.old_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_path | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_sha1 | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.old_repo | STRING                                                                                                                                              | NULL        |
  | commits    | difference  | difference.new_repo | STRING                                                                                                                                              | NULL        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+

TABLE_STORAGE 视图

TABLE_STORAGE 和 TABLE_STORAGE_BY_ORGANIZATION 视图具有如下架构：

列名 数据类型 值
PROJECT_ID STRING 该数据集所属项目的项目 ID
TABLE_CATALOG STRING 该数据集所属项目的项目 ID
PROJECT_NUMBER INT64 该数据集所属项目的项目编号
TABLE_SCHEMA STRING 包含表或具体化视图的数据集的名称，也称为 datasetId
TABLE_NAME STRING 表或具体化视图的名称，也称为 tableId
CREATION_TIME TIMESTAMP 表的创建时间
DELETED BOOLEAN 指示表是否已删除
STORAGE_LAST_MODIFIED_TIME TIMESTAMP 数据最近一次写入表的时间。
TOTAL_ROWS INT64 表或具体化视图中的总行数
TOTAL_PARTITIONS INT64 表或具体化视图中存在的分区数量。未分区表会返回 0。
TOTAL_LOGICAL_BYTES INT64 表或具体化视图中的逻辑（非压缩）字节总数
ACTIVE_LOGICAL_BYTES INT64 存在时间不超过 90 天的逻辑（非压缩）字节数
LONG_TERM_LOGICAL_BYTES INT64 存在时间超过 90 天的逻辑（非压缩）字节数
TOTAL_PHYSICAL_BYTES INT64 用于存储的物理（压缩）字节总数，包括活跃、长期和时间旅行（已删除或已更改的数据）字节数
ACTIVE_PHYSICAL_BYTES INT64 存在时间短于 90 天的物理（压缩）字节数，包括时间旅行（删除或更改的数据）字节
LONG_TERM_PHYSICAL_BYTES INT64 存在时间超过 90 天的物理（非压缩）字节数
TIME_TRAVEL_PHYSICAL_BYTES INT64 时间旅行存储（删除或更改的数据）使用的物理（非压缩）字节数
FAIL_SAFE_PHYSICAL_BYTES INT64 故障安全存储（删除或更改的数据）使用的物理（非压缩）字节数
TABLE_TYPE STRING 表的类型。 例如，“EXTERNAL”或“BASE TABLE”

示例

示例 1：

以下示例显示了当前项目需付费的逻辑总字节数。

SELECT
  SUM(total_logical_bytes) AS total_logical_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE;

结果类似于以下内容：

+---------------------+
| total_logical_bytes |
+---------------------+
| 971329178274633     |
+---------------------+
示例 2：

以下示例展示了如何预测未来 30 天内每个数据集的逻辑结算模型和物理结算模型之间的价格差异。此示例假定在未来的 30 天内（自运行查询之时起），存储空间用量保持不变。请注意，预测仅限于基表，不包括数据集中的所有其他类型的表。

此查询的价格变量中使用的价格适用于 us-central1 区域。如果您要针对其他区域运行此查询，请相应更新价格变量。如需了解价格信息，请参阅存储价格。

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

    转到 BigQuery 页面

  2. 在查询编辑器框中输入以下 GoogleSQL 查询。 INFORMATION_SCHEMA 要求使用 GoogleSQL 语法。GoogleSQL 是 Google Cloud 控制台中的默认语法。

    DECLARE active_logical_gib_price FLOAT64 DEFAULT 0.02;
DECLARE long_term_logical_gib_price FLOAT64 DEFAULT 0.01;
DECLARE active_physical_gib_price FLOAT64 DEFAULT 0.04;
DECLARE long_term_physical_gib_price FLOAT64 DEFAULT 0.02;

WITH
 storage_sizes AS (
   SELECT
     table_schema AS dataset_name,
     -- Logical
     SUM(IF(deleted=false, active_logical_bytes, 0)) / power(1024, 3) AS active_logical_gib,
     SUM(IF(deleted=false, long_term_logical_bytes, 0)) / power(1024, 3) AS long_term_logical_gib,
     -- Physical
     SUM(active_physical_bytes) / power(1024, 3) AS active_physical_gib,
     SUM(active_physical_bytes - time_travel_physical_bytes) / power(1024, 3) AS active_no_tt_physical_gib,
     SUM(long_term_physical_bytes) / power(1024, 3) AS long_term_physical_gib,
     -- Restorable previously deleted physical
     SUM(time_travel_physical_bytes) / power(1024, 3) AS time_travel_physical_gib,
     SUM(fail_safe_physical_bytes) / power(1024, 3) AS fail_safe_physical_gib,
   FROM
     `region-REGION`.INFORMATION_SCHEMA.TABLE_STORAGE_BY_PROJECT
   WHERE total_physical_bytes > 0
     -- Base the forecast on base tables only for highest precision results
     AND table_type  = 'BASE TABLE'
     GROUP BY 1
 )
SELECT
  dataset_name,
  -- Logical
  ROUND(active_logical_gib, 2) AS active_logical_gib,
  ROUND(long_term_logical_gib, 2) AS long_term_logical_gib,
  -- Physical
  ROUND(active_physical_gib, 2) AS active_physical_gib,
  ROUND(long_term_physical_gib, 2) AS long_term_physical_gib,
  ROUND(time_travel_physical_gib, 2) AS time_travel_physical_gib,
  ROUND(fail_safe_physical_gib, 2) AS fail_safe_physical_gib,
  -- Compression ratio
  ROUND(SAFE_DIVIDE(active_logical_gib, active_no_tt_physical_gib), 2) AS active_compression_ratio,
  ROUND(SAFE_DIVIDE(long_term_logical_gib, long_term_physical_gib), 2) AS long_term_compression_ratio,
  -- Forecast costs logical
  ROUND(active_logical_gib * active_logical_gib_price, 2) AS forecast_active_logical_cost,
  ROUND(long_term_logical_gib * long_term_logical_gib_price, 2) AS forecast_long_term_logical_cost,
  -- Forecast costs physical
  ROUND((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price, 2) AS forecast_active_physical_cost,
  ROUND(long_term_physical_gib * long_term_physical_gib_price, 2) AS forecast_long_term_physical_cost,
  -- Forecast costs total
  ROUND(((active_logical_gib * active_logical_gib_price) + (long_term_logical_gib * long_term_logical_gib_price)) -
     (((active_no_tt_physical_gib + time_travel_physical_gib + fail_safe_physical_gib) * active_physical_gib_price) + (long_term_physical_gib * long_term_physical_gib_price)), 2) AS forecast_total_cost_difference
FROM
  storage_sizes
ORDER BY
  (forecast_active_logical_cost + forecast_active_physical_cost) DESC;

  3. 点击运行。

结果如下所示：

+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset_name | active_logical_gib | long_term_logical_gib | active_physical_gib | long_term_physical_gib | active_compression_ratio | long_term_compression_ratio | forecast_active_logical_cost | forecaset_long_term_logical_cost | forecast_active_physical_cost | forecast_long_term_physical_cost | forecast_total_cost_difference |
+--------------+--------------------+-----------------------+---------------------+------------------------+--------------------------+-----------------------------+------------------------------+----------------------------------+-------------------------------+----------------------------------+--------------------------------+
| dataset1     |               10.0 |                  10.0 |                 1.0 |                    1.0 |                     10.0 |                        10.0 |                          0.2 |                              0.1 |                          0.04 |                             0.02 |                           0.24 |

列出数据集中的表

您可以通过以下方式列出数据集中的表：

  • 使用 Google Cloud 控制台。
  • 使用 bq 命令行工具 bq ls 命令。
  • 调用 tables.list API 方法。
  • 使用客户端库。

所需权限

如需列出数据集中的表，您至少必须具有 bigquery.tables.list 权限。以下预定义 IAM 角色包含 bigquery.tables.list 权限：

  • bigquery.user
  • bigquery.metadataViewer
  • bigquery.dataViewer
  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

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

列出表

要列出数据集中的表，请执行以下操作：

控制台

  1. 在 Google Cloud 控制台的导航窗格中，点击您的数据集将其展开。此时会显示数据集中的表和视图。

  2. 滚动列表，查看数据集中的表。表和视图由不同的图标进行标识。

bq

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. 发出 bq ls 命令。--format 标志可用于控制输出。如果您要列出非默认项目中的表，请按以下格式将相应项目 ID 添加到数据集中：project_id:dataset。

    您还可以使用其他标志，包括：

    • --max_results 或 -n：用于表示结果数量上限的整数，默认值为 50。
    bq ls \
--format=pretty \
--max_results integer \
project_id:dataset

    其中：

    • integer 是一个整数，表示要列出的表的数量。
    • project_id 是您的项目 ID。
    • dataset 是数据集的名称。

    运行该命令时，Type 字段会显示 TABLE 或 VIEW。例如：

    +-------------------------+-------+----------------------+-------------------+
|         tableId         | Type  |        Labels        | Time Partitioning |
+-------------------------+-------+----------------------+-------------------+
| mytable                 | TABLE | department:shipping  |                   |
| myview                  | VIEW  |                      |                   |
+-------------------------+-------+----------------------+-------------------+

    示例：

    输入以下命令可列出默认项目的数据集 mydataset 中的表。 

       bq ls --format=pretty mydataset

    输入以下命令可从 mydataset 返回超出默认输出数量（50 个）的表。mydataset 位于您的默认项目中。 

       bq ls --format=pretty --max_results 60 mydataset

    输入以下命令可列出 myotherproject 的数据集 mydataset 中的表。 

       bq ls --format=pretty myotherproject:mydataset

API

如需使用 API 列出表，请调用 tables.list 方法。

C#

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

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


using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;
using System.Linq;

public class BigQueryListTables
{
    public void ListTables(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Retrieve list of tables in the dataset
        List<BigQueryTable> tables = client.ListTables(datasetId).ToList();
        // Display the results
        if (tables.Count > 0)
        {
            Console.WriteLine($"Tables in dataset {datasetId}:");
            foreach (var table in tables)
            {
                Console.WriteLine($"\t{table.Reference.TableId}");
            }
        }
        else
        {
            Console.WriteLine($"{datasetId} does not contain any tables.");
        }
    }
}

Go

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

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// listTables demonstrates iterating through the collection of tables in a given dataset.
func listTables(w io.Writer, 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()

	ts := client.Dataset(datasetID).Tables(ctx)
	for {
		t, err := ts.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Table: %q\n", t.TableID)
	}
	return nil
}

Java

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

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

import com.google.api.gax.paging.Page;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.DatasetId;
import com.google.cloud.bigquery.Table;

public class ListTables {

  public static void runListTables() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    listTables(projectId, datasetName);
  }

  public static void listTables(String projectId, 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();

      DatasetId datasetId = DatasetId.of(projectId, datasetName);
      Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
      tables.iterateAll().forEach(table -> System.out.print(table.getTableId().getTable() + "\n"));

      System.out.println("Tables listed successfully.");
    } catch (BigQueryException e) {
      System.out.println("Tables were not listed. Error occurred: " + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function listTables() {
  // Lists tables in 'my_dataset'.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';

  // List all tables in the dataset
  const [tables] = await bigquery.dataset(datasetId).getTables();

  console.log('Tables:');
  tables.forEach(table => console.log(table.id));
}

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->dataset($datasetId);
$tables = $dataset->tables();
foreach ($tables as $table) {
    print($table->id() . PHP_EOL);
}

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 that contains
#                  the tables you are listing.
# dataset_id = 'your-project.your_dataset'

tables = client.list_tables(dataset_id)  # Make an API request.

print("Tables contained in '{}':".format(dataset_id))
for table in tables:
    print("{}.{}.{}".format(table.project, table.dataset_id, table.table_id))

Ruby

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

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

require "google/cloud/bigquery"

def list_tables dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id

  puts "Tables in dataset #{dataset_id}:"
  dataset.tables.each do |table|
    puts "\t#{table.table_id}"
  end
end

表安全性

如需控制对 BigQuery 中表的访问权限，请参阅表访问权限控制简介。

后续步骤

自行试用

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

免费试用 BigQuery