创建和使用表

本文档介绍了如何在 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.createbigquery.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 方法时,在表资源中提供架构

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

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

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

控制台

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

  2. 在导航面板的资源部分中,展开您的项目并选择数据集。

  3. 在窗口右侧的详细信息面板中,点击创建表

    创建表

  4. 创建表页面的来源部分,选择空白表

  5. 创建表页面的目标部分,执行以下操作:

    • 数据集名称部分,选择相应的数据集。

      选择数据集

    • 表名称字段中,输入您要在 BigQuery 中创建的表的名称。

    • 确认表类型设置为原生表

  6. 架构部分中,输入架构定义。

    • 通过以下方式,手动输入架构信息:

      • 启用以文本形式修改,并以 JSON 数组格式输入表架构。

      • 使用添加字段手动输入架构。

  7. 对于分区和聚簇设置,保留默认值 (No partitioning)。

  8. 对于高级选项部分的加密,保留默认值 (Google-managed key)。默认情况下,BigQuery 会对以静态方式存储的客户内容进行加密

  9. 点击创建表

DDL

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

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

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

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

  2. 点击编写新查询

  3. 查询编辑器文本区域中,输入 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")]
     )

  4. (可选)点击展开并选择查询设置查询设置

  5. (可选)对于处理位置,点击自动选择并选择数据的位置。如果您将处理位置保留设置为“未指定”,则系统会自动检测处理位置。 查询处理位置

  6. 点击运行。查询完成后,该表将显示在资源窗格中。

经典版界面

  1. 在导航窗格中,点击数据集名称旁边的向下箭头图标 向下箭头图标,然后点击 Create new table

  2. Create Table 页面上的 Source Data 部分中,点击 Create empty table

  3. Create Table 页面的 Destination Table 部分,执行以下操作:

    • 对于 Table name ,选择相应的数据集,然后在表名称字段中输入要创建的表的名称。
    • 确认 Table type 设置为 Native table
  4. Schema 部分中,手动输入架构定义

    • 可通过以下方式手动输入架构信息:

      • 点击 Edit as text,并以 JSON 数组格式输入表架构:

        以 JSON 数组格式添加架构

      • 使用 Add Field 输入架构:

        使用“添加字段”添加架构

  5. Options 部分保留默认值。

    • Partitioning TypeNone
    • Partitioning Field:应该不可用
    • Require partition filter:应该不可用
    • Clustering Fields:应该不可用
    • Destination EncryptionDefault 默认情况下,BigQuery 会使用 Google 管理的密钥对以静态方式存储的客户内容进行加密
  6. 点击 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 架构文件创建表。该命令会在 myotherprojectmydataset 中创建一个名为 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 参考文档


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

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

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

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

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

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

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

基于查询结果创建表

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

控制台

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

    转到 GCP Console

  2. 在导航面板的资源部分中,展开您的项目并选择数据集。

  3. 如果查询编辑器处于隐藏状态,请点击窗口右上角的显示编辑器

  4. 查询编辑器文本区域中输入有效的 SQL 查询。

  5. 点击编辑器下方的更多,然后选择查询设置

    查询设置

  6. 勾选该方框,为查询结果设置目标表

    设置目标位置

  7. 目标位置部分,选择要在其中创建表的相应项目名称数据集名称,然后选择表名称

  8. 目标表的写入设置部分,选择以下选项之一:

    • 只写入空白表 - 仅在表为空时才将查询结果写入表。
    • 附加到表 - 将查询结果附加到现有表。
    • 覆盖表 - 使用查询结果覆盖名称相同的现有表。
  9. (可选)在处理位置部分,点击自动选择并选择您的位置

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

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

DDL

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

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

经典版界面

  1. 转到经典版 BigQuery 网页界面。
    转到经典版 BigQuery 网页界面

  2. 点击 Compose query 按钮。

  3. New Query 文本区域中输入有效的 SQL 查询。

  4. 点击 Show Options

  5. Destination Table 部分,点击 Select Table

  6. Select Destination Table 对话框中,执行以下操作:

    1. 对于 Project,选择一个用于存储数据集和表的项目。

    2. 对于 Dataset,选择用于存储表的数据集。

    3. Table ID 字段中,输入表名称。该名称在目标数据集中必须是唯一的。表名称最长可达 1024 个字符,并且只能包含 a-z、A-Z、0-9 或 _(下划线字符)。

    4. 点击 OK

  7. Destination Table 部分的 Write Preference 中,选择以下某个选项:

    • Write if empty - 仅在表为空时才将查询结果写入表。
    • Append to table - 将查询结果附加到现有表。
    • Overwrite table - 使用查询结果覆盖名称相同的现有表。
  8. (可选)在 Processing Location 部分,点击 Unspecified 并选择数据的位置

  9. 点击 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 参考文档

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

// 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。将作业配置传递给查询方法

# 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 角色和权限,请参阅访问权限控制

获取表信息

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

控制台

  1. 在导航面板的资源部分中,展开您的项目并选择数据集。点击数据集名称,将其展开。此时会显示数据集中的表和视图。

  2. 点击表名称。

  3. 在编辑器下方,点击详细信息。此页面会显示表说明和表信息。

  4. 点击架构标签页,查看表的架构定义。

经典版界面

  1. 在导航窗格中,点击数据集左侧的向下箭头图标 向下箭头图标 展开数据集,或双击数据集名称。此时会显示数据集中的表和视图。

  2. 点击表名称。

  3. 点击 DetailsTable Details 页面会显示表说明和表信息。

    查看表详细信息

  4. 点击 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 的所有信息。mydatasetmyotherproject 中,不在默认项目中。

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

输入以下命令可仅显示有关 mydataset 中的 mytable 的架构信息。mydatasetmyotherproject 中,不在默认项目中。

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

API

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

Go

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

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

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

PHP

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

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

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.TABLESINFORMATION_SCHEMA.TABLE_OPTIONS 视图,检索关于项目中的表和视图的元数据。您还可以查询 INFORMATION_SCHEMA.COLUMNSINFORMATION_SCHEMA.COLUMN_FIELD_PATHS 视图以检索关于表中的列(字段)的元数据。

TABLESTABLE_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 表类型:
IS_INSERTABLE_INTO STRING YESNO,具体取决于表是否支持 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

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    
  3. 点击运行

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

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

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。

    SELECT
     * EXCEPT(is_typed)
    FROM
     mydataset.INFORMATION_SCHEMA.TABLES
    WHERE
     table_type="BASE TABLE"
    
  3. 点击运行

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

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="expiration_timestamp"
    
  3. 点击运行

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 中。

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

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 SQL 查询。 INFORMATION_SCHEMA 要求使用标准 SQL 语法。标准 SQL 是 GCP Console 中的默认语法。

    SELECT
     *
    FROM
     mydataset.INFORMATION_SCHEMA.TABLE_OPTIONS
    WHERE
     option_name="description" AND option_value LIKE "%test%"
    
  3. 点击运行

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 YESNO,具体取决于列的模式是否允许使用 NULL
DATA_TYPE STRING 列的标准 SQL 数据类型
IS_GENERATED STRING 值始终为 NEVER
GENERATION_EXPRESSION STRING 值始终为 NULL
IS_STORED STRING 值始终为 NULL
IS_HIDDEN STRING YESNO,具体取决于列是否为伪列,例如 _PARTITIONTIME 或 _PARTITIONDATE
IS_UPDATABLE STRING 值始终为 NULL
IS_SYSTEM_DEFINED STRING YESNO,具体取决于列是否为伪列,例如 _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 视图的查询必须具有数据集限定符。提交查询的用户必须能够访问包含这些表的数据集。

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 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"
    
  3. 点击运行

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

查询将检索有关 authordifference 列的元数据。

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

如需运行查询,请执行以下操作:

控制台

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

    转到 GCP Console

  2. 查询编辑器框中输入以下标准 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"
    
  3. 点击运行

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_catalogtable_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 角色和权限,请参阅访问权限控制

列出表

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

控制台

  1. 在 GCP Console 的导航窗格中,点击您的数据集将其展开。此时会显示数据集中的表和视图。

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

经典版界面

  1. 在网页界面的导航窗格中,点击数据集左侧的向下箭头图标 向下箭头图标 展开数据集,或双击数据集名称。此时会显示数据集中的表和视图。

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

    查看表

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 字段会显示 TABLEVIEW。例如:

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


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

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

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

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

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

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

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

后续步骤

此页内容是否有用?请给出您的反馈和评价:

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面