创建和使用表

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

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

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

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

表限制

BigQuery 表受到以下限制：

每个数据集中的表名必须是唯一的。
GCP Console 和经典版 BigQuery 网页界面仅支持一次复制一个表。
复制表时，目标数据集必须与要复制的表位于同一位置。例如，您无法将表从存储在欧盟的数据集复制到存储在美国的数据集。
使用 CLI、API 或客户端库将多个源表复制到目标表时，所有源表都必须具有相同的架构。
通过使用 GCP Console、经典版 BigQuery 网页界面、命令行工具、API 或客户端库，您一次只能删除一个表。
导出表数据时，唯一支持的目标是 Cloud Storage。
当数据集中表的数量接近 50000 个或更多时，枚举这些表时速度会变慢。无论您是使用 API 调用，还是使用经典版 BigQuery 网页界面，枚举性能都会受到影响。目前，GCP Console 中的 BigQuery 网页界面最多允许每个数据集显示 50000 个表。

如需提升经典版 BigQuery 网页界面的性能，您可以使用 ?minimal 参数将每个项目显示的表数限制为 30000 个。您可以按以下格式向经典版 BigQuery 网页界面网址添加该参数：https://bigquery.cloud.google.com/queries/project_id?minimal。

创建表

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

手动使用 GCP Console、经典版 BigQuery 网页界面或命令行工具的 bq mk 命令创建
通过调用 tables.insert API 方法以编程方式创建
通过使用客户端库创建
根据查询结果创建
通过定义引用外部数据源的表
在加载数据时创建
通过使用 CREATE TABLE DDL 语句创建

表命名

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

包含最多 1024 个字符
包含字母（大写或小写）、数字和下划线

所需权限

如需创建表，您至少必须具有以下权限：

bigquery.tables.create：创建表的权限
bigquery.tables.updateData：使用加载作业、查询作业或复制作业向表中写入数据
bigquery.jobs.create：运行将数据写入表的查询作业、加载作业或复制作业

如需访问要写入表中的数据，可能还需要其他权限，例如 bigquery.tables.getData。

以下预定义的 Cloud IAM 角色具有 bigquery.tables.create 和 bigquery.tables.updateData 权限：

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

以下预定义的 Cloud IAM 角色具有 bigquery.jobs.create 权限：

bigquery.user
bigquery.jobUser
bigquery.admin

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

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

创建具有架构定义的空表

创建具有架构定义的空表时，您可执行以下操作：

使用 GCP Console 或经典版 BigQuery 网页界面输入架构
使用命令行工具以内嵌方式提供架构
使用命令行工具提交 JSON 架构文件
调用 API 的 tables.insert 方法时，在表资源中提供架构

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

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

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

控制台

在 GCP Console 中打开 BigQuery 网页界面。
转到 BigQuery 网页界面
在导航面板的资源部分中，展开您的项目并选择数据集。
在窗口右侧的详细信息面板中，点击创建表。
在创建表页面的来源部分，选择空白表。
在创建表页面的目标部分，执行以下操作：
- 在数据集名称部分，选择相应的数据集。
- 在表名称字段中，输入您要在 BigQuery 中创建的表的名称。
- 确认表类型设置为原生表。
在架构部分中，输入架构定义。
- 通过以下方式，手动输入架构信息：
  - 启用以文本形式修改，并以 JSON 数组格式输入表架构。
    
    注意：您可以输入以下命令来查看 JSON 格式的现有表架构：bq show --format=prettyjson dataset.table。
  - 使用添加字段手动输入架构。
对于分区和聚簇设置，保留默认值 (No partitioning)。
对于高级选项部分的加密，保留默认值 (Google-managed key)。默认情况下，BigQuery 会对以静态方式存储的客户内容进行加密。
点击创建表。

DDL

借助数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表和视图。

详细了解如何使用数据定义语言语句。

如需使用 DDL 语句在 GCP Console 中创建表，请执行以下操作：

在 GCP Console 中打开 BigQuery 网页界面。
转到 GCP Console
点击编写新查询。

在查询编辑器文本区域中，输入 CREATE TABLE DDL 语句。

以下查询会创建一个名为 newtable 的表，该表将于 2020 年 1 月 1 日到期。该表的说明是“a table that expires in 2020”（一个将在 2020 年到期的表），该表的标签是 org_unit:development。

 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 "2020-01-01 00:00:00 UTC",
   description="a table that expires in 2020",
   labels=[("org_unit", "development")]
 )

（可选）点击展开并选择查询设置。
（可选）对于处理位置，点击自动选择并选择数据的位置。如果您将处理位置保留设置为“未指定”，则系统会自动检测处理位置。
点击运行。查询完成后，该表将显示在资源窗格中。

经典版界面

在导航窗格中，点击数据集名称旁边的向下箭头图标，然后点击 Create new table。
在 Create Table 页面上的 Source Data 部分中，点击 Create empty table。
在 Create Table 页面的 Destination Table 部分，执行以下操作：
- 对于 Table name ，选择相应的数据集，然后在表名称字段中输入要创建的表的名称。
- 确认 Table type 设置为 Native table。
在 Schema 部分中，手动输入架构定义。
- 可通过以下方式手动输入架构信息：
  - 点击 Edit as text，并以 JSON 数组格式输入表架构：
    
    注意：您可以输入以下命令来查看 JSON 格式的现有表架构：bq show --schema --format=prettyjson project_id:dataset.table。
  - 使用 Add Field 输入架构：
在 Options 部分保留默认值。
- Partitioning Type：None
- Partitioning Field：应该不可用
- Require partition filter：应该不可用
- Clustering Fields：应该不可用
- Destination Encryption：Default 默认情况下，BigQuery 会使用 Google 管理的密钥对以静态方式存储的客户内容进行加密。
点击 Create Table。

CLI

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

--expiration
--description
--time_partitioning_type
--destination_kms_key
--label

此处未演示 --time_partitioning_type 和 --destination_kms_key。如需详细了解 --time_partitioning_type，请参阅提取时间分区表或分区表。如需详细了解 --destination_kms_key，请参阅 CMEK（客户管理的加密密钥）。

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

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

bq mk \
--table \
--expiration integer \
--description description \
--label key:value, key:value \
project_id:dataset.table \
schema

其中：

integer 是表的默认生命周期（以秒为单位）。最小值为 3600 秒（一小时）。到期时间以当前世界协调时间 (UTC) 加上这个整数值为准。如果在创建表时设置该表的到期时间，则系统会忽略数据集的默认表到期时间设置。
description 是加引号的表说明。
key:value 是代表标签的键值对。可使用英文逗号分隔列表输入多个标签。
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

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

API

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

C#

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

在 GitHub 上查看反馈


using Google.Cloud.BigQuery.V2;
using System;

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

在 GitHub 上查看反馈

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
}

Java

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

在 GitHub 上查看反馈

TableId tableId = TableId.of(datasetName, tableName);
// Table field definition
Field field = Field.of(fieldName, LegacySQLTypeName.STRING);
// Table schema definition
Schema schema = Schema.of(field);
TableDefinition tableDefinition = StandardTableDefinition.of(schema);
TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();
Table table = bigquery.create(tableInfo);

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

在 GitHub 上查看反馈

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

在 GitHub 上查看反馈

from google.cloud import bigquery

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

# TODO(developer): 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"

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

Ruby

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

在 GitHub 上查看反馈

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

基于查询结果创建表

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

控制台

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

转到 GCP Console
在导航面板的资源部分中，展开您的项目并选择数据集。
如果查询编辑器处于隐藏状态，请点击窗口右上角的显示编辑器。
在查询编辑器文本区域中输入有效的 SQL 查询。
点击编辑器下方的更多，然后选择查询设置。
勾选该方框，为查询结果设置目标表。
在目标位置部分，选择要在其中创建表的相应项目名称和数据集名称，然后选择表名称。
在目标表的写入设置部分，选择以下选项之一：
- 只写入空白表 - 仅在表为空时才将查询结果写入表。
- 附加到表 - 将查询结果附加到现有表。
- 覆盖表 - 使用查询结果覆盖名称相同的现有表。
（可选）在处理位置部分，点击自动选择并选择您的位置。
点击运行查询。这会创建一个查询作业，并将查询结果写入您指定的表中。

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

DDL

通过数据定义语言 (DDL) 语句，您可以使用标准 SQL 查询语法创建和修改表。

如需了解详情，请参阅 CREATE TABLE 语句页面和 CREATE TABLE 示例：从现有表创建新表。

经典版界面

转到经典版 BigQuery 网页界面。
转到经典版 BigQuery 网页界面
点击 Compose query 按钮。
在 New Query 文本区域中输入有效的 SQL 查询。
点击 Show Options。
在 Destination Table 部分，点击 Select Table。
在 Select Destination Table 对话框中，执行以下操作：
1. 对于 Project，选择一个用于存储数据集和表的项目。
2. 对于 Dataset，选择用于存储表的数据集。
3. 在 Table ID 字段中，输入表名称。该名称在目标数据集中必须是唯一的。表名称最长可达 1024 个字符，并且只能包含 a-z、A-Z、0-9 或 _（下划线字符）。
4. 点击 OK。
在 Destination Table 部分的 Write Preference 中，选择以下某个选项：
- Write if empty - 仅在表为空时才将查询结果写入表。
- Append to table - 将查询结果附加到现有表。
- Overwrite table - 使用查询结果覆盖名称相同的现有表。
（可选）在 Processing Location 部分，点击 Unspecified 并选择数据的位置。
点击 Run query。这会创建一个查询作业，并将查询结果写入您指定的表中。

或者，如果在运行查询之前忘记指定目标表，您可以将临时表复制到永久表，只需点击结果窗口中的 Save as Table 按钮即可。

CLI

输入 bq query 命令并指定 --destination_table 标志，可基于查询结果创建一个永久表。指定 use_legacy_sql=false 标志以使用标准 SQL 语法。如需将查询结果写入非默认项目中的某个表，请按以下格式将相应项目 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 是使用标准 SQL 语法的查询。

如果未指定“写入处置方式”标志，则默认行为是仅在表为空时写入结果。如果表已存在且非空，则系统会返回以下错误：`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 标志将查询结果附加到目标表。

bq query \
--append \
--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/snippets/snippet.go

在 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")

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)
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.Println(row)
}

Java

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

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

在 GitHub 上查看

// BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();
// String destinationDataset = 'my_destination_dataset';
// String destinationTable = 'my_destination_table';
String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
QueryJobConfiguration queryConfig =
    // Note that setUseLegacySql is set to false by default
    QueryJobConfiguration.newBuilder(query)
        // Save the results of the query to a permanent table.
        .setDestinationTable(TableId.of(destinationDataset, destinationTable))
        .build();

// Print the results.
for (FieldValueList row : bigquery.query(queryConfig).iterateAll()) {
  for (FieldValue val : row) {
    System.out.printf("%s,", val.toString());
  }
  System.out.printf("\n");
}

Python

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

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

在 GitHub 上查看

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'your_dataset_id'

job_config = bigquery.QueryJobConfig()
# Set the destination table
table_ref = client.dataset(dataset_id).table('your_table_id')
job_config.destination = table_ref
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,
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location='US',
    job_config=job_config)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print('Query results loaded to table {}'.format(table_ref.path))

创建引用外部数据源的表

外部数据源（也称为“联合数据源”）是可供直接查询的数据源，即使数据未存储在 BigQuery 中也是如此。您不用加载或流式传输数据，只需创建一个引用外部数据源的表即可。

BigQuery 支持直接查询以下各项中的数据：

您可以在支持的外部数据源中查询数据，方法是创建一个临时或永久表，该表引用外部数据源中存储的数据。要详细了解如何使用外部数据源，请参阅：

在加载数据时创建表

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

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

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

控制表的访问权限

您不能直接分配对表或视图的访问权限控制。您能够授予访问权限的最低级别的 BigQuery 资源是数据集级别。如需配置对表和视图的访问权限，请在数据集或更高级别为实体授予 Cloud IAM 角色。

在数据集级别授予角色可指定允许实体对该特定数据集中的表和视图执行的操作。如需了解如何配置数据集级别的访问权限控制，请参阅控制对数据集的访问权限。

您还可以在 Google Cloud Platform 资源层次结构中的更高级别（例如项目、文件夹或组织级别）授予 Cloud IAM 角色。在更高级别授予角色后，实体可以访问更多资源。例如，在项目级别为实体授予角色可向该实体提供适用于整个项目中所有数据集的权限。如需详细了解如何授予对资源的访问权限，请参阅 Cloud IAM 文档中的授予、更改和撤消对资源的访问权限。

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

如需详细了解角色和权限，请参阅以下内容：

使用表

获取表的相关信息

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

使用 GCP Console 或经典版 BigQuery 网页界面
使用 bq show CLI 命令
调用 tables.get API 方法
使用客户端库
查询 INFORMATION_SCHEMA 视图（测试版）

所需权限

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

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

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

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

获取表信息

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

控制台

在导航面板的资源部分中，展开您的项目并选择数据集。点击数据集名称，将其展开。此时会显示数据集中的表和视图。
点击表名称。
在编辑器下方，点击详细信息。此页面会显示表说明和表信息。
点击架构标签页，查看表的架构定义。

经典版界面

在导航窗格中，点击数据集左侧的向下箭头图标展开数据集，或双击数据集名称。此时会显示数据集中的表和视图。
点击表名称。
点击 Details。Table Details 页面会显示表说明和表信息。
点击 Schema 标签页，查看表的架构定义。

CLI

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

在 GitHub 上查看反馈

meta, err := client.Dataset(datasetID).Table(tableID).Metadata(ctx)
if err != nil {
	return err
}
// Print basic information about the table.
fmt.Printf("Schema has %d top-level fields\n", len(meta.Schema))
fmt.Printf("Description: %s\n", meta.Description)
fmt.Printf("Row in managed storage: %d\n", meta.NumRows)

Java

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

在 GitHub 上查看反馈

TableId tableId = TableId.of(projectId, datasetName, tableName);
Table table = bigquery.getTable(tableId);

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

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

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 table_id to the ID of the model to fetch.
# table_id = 'your-project.your_dataset.your_table'

table = client.get_table(table_id)

print(
    "Got table '{}.{}.{}'.".format(table.project, table.dataset_id, table.table_id)
)

# View table properties
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 视图以检索关于表中的列（字段）的元数据。

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

`TABLES` 视图

当您查询 INFORMATION_SCHEMA.TABLES 视图时，查询结果为数据集中的每个表或视图返回一行。

针对 INFORMATION_SCHEMA.TABLES 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表或视图的数据集。

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

列名	数据类型	值
`TABLE_CATALOG`	`STRING`	包含数据集的项目的名称
`TABLE_SCHEMA`	`STRING`	包含表或视图的数据集的名称（也称为 `datasetId`）
`TABLE_NAME`	`STRING`	表或视图的名称（也称为 `tableId`）
`TABLE_TYPE`	`STRING`	表类型： `BASE TABLE`：一个 BigQuery 表 `VIEW`：一个 BigQuery 视图 `EXTERNAL`：一个引用外部数据源的表
`IS_INSERTABLE_INTO`	`STRING`	`YES` 或 `NO`，具体取决于表是否支持 DML INSERT 语句
`IS_TYPED`	`STRING`	值始终为 `NO`
`CREATION_TIME`	`TIMESTAMP`	表的创建时间

如需详细了解数据集属性，请参阅 REST API 文档中的数据集资源页。如需详细了解表和视图属性，请参阅 REST API 文档中的表资源页。

示例

示例 1：

以下示例从 INFORMATION_SCHEMA.TABLES 视图中检索所有列，is_typed 除外，该列留待将来使用。返回的元数据包括默认项目 myproject 的数据集 mydataset 中的所有表。

mydataset 包含以下表：

mytable1：标准 BigQuery 表
myview1：BigQuery 视图

针对 INFORMATION_SCHEMA.TABLES 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

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

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
SELECT
 * EXCEPT(is_typed)
FROM
 mydataset.INFORMATION_SCHEMA.TABLES
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'SELECT
   * EXCEPT(is_typed)
 FROM
   mydataset.INFORMATION_SCHEMA.TABLES'

结果应如下所示：

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | YES                | 2018-10-29 20:34:44 |
  | myproject      | mydataset     | myview1        | VIEW       | NO                 | 2018-12-29 00:19:20 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+

示例 2：

以下示例从 INFORMATION_SCHEMA.TABLES 视图中检索类型为 BASE TABLE 的所有表。不包括 is_typed 列。返回的元数据包括默认项目 myproject 的数据集 mydataset 中的所有表。

针对 INFORMATION_SCHEMA.TABLES 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
SELECT
 * EXCEPT(is_typed)
FROM
 mydataset.INFORMATION_SCHEMA.TABLES
WHERE
 table_type="BASE TABLE"
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'SELECT
   * EXCEPT(is_typed)
 FROM
   mydataset.INFORMATION_SCHEMA.TABLES
 WHERE
   table_type="BASE TABLE"'

结果应如下所示：

  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | table_catalog  | table_schema  |   table_name   | table_type | is_insertable_into |    creation_time    |
  +----------------+---------------+----------------+------------+--------------------+---------------------+
  | myproject      | mydataset     | mytable1       | BASE TABLE | NO                 | 2018-10-31 22:40:05 |
  +----------------+---------------+----------------+------------+--------------------+---------------------+

`TABLE_OPTIONS` 视图

当您查询 INFORMATION_SCHEMA.TABLE_OPTIONS 视图时，查询结果为数据集中的每个表或视图返回一行。

针对 INFORMATION_SCHEMA.TABLE_OPTIONS 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表或视图的数据集。

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

列名	数据类型	值
`TABLE_CATALOG`	`STRING`	包含数据集的项目的名称
`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`	`FLOAT64`	表的默认生命周期（以天为单位）
`kms_key_name`	`STRING`	用于加密表的 Cloud KMS 密钥的名称
`friendly_name`	`STRING`	表的描述性名称
`description`	`STRING`	表的说明
`labels`	`ARRAY<STRUCT<STRING, STRING>>`	一组 `STRUCT`，表示表的标签

如需详细了解数据集属性，请参阅 REST API 文档中的数据集资源页。如需详细了解表和视图属性，请参阅 REST API 文档中的表资源页。

示例

示例 1：

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

针对 INFORMATION_SCHEMA.TABLE_OPTIONS 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

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

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
SELECT
 *
FROM
 mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE
 option_name="expiration_timestamp"
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'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 中。

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
SELECT
 *
FROM
 mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE
 option_name="description" AND option_value LIKE "%test%"
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'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 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

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

列名	数据类型	值
`TABLE_CATALOG`	`STRING`	包含数据集的项目的名称
`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`	列的标准 SQL 数据类型
`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` or `NO` depending on whether the column is a partitioning column
`CLUSTERING_ORDINAL_POSITION`	`STRING`	表的聚簇列中列的偏移量，从 1 开始计数；如果表不是聚簇表，则值为 `NULL`

如需详细了解数据集属性，请参阅 REST API 文档中的数据集资源页。如需详细了解表和视图属性，请参阅 REST API 文档中的表资源页。

示例

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

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

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

IS_GENERATED
GENERATION_EXPRESSION
IS_STORED
IS_UPDATABLE

针对 INFORMATION_SCHEMA.COLUMNS 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
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"
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'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_catalog 和 table_schema：

+------------------------+-------------+------------------+-------------+-----------+-----------+-------------------+------------------------+-----------------------------+
|       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 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

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

列名	数据类型	值
`TABLE_CATALOG`	>`STRING`	包含数据集的项目的名称
`TABLE_SCHEMA`	`STRING`	包含表的数据集的名称（也称为 `datasetId`）
`TABLE_NAME`	`STRING`	表或视图的名称（也称为 `tableId`）
`COLUMN_NAME`	`STRING`	列的名称
`FIELD_PATH`	`STRING`	嵌套在“RECORD”或“STRUCT”列中的列的路径
`DATA_TYPE`	`STRING`	列的标准 SQL 数据类型
`DESCRIPTION`	`STRING`	列的说明

如需详细了解数据集属性，请参阅 REST API 文档中的数据集资源页。如需详细了解表和视图属性，请参阅 REST API 文档中的表资源页。

示例

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

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

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

author：嵌套 RECORD 列
committer：嵌套 RECORD 列
trailer：嵌套和重复 RECORD 列
difference：嵌套和重复 RECORD 列

查询将检索有关 author 和 difference 列的元数据。

针对 INFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

如需运行查询，请执行以下操作：

控制台

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

转到 GCP Console
在查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。
```
SELECT
 *
FROM
 `bigquery-public-data`.github_repos.INFORMATION_SCHEMA.COLUMN_FIELD_PATHS
WHERE
 table_name="commits"
 AND column_name="author"
 OR column_name="difference"
```
注意：INFORMATION_SCHEMA 视图名称区分大小写。
点击运行。

CLI

使用 query 命令并使用 --nouse_legacy_sql 或 --use_legacy_sql=false 标志指定标准 SQL 语法。INFORMATION_SCHEMA 查询要求使用标准 SQL 语法。

如需运行查询，请输入以下命令：

bq query --nouse_legacy_sql \
'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_catalog 和 table_schema。

  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+
  | 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        |
  +------------+-------------+---------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------+

列出数据集中的表

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

使用 GCP Console 或经典版 BigQuery 网页界面
使用 bq ls CLI 命令
调用 tables.list API 方法
使用客户端库

所需权限

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

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

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

列出表

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

控制台

在 GCP Console 的导航窗格中，点击您的数据集将其展开。此时会显示数据集中的表和视图。
滚动列表，查看数据集中的表。表和视图由不同的图标进行标识。

经典版界面

在网页界面的导航窗格中，点击数据集左侧的向下箭头图标展开数据集，或双击数据集名称。此时会显示数据集中的表和视图。
滚动列表，查看数据集中的表。表和视图由不同的图标进行标识。

CLI

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

在 GitHub 上查看反馈


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

在 GitHub 上查看反馈

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

Java

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

在 GitHub 上查看反馈

DatasetId datasetId = DatasetId.of(projectId, datasetName);
Page<Table> tables = bigquery.listTables(datasetId, TableListOption.pageSize(100));
for (Table table : tables.iterateAll()) {
  // do something with the table
}

Node.js

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

在 GitHub 上查看反馈

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

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

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

tables = client.list_tables(dataset_id)

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

在 GitHub 上查看反馈

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

后续步骤

如需详细了解数据集，请参阅数据集简介。
如需详细了解如何处理表数据，请参阅管理表数据。
如需详细了解如何指定表架构，请参阅指定架构。
如需详细了解如何修改表架构，请参阅修改表架构。
如需详细了解如何管理表，请参阅管理表。
如需查看 INFORMATION_SCHEMA 的概览，请转到 BigQuery INFORMATION_SCHEMA 简介。

表限制

创建表

表命名

所需权限

创建具有架构定义的空表

控制台

DDL

经典版界面

CLI

API

C#

Go

Java

Node.js

PHP

Python

Ruby

基于查询结果创建表

控制台

DDL

经典版界面

CLI

API

Go

Java

Python

创建引用外部数据源的表

在加载数据时创建表

控制表的访问权限

使用表

获取表的相关信息

所需权限

获取表信息

控制台

经典版界面

CLI

API

Go

Java

PHP

Python

使用 INFORMATION_SCHEMA 获取表信息（测试版）

TABLES 视图

示例

示例 1：

控制台

CLI

示例 2：

控制台

CLI

TABLE_OPTIONS 视图

选项表

示例

示例 1：

控制台

CLI

示例 2：

控制台

CLI

COLUMNS 视图

示例

控制台

CLI

COLUMN_FIELD_PATHS 视图

示例

控制台

CLI

列出数据集中的表

所需权限

列出表

控制台

经典版界面

CLI

API

C#

Go

Java

Node.js

PHP

使用 `INFORMATION_SCHEMA` 获取表信息（测试版）

`TABLES` 视图

`TABLE_OPTIONS` 视图

`COLUMNS` 视图

`COLUMN_FIELD_PATHS` 视图