指定架构

通过 BigQuery，您可以在将数据加载到表中以及创建空表时指定表架构。对于支持的数据格式，您还可以使用架构自动检测功能。

加载 Avro、Parquet、ORC、Firestore 导出文件或 Datastore 导出文件时，系统会自动从自描述源数据中检索架构。

您可以通过以下方式指定表的架构：

• 使用 Google Cloud 控制台。
• 使用 CREATE TABLE SQL 语句。
• 使用 bq 命令行工具以内嵌方式提供。
• 创建 JSON 格式的架构文件。
• 调用 jobs.insert 方法并在 load 作业配置中配置 schema 属性。
• 调用 tables.insert 方法并使用 schema 属性在表资源中配置架构。

加载数据或创建空表之后，您可以修改表的架构定义。

架构组件

指定表架构时，必须提供每个列的名称和数据类型。您还可以提供列的说明、模式和默认值。

列名称

列名称可以包含字母（a-z、A-Z）、数字 (0-9) 或下划线 (_)，并且必须以字母或下划线开头。如果使用灵活的列名称，则 BigQuery 支持列名称以数字开头。列以数字开头时要格外注意，因为将灵活的列名称与 BigQuery Storage Read API 或 BigQuery Storage Write API 搭配使用需要特殊处理。如需详细了解灵活的列名称支持，请参阅灵活的列名称。

列名称的长度不得超过 300 个字符。列名称不能使用以下任何前缀：

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER
• _CHANGE_SEQUENCE_NUMBER
• _CHANGE_TYPE
• _CHANGE_TIMESTAMP

列名不可重复，即使其大小写不同也不行。例如，名为 Column1 的列和名为 column1 的列被视作相同。如需详细了解列命名规则，请参阅 GoogleSQL 参考文档中的列名称。

如果表名称（例如 test）与其一个列名称（例如 test）相同，则 SELECT 表达式会将 test 列解释为包含所有其他表列的 STRUCT。如需避免这种冲突，请使用以下方法之一：

• 避免为表及其列使用相同的名称。

• 避免使用 _field_ 作为列名前缀。系统预留的前缀会导致在查询期间自动重命名。例如，SELECT _field_ FROM project1.dataset.test 查询会返回一个名为 _field_1 的列。如果您必须查询具有此名称的列，请使用别名来控制输出。

• 为表分配其他别名。例如，以下查询会为表 project1.dataset.test 分配表别名 t：

  SELECT test FROM project1.dataset.test AS t;
  

• 引用列时添加表名称。例如：

  SELECT test.test FROM project1.dataset.test;
  

灵活的列名称

您可以更灵活地命名列，包括扩展使用非英语字符以及其他符号。 如果灵活的列名称是带引号的标识符，请务必使用反引号 (`) 字符将其括起来。

灵活的列名称支持以下字符：

• 任何语言的任何字母，由 Unicode 正则表达式 \p{L} 表示。
• 任何语言的任何数字字符，由 Unicode 正则表达式 \p{N} 表示。
• 任何由 Unicode 正则表达式 \p{Pc} 表示的连接器标点符号（包括下划线）。
• 连字符或短划线（由 Unicode 正则表达式 \p{Pd} 表示）。
• 任何伴随另一个字符的标记，由 Unicode 正则表达式 \p{M} 表示。例如重音符号、变音符号或括起的框。
• 以下特殊字符：
  • 与符号 (&)，由 Unicode 正则表达式 \u0026 表示。
  • 百分号 (%)，由 Unicode 正则表达式 \u0025 表示。
  • 等号 (=)，由 Unicode 正则表达式 \u003D 表示。
  • 加号 (+)，由 Unicode 正则表达式 \u002B 表示。
  • 冒号 (:)，由 Unicode 正则表达式 \u003A 表示。
  • 撇号 (')，由 Unicode 正则表达式 \u0027 表示。
  • 小于符号 (<)，以 Unicode 正则表达式 \u003C 表示。
  • 大于符号 (>)，由 Unicode 正则表达式 \u003E 表示。
  • 井号 (#)，由 Unicode 正则表达式 \u0023 表示。
  • 竖线 (|)，由 Unicode 正则表达式 \u007c 表示。
  • 空格。

灵活的列名称不支持以下特殊字符：

• 感叹号 (!)，由 Unicode 正则表达式 \u0021 表示。
• 引号 (")，由 Unicode 正则表达式 \u0022 表示。
• 美元符号 ($)，由 Unicode 正则表达式 \u0024 表示。
• 左括号 (()，由 Unicode 正则表达式 \u0028 表示。
• 右括号 ())，由 Unicode 正则表达式 \u0029 表示。
• 星号 (*)，由 Unicode 正则表达式 \u002A 表示。
• 逗号 (,)，由 Unicode 正则表达式 \u002C 表示。
• 由 Unicode 正则表达式 \u002E 表示的英文句号 (.)。 使用列名称字符映射时，Parquet 文件列名称中的句点不会被下划线替换。如需了解详情，请参阅灵活列限制。
• 正斜杠 (/)，由 Unicode 正则表达式 \u002F 表示。
• 分号 (;)，由 Unicode 正则表达式 \u003B 表示。
• 问号 (?)，由 Unicode 正则表达式 \u003F 表示。
• 由 Unicode 正则表达式 \u0040 表示的 @ 符号 (@)。
• 左方括号 ([)，由 Unicode 正则表达式 \u005B 表示。
• 反斜杠 (\)，由 Unicode 正则表达式 \u005C 表示。
• 右方括号 (])，由 Unicode 正则表达式 \u005D 表示。
• 扬抑符 (^)，由 Unicode 正则表达式 \u005E 表示。
• 重音符号 (`)，由 Unicode 正则表达式 \u0060 表示。
• 左花括号 ({)，由 Unicode 正则表达式 \u007B 表示。
• 右花括号 (})，由 Unicode 正则表达式 \u007D 表示。
• 波浪号 (~)，由 Unicode 正则表达式 \u007E 表示。

如需了解其他准则，请参阅列名称。

BigQuery Storage Read API 和 BigQuery Storage Write API 都支持扩展的列字符。如需将扩展的 Unicode 字符列表与 BigQuery Storage Read API 搭配使用，您必须设置标志。您可以使用 displayName 属性检索列名称。以下示例展示了如何使用 Python 客户端来设置标志：

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

如需将扩展的 Unicode 字符列表与 BigQuery Storage Write API 搭配使用，您必须提供采用 column_name 表示法的架构，除非您使用的是 JsonStreamWriter 写入器对象。以下示例展示了如何提供架构：

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

在此示例中，item_name_column 和 item_description_column 是需要遵循协议缓冲区命名惯例的占位名称。请注意，column_name 注解始终优先于占位名称。

限制

• 外部表不支持灵活的列名称。

列说明

每个列均可以选择性地包含说明信息。说明就是一个字符串，长度最大为 1024 个字符。

默认值

列的默认值必须是一个字面量或者是以下一种函数：

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

GoogleSQL 数据类型

GoogleSQL 使您可以在架构中指定以下数据类型。数据类型是必需的。

如需详细了解 GoogleSQL 中的数据类型，请参阅 GoogleSQL 数据类型。

您还可以在查询数据时声明数组类型。如需了解详情，请参阅使用数组。

模式

BigQuery 支持列的以下模式。模式是可选的。如果未指定模式，则列默认为 NULLABLE。

如需详细了解模式，请参阅 TableFieldSchema 中的 mode。

舍入模式

某列是 NUMERIC 或 BIGNUMERIC 类型时，您可以设置 rounding_mode 列选项，用于确定该列中的值在写入表时的舍入方式。您可以在顶级列或 STRUCT 字段上设置 rounding_mode 选项。支持以下四舍五入模式：

• "ROUND_HALF_AWAY_FROM_ZERO"：此模式（默认）会将中间数向远离 0 的方向舍入。
• "ROUND_HALF_EVEN"：此模式会将中间数舍入到最接近的偶数。

您无法为非 NUMERIC 或 BIGNUMERIC 类型的列设置 rounding_mode 选项。如需详细了解这些类型，请参阅小数类型。

以下示例会创建表并插入基于列的舍入模式进行舍入的值：

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

mytable 表如下所示：

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

如需了解详情，请参阅 TableFieldSchema 中的 roundingMode。

指定架构

在加载数据或创建空表时，您可以使用 Google Cloud 控制台或 bq 命令行工具指定表架构。加载 CSV 和 JSON（换行符分隔）文件时，系统支持指定架构。加载 Avro、Parquet、ORC、Firestore 导出数据或 Datastore 导出数据时，系统会自动从自描述源数据中检索架构。

如需指定表架构，请执行以下操作：

bq --location=location load \
--source_format=format \
project_id:dataset.table_name \
path_to_source \
schema

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

bq mk --table project_id:dataset.table schema

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public