MCP Tools Reference: bigquery.googleapis.com

工具：get_table_info

获取有关 BigQuery 表的元数据信息。

以下示例演示了如何使用 curl 调用 get_table_info MCP 工具。

Curl 请求 
                  
curl --location 'https://bigquery.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "get_table_info",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

申请表格。

JSON 表示法 
{
  "projectId": string,
  "datasetId": string,
  "tableId": string
}
字段
projectId

string

必需。表请求的项目 ID。
datasetId

string

必需。表请求的数据集 ID。
tableId

string

必需。表请求的表 ID。

输出架构

JSON 表示法 
{
  "kind": string,
  "etag": string,
  "id": string,
  "selfLink": string,
  "tableReference": {
    object (TableReference)
  },
  "friendlyName": string,
  "description": string,
  "labels": {
    string: string,
    ...
  },
  "schema": {
    object (TableSchema)
  },
  "timePartitioning": {
    object (TimePartitioning)
  },
  "rangePartitioning": {
    object (RangePartitioning)
  },
  "clustering": {
    object (Clustering)
  },
  "requirePartitionFilter": boolean,
  "numBytes": string,
  "numPhysicalBytes": string,
  "numLongTermBytes": string,
  "numRows": string,
  "creationTime": string,
  "expirationTime": string,
  "lastModifiedTime": string,
  "type": string,
  "view": {
    object (ViewDefinition)
  },
  "materializedView": {
    object (MaterializedViewDefinition)
  },
  "materializedViewStatus": {
    object (MaterializedViewStatus)
  },
  "externalDataConfiguration": {
    object (ExternalDataConfiguration)
  },
  "biglakeConfiguration": {
    object (BigLakeConfiguration)
  },
  "managedTableType": enum (ManagedTableType),
  "location": string,
  "streamingBuffer": {
    object (Streamingbuffer)
  },
  "encryptionConfiguration": {
    object (EncryptionConfiguration)
  },
  "snapshotDefinition": {
    object (SnapshotDefinition)
  },
  "defaultCollation": string,
  "defaultRoundingMode": enum (RoundingMode),
  "cloneDefinition": {
    object (CloneDefinition)
  },
  "numTimeTravelPhysicalBytes": string,
  "numTotalLogicalBytes": string,
  "numActiveLogicalBytes": string,
  "numLongTermLogicalBytes": string,
  "numCurrentPhysicalBytes": string,
  "numTotalPhysicalBytes": string,
  "numActivePhysicalBytes": string,
  "numLongTermPhysicalBytes": string,
  "numPartitions": string,
  "maxStaleness": string,
  "restrictions": {
    object (RestrictionConfig)
  },
  "tableConstraints": {
    object (TableConstraints)
  },
  "resourceTags": {
    string: string,
    ...
  },
  "tableReplicationInfo": {
    object (TableReplicationInfo)
  },
  "replicas": [
    {
      object (TableReference)
    }
  ],
  "externalCatalogTableOptions": {
    object (ExternalCatalogTableOptions)
  },

  // Union field _partition_definition can be only one of the following:
  "partitionDefinition": {
    object (PartitioningDefinition)
  }
  // End of list of possible types for union field _partition_definition.
}
字段
kind

string

资源 ID 的类型。
etag

string

仅限输出。相应资源的哈希值。
id

string

仅限输出。唯一标识相应表的不透明 ID。
selfLink

string

仅限输出。可用于再次访问相应资源的网址。
tableReference

object (TableReference)

必需。用于描述此表 ID 的参考。
friendlyName

string

可选。此表的描述性名称。
description

string

可选。此表的简单易懂的说明。
labels

map (key: string, value: string)

与相应表关联的标签。您可以使用这些功能来整理和分组表格。标签键和值不得超过 63 个字符，并且只能包含小写字母、数字字符、下划线和短划线。允许使用国际字符。标签值是可选的。标签键必须以字母开头，并且列表中的每个标签都必须具有不同的键。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
schema

object (TableSchema)

可选。描述此表的架构。
timePartitioning

object (TimePartitioning)

如果指定，则为此表配置基于时间的分区。
rangePartitioning

object (RangePartitioning)

如果指定，则为此表配置范围分区。
clustering

object (Clustering)

表的聚簇规范。必须与基于时间的分区一起指定，表中的数据将先进行分区，然后再进行聚簇。
requirePartitionFilter

boolean

可选。如果设置为 true，则对此表进行的所有查询都需要指定可用于执行分区消除的分区过滤条件。
numBytes

string (Int64Value format)

仅限输出。相应表的大小（以逻辑字节为单位），不包括流式缓冲区中的任何数据。
numPhysicalBytes

string (Int64Value format)

仅限输出。相应表在物理上所占的大小（以字节为单位）。这包括用于时间旅行的存储空间。
numLongTermBytes

string (Int64Value format)

仅限输出。表中被视为“长期存储”的逻辑字节数。
numRows

string (UInt64Value format)

仅限输出。相应表中的数据行数，不包括流式缓冲区中的任何数据。
creationTime

string (int64 format)

仅限输出。相应表的创建时间，以自纪元以来的毫秒数表示。
expirationTime

string (Int64Value format)

可选。相应表的过期时间（以毫秒为单位，从纪元开始计算）。如果未提供，则表将无限期保留。过期的表将被删除，其存储空间将被回收。封装数据集的 defaultTableExpirationMs 属性可用于为新创建的表设置默认的 expirationTime。
lastModifiedTime

string (uint64 format)

仅限输出。相应表的上次修改时间（以自纪元以来经历的毫秒数表示）。
type

string

仅限输出。描述表类型。支持以下值：

  • TABLE：常规 BigQuery 表。
  • VIEW：由 SQL 查询定义的虚拟表。
  • EXTERNAL：引用存储在外部存储系统（例如 Google Cloud Storage）中的数据的表。
  • MATERIALIZED_VIEW：由 SQL 查询定义的预计算视图。
  • SNAPSHOT：一种不可变的 BigQuery 表，用于保留基表在特定时间的内容。如需了解详情，请参阅表快照。

默认值为 TABLE。
view

object (ViewDefinition)

可选。视图定义。
materializedView

object (MaterializedViewDefinition)

可选。具体化视图定义。
materializedViewStatus

object (MaterializedViewStatus)

仅限输出。具体化视图状态。
externalDataConfiguration

object (ExternalDataConfiguration)

可选。描述了存储在 BigQuery 外部的表的数据格式、位置和其他属性。定义这些属性后，就可以像查询标准 BigQuery 表一样查询数据源。
biglakeConfiguration

object (BigLakeConfiguration)

可选。指定 Apache Iceberg 的 BigQuery 表的配置。
managedTableType

enum (ManagedTableType)

可选。如果设置，则会替换数据集中配置的默认受管理表类型。
location

string

仅限输出。相应表所在的地理位置。此值继承自数据集。
streamingBuffer

object (Streamingbuffer)

仅限输出。包含有关相应表的流式缓冲区的信息（如果有）。如果表未进行流式传输，或者流式缓冲区中没有数据，则此字段将不存在。
encryptionConfiguration

object (EncryptionConfiguration)

自定义加密配置（例如，Cloud KMS 密钥）。
snapshotDefinition

object (SnapshotDefinition)

仅限输出。包含有关快照的信息。此值通过创建快照来设置。
defaultCollation

string

可选。定义表中新 STRING 字段的默认排序规则规范。在创建或更新表期间，如果向该表添加了 STRING 字段但未明确指定排序规则，则该表会继承表默认排序规则。对此字段的更改只会影响之后添加的字段，不会更改现有字段。支持以下值：

  • 'und:ci'：未确定的语言区域，不区分大小写。
  • ''：空字符串。默认区分大小写。
defaultRoundingMode

enum (RoundingMode)

可选。定义表中新的十进制字段（NUMERIC 或 BIGNUMERIC）的默认舍入模式规范。在创建或更新表期间，如果向该表添加了未明确指定舍入模式的十进制字段，则该字段会继承表的默认舍入模式。更改此字段不会影响现有字段。
cloneDefinition

object (CloneDefinition)

仅限输出。包含有关克隆的信息。此值通过克隆操作设置。
numTimeTravelPhysicalBytes

string (Int64Value format)

仅限输出。时间旅行存储（已删除或已更改的数据）使用的物理字节数。此数据不会实时保留，可能会延迟几秒钟到几分钟。
numTotalLogicalBytes

string (Int64Value format)

仅限输出。表或具体化视图中的逻辑字节总数。
numActiveLogicalBytes

string (Int64Value format)

仅限输出。存在时间不超过 90 天的逻辑字节数。
numLongTermLogicalBytes

string (Int64Value format)

仅限输出。存在时间超过 90 天的逻辑字节数。
numCurrentPhysicalBytes

string (Int64Value format)

仅限输出。当前实时数据存储使用的物理字节数。此数据不会实时保留，可能会延迟几秒钟到几分钟。
numTotalPhysicalBytes

string (Int64Value format)

仅限输出。相应表在物理上所占的大小（以字节为单位）。这还包括用于时间旅行的存储空间。此数据不会实时保留，可能会延迟几秒钟到几分钟。
numActivePhysicalBytes

string (Int64Value format)

仅限输出。存在时间少于 90 天的物理字节数。此数据不会实时保留，可能会延迟几秒钟到几分钟。
numLongTermPhysicalBytes

string (Int64Value format)

仅限输出。存在时间超过 90 天的物理字节数。此数据不会实时保留，可能会延迟几秒钟到几分钟。
numPartitions

string (Int64Value format)

仅限输出。表或具体化视图中存在的分区数量。此数据不会实时保留，可能会延迟几秒钟到几分钟。
maxStaleness

string

可选。查询表（或过时的具体化视图）时可能返回的数据的最大过时时间。以 SQL IntervalValue 类型的字符串编码形式表示的陈旧度。
restrictions

object (RestrictionConfig)

可选。仅限输出。表的限制配置。如果设置，则根据配置限制对表的某些访问权限。如需了解详情，请参阅数据出站流量。
tableConstraints

object (TableConstraints)

可选。表主键和外键信息
resourceTags

map (key: string, value: string)

可选。附加到相应表的标记。标记键是全局唯一的。标记键应采用命名空间格式，例如“123456789012/environment”，其中 123456789012 是相应标记键的父组织或项目资源的 ID。标记值应为简称，例如“生产环境”。如需了解详情，请参阅标记定义。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
tableReplicationInfo

object (TableReplicationInfo)

可选。使用 AS REPLICA DDL（例如 CREATE MATERIALIZED VIEW mv1 AS REPLICA OF src_mv）创建的表的复制信息
replicas[]

object (TableReference)

可选。仅限输出。当前在相应表上处于活动状态的所有副本的表引用。
externalCatalogTableOptions

object (ExternalCatalogTableOptions)

可选。用于定义开源兼容表的选项。

联合字段 _partition_definition。

_partition_definition 只能是下列其中一项：
partitionDefinition

object (PartitioningDefinition)

可选。所有表格式（包括受管理的分区表、Hive 分区表、Iceberg 分区表和 Metastore 分区表）的分区信息。此字段仅针对元存储区分区表进行填充。对于其他表格格式，此字段仅限输出。
JSON 表示法 
{
  "projectId": string,
  "datasetId": string,
  "tableId": string,
  "projectIdAlternative": [
    string
  ],
  "datasetIdAlternative": [
    string
  ],
  "tableIdAlternative": [
    string
  ]
}
字段
projectId

string

必需。包含相应表的项目的 ID。
datasetId

string

必需。包含相应表的相应数据集的 ID。
tableId

string

必需。表格的 ID。ID 可以包含类别 L（字母）、M（符号）、N（数字）、Pc（连接符，包括下划线）、Pd（短划线）和 Zs（空格）中的 Unicode 字符。如需了解详情，请参阅常规类别。最大长度为 1,024 个字符。某些操作允许在表 ID 后面添加分区修饰器，例如 sample_table$20190123。
projectIdAlternative[]

string

不应使用此字段。
datasetIdAlternative[]

string

不应使用此字段。
tableIdAlternative[]

string

不应使用此字段。
JSON 表示法 
{
  "value": string
}
字段
value

string

字符串值。
JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string
JSON 表示法 
{
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "foreignTypeInfo": {
    object (ForeignTypeInfo)
  }
}
字段
fields[]

object (TableFieldSchema)

描述表格中的字段。
foreignTypeInfo

object (ForeignTypeInfo)

可选。指定字段架构 (TableFieldSchema.foreign_type_definition) 中外部数据类型定义的元数据。
JSON 表示法 
{
  "name": string,
  "type": string,
  "mode": string,
  "fields": [
    {
      object (TableFieldSchema)
    }
  ],
  "description": string,
  "policyTags": {
    object (PolicyTagList)
  },
  "dataPolicies": [
    {
      object (DataPolicyOption)
    }
  ],
  "nameAlternative": [
    string
  ],
  "maxLength": string,
  "precision": string,
  "scale": string,
  "timestampPrecision": string,
  "roundingMode": enum (RoundingMode),
  "collation": string,
  "defaultValueExpression": string,
  "rangeElementType": {
    object (FieldElementType)
  },
  "foreignTypeDefinition": string
}
字段
name

string

必需。字段名称。名称只能包含字母（a-z、A-Z）、数字 (0-9) 或下划线 (_)，并且必须以字母或下划线开头。长度上限为 300 个字符。
type

string

必需。字段数据类型。可能的值包括：

  • STRING
  • BYTES
  • INTEGER（或 INT64）
  • FLOAT（或 FLOAT64）
  • BOOLEAN（或 BOOL）
  • 时间戳
  • DATE
  • 时间
  • DATETIME
  • GEOGRAPHY
  • NUMERIC
  • BIGNUMERIC
  • JSON
  • RECORD（或 STRUCT）
  • RANGE

使用 RECORD/STRUCT 表示相应字段包含嵌套的架构。
mode

string

可选。字段模式。可能的值包括 NULLABLE、REQUIRED 和 REPEATED。默认值为 NULLABLE。
fields[]

object (TableFieldSchema)

可选。如果 type 属性设置为 RECORD，则描述嵌套的架构字段。
description

string

可选。字段说明。最大长度为 1,024 个字符。
policyTags

object (PolicyTagList)

可选。附加到此字段的政策标记，用于字段级访问权限控制。如果未设置，则默认为空 policy_tags。
dataPolicies[]

object (DataPolicyOption)

可选。附加到此字段的数据政策，用于字段级访问权限控制。
nameAlternative[]

string

不应使用此字段。
maxLength

string (int64 format)

可选。STRING 或 BYTES 的相应字段值的最大长度。

如果未指定 max_length，则此字段没有长度上限限制。

如果 type = "STRING"，则 max_length 表示相应字段中字符串的最大 UTF-8 长度。

如果 type = "BYTES"，则 max_length 表示相应字段中的最大字节数。

如果类型不为“STRING”且不为“BYTES”，则设置此字段无效。
precision

string (int64 format)

可选。NUMERIC 或 BIGNUMERIC 的相应字段值的精度（以 10 为底的总位数上限）和比例（以 10 为底的小数部分位数上限）限制。

如果类型不为“NUMERIC”且不为“BIGNUMERIC”，则设置精度或小数位数无效。

如果未指定精度和比例，则不会对此字段施加任何值范围限制，只要值符合相应类型即可。

当出现以下情况时，相应 NUMERIC 或 BIGNUMERIC 字段的值必须在此范围内：

  • 指定了精确度 (P) 和缩放比例 (S)：[-10P-S + 10-S, 10P-S - 10-S]
  • 指定了精度 (P)，但未指定标度（因此标度被解读为等于零）：[-10P + 1, 10P - 1]。

如果同时指定了精度和标度，则可接受的值如下：

  • 如果 type = "NUMERIC"：1 ≤ precision - scale ≤ 29 且 0 ≤ scale ≤ 9。
  • 如果 type = "BIGNUMERIC"：1 ≤ 精度 - 标度 ≤ 38 且 0 ≤ 标度 ≤ 38。

如果仅指定了精度，而未指定小数位数（因此小数位数被解读为零），则可接受的精度值如下：

  • 如果 type = "NUMERIC"：1 ≤ precision ≤ 29。
  • 如果 type = "BIGNUMERIC"，则 1 ≤ precision ≤ 38。

如果指定了小数位数，但未指定总位数，则无效。
scale

string (int64 format)

可选。如需了解精度，请参阅文档。
timestampPrecision

string (Int64Value format)

可选。TIMESTAMP 类型的秒的精度（以 10 为底的总位数上限）。

可能的值包括：* 6（默认值，适用于精确到微秒的 TIMESTAMP 类型）* 12（适用于精确到皮秒的 TIMESTAMP 类型）
roundingMode

enum (RoundingMode)

可选。指定存储 NUMERIC 和 BIGNUMERIC 类型的值时要使用的舍入模式。
collation

string

可选。只有当字段的类型为 STRING 时，才能设置字段排序规则。支持以下值：

  • 'und:ci'：未确定的语言区域，不区分大小写。
  • ''：空字符串。默认区分大小写。
defaultValueExpression

string

可选。用于指定相应字段的默认值的 SQL 表达式。
rangeElementType

object (FieldElementType)

可选。如果相应字段的类型为 RANGE，则为 RANGE 的子类型。如果类型为 RANGE，则此字段为必填字段。字段元素类型的值可以是以下任一值：

  • DATE
  • DATETIME
  • 时间戳
foreignTypeDefinition

string

可选。外部数据类型的定义。仅对顶级架构字段（而非嵌套字段）有效。如果类型为 FOREIGN，则此字段为必填字段。
JSON 表示法 
{
  "names": [
    string
  ]
}
字段
names[]

string

政策标记资源名称的列表。例如，“projects/1/locations/eu/taxonomies/2/policyTags/3”。目前最多允许添加 1 个政策标记。
JSON 表示法 
{

  // Union field _name can be only one of the following:
  "name": string
  // End of list of possible types for union field _name.
}
字段

联合字段 _name。

_name 只能是下列其中一项：
name

string

数据政策资源名称，格式为 projects/project_id/locations/location_id/dataPolicies/data_policy_id。
JSON 表示法 
{
  "value": string
}
字段
value

string (int64 format)

int64 值。
JSON 表示法 
{
  "type": string
}
字段
type

string

必需。字段元素的类型。如需了解详情，请参阅TableFieldSchema.type。
JSON 表示法 
{
  "typeSystem": enum (TypeSystem)
}
字段
typeSystem

enum (TypeSystem)

必需。指定定义外部数据类型的系统。
JSON 表示法 
{
  "type": string,
  "expirationMs": string,
  "field": string,
  "requirePartitionFilter": boolean
}
字段
type

string

必需。支持的类型包括 DAY、HOUR、MONTH 和 YEAR，它们分别会每天、每小时、每月和每年生成一个分区。
expirationMs

string (Int64Value format)

可选。分区存储空间的保留时长（以毫秒为单位）。此处使用封装容器，因为 0 是无效值。
field

string

可选。如果未设置，则按伪列“_PARTITIONTIME”对表进行分区；如果已设置，则按此字段对表进行分区。该字段必须是顶级 TIMESTAMP 或 DATE 字段。其模式必须为 NULLABLE 或 REQUIRED。此处使用封装容器是因为空字符串是无效值。
requirePartitionFilter
(deprecated)

boolean

如果设置为 true，则对此表进行的所有查询都需要指定可用于执行分区消除的分区过滤条件。此字段已弃用；请改为在表本身上设置同名字段。此字段需要封装容器，因为我们希望在用户明确设置该字段时输出默认值 false。
JSON 表示法 
{
  "value": boolean
}
字段
value

boolean

布尔值。
JSON 表示法 
{
  "field": string,
  "range": {
    object (Range)
  }
}
字段
field

string

必需。用于对表进行分区的列的名称。它必须是顶级 INT64 列，且模式为 NULLABLE 或 REQUIRED。
range

object (Range)

定义范围分区的范围。
JSON 表示法 
{
  "start": string,
  "end": string,
  "interval": string
}
字段
start

string

必需。范围分区的起始值（含边界值）。此字段是一个以字符串形式表示的 INT64 值。
end

string

必需。范围分区的终止值（不含边界值）。此字段是一个以字符串形式表示的 INT64 值。
interval

string

必需。每个区间的宽度。此字段是一个以字符串形式表示的 INT64 值。
JSON 表示法 
{
  "fields": [
    string
  ]
}
字段
fields[]

string

应根据哪些字段对数据进行聚类。仅支持顶级非重复简单类型字段。聚类字段的排序应按过滤目的从最重要到最不重要进行优先排序。

如需了解详情，请参阅聚簇表简介。
JSON 表示法 
{
  "partitionedColumn": [
    {
      object (PartitionedColumn)
    }
  ]
}
字段
partitionedColumn[]

object (PartitionedColumn)

可选。有关每个分区列的详细信息。对于元存储区分区表以外的所有分区类型，此字段仅用于输出。BigQuery 原生表仅支持 1 个分区列。其他表类型可能支持 0 个、1 个或多个分区列。对于 metastore 分区表，顺序必须与 Hive Metastore 中的定义顺序一致，并且必须与表的物理布局一致。例如，

CREATE TABLE a_table(id BIGINT, name STRING) PARTITIONED BY (city STRING, state STRING).

在这种情况下，值必须按此顺序排列：['city', 'state']。
JSON 表示法 
{

  // Union field _field can be only one of the following:
  "field": string
  // End of list of possible types for union field _field.
}
字段

联合字段 _field。

_field 只能是下列其中一项：
field

string

必需。分区列的名称。
JSON 表示法 
{
  "value": string
}
字段
value

string

uint64 值。
JSON 表示法 
{
  "query": string,
  "userDefinedFunctionResources": [
    {
      object (UserDefinedFunctionResource)
    }
  ],
  "useLegacySql": boolean,
  "useExplicitColumnNames": boolean,
  "privacyPolicy": {
    object (PrivacyPolicy)
  },
  "foreignDefinitions": [
    {
      object (ForeignViewDefinition)
    }
  ]
}
字段
query

string

必需。在引用视图时，BigQuery 执行的查询。
userDefinedFunctionResources[]

object (UserDefinedFunctionResource)

描述查询中使用的用户定义的函数资源。
useLegacySql

boolean

指定是否为此视图使用 BigQuery 的旧版 SQL。默认值为 true。 如果设置为 false，视图将使用 BigQuery 的 GoogleSQL：https://cloud.google.com/bigquery/sql-reference/

引用此视图的查询和视图必须使用相同的标志值。此处使用封装容器是因为默认值为 True。
useExplicitColumnNames

boolean

如果明确指定了列名称，则为 True。例如，使用“CREATE VIEW v(c1, c2) AS ...”语法。只能为 GoogleSQL 视图设置。
privacyPolicy

object (PrivacyPolicy)

可选。指定视图的隐私权政策。
foreignDefinitions[]

object (ForeignViewDefinition)

可选。外部视图表示形式。
JSON 表示法 
{
  "resourceUri": string,
  "inlineCode": string,
  "inlineCodeAlternative": [
    string
  ]
}
字段
resourceUri

string

[选择一项] 要从 Google Cloud Storage URI (gs://bucket/path) 加载的代码资源。
inlineCode

string

[选择一项] 包含用户定义的函数 (UDF) 代码的内嵌资源。提供内嵌代码资源相当于提供包含相同代码的文件的 URI。
inlineCodeAlternative[]

string
JSON 表示法 
{

  // Union field privacy_policy can be only one of the following:
  "aggregationThresholdPolicy": {
    object (AggregationThresholdPolicy)
  },
  "differentialPrivacyPolicy": {
    object (DifferentialPrivacyPolicy)
  }
  // End of list of possible types for union field privacy_policy.

  // Union field _join_restriction_policy can be only one of the following:
  "joinRestrictionPolicy": {
    object (JoinRestrictionPolicy)
  }
  // End of list of possible types for union field _join_restriction_policy.
}
字段
联合字段 privacy_policy。与此要求规范相关联的隐私权政策。每个数据源对象只能使用一种隐私保护方法。privacy_policy 只能是下列其中一项：
aggregationThresholdPolicy

object (AggregationThresholdPolicy)

可选。用于汇总阈值的政策。
differentialPrivacyPolicy

object (DifferentialPrivacyPolicy)

可选。用于差分隐私的政策。

联合字段 _join_restriction_policy。

_join_restriction_policy 只能是下列其中一项：
joinRestrictionPolicy

object (JoinRestrictionPolicy)

可选。联接限制政策不属于任何政策，因为此政策可以与其他政策一起设置。此政策使数据提供方能够在从受隐私保护的视图查询数据时，强制对“join_allowed_columns”执行联接。
JSON 表示法 
{
  "privacyUnitColumns": [
    string
  ],

  // Union field _threshold can be only one of the following:
  "threshold": string
  // End of list of possible types for union field _threshold.
}
字段
privacyUnitColumns[]

string

可选。与相应政策关联的隐私权单元列。目前，每个数据源对象（表、视图）只能有一个列作为隐私权单元列。在元数据中表示为重复字段，以便将来扩展到多个列。不允许重复和重复的结构体字段。对于嵌套字段，请使用点表示法（“outer.inner”）

联合字段 _threshold。

_threshold 只能是下列其中一项：
threshold

string (int64 format)

可选。“汇总阈值”政策的阈值。
JSON 表示法 
{

  // Union field _max_epsilon_per_query can be only one of the following:
  "maxEpsilonPerQuery": number
  // End of list of possible types for union field _max_epsilon_per_query.

  // Union field _delta_per_query can be only one of the following:
  "deltaPerQuery": number
  // End of list of possible types for union field _delta_per_query.

  // Union field _max_groups_contributed can be only one of the following:
  "maxGroupsContributed": string
  // End of list of possible types for union field _max_groups_contributed.

  // Union field _privacy_unit_column can be only one of the following:
  "privacyUnitColumn": string
  // End of list of possible types for union field _privacy_unit_column.

  // Union field _epsilon_budget can be only one of the following:
  "epsilonBudget": number
  // End of list of possible types for union field _epsilon_budget.

  // Union field _delta_budget can be only one of the following:
  "deltaBudget": number
  // End of list of possible types for union field _delta_budget.

  // Union field _epsilon_budget_remaining can be only one of the following:
  "epsilonBudgetRemaining": number
  // End of list of possible types for union field _epsilon_budget_remaining.

  // Union field _delta_budget_remaining can be only one of the following:
  "deltaBudgetRemaining": number
  // End of list of possible types for union field _delta_budget_remaining.
}
字段

联合字段 _max_epsilon_per_query。

_max_epsilon_per_query 只能是下列其中一项：
maxEpsilonPerQuery

number

可选。查询可消耗的最大 epsilon 值。如果订阅者在 SELECT 查询中将 epsilon 指定为参数，则该参数必须小于或等于此值。epsilon 参数用于控制添加到群组的噪声量，epsilon 值越大，噪声越少。

联合字段 _delta_per_query。

_delta_per_query 只能是下列其中一项：
deltaPerQuery

number

可选。每次查询所用的增量值。Delta 表示任何一行未能达到 epsilon 差分隐私的概率。表示在查询结果中公开汇总行所带来的风险。

联合字段 _max_groups_contributed。

_max_groups_contributed 只能是下列其中一项：
maxGroupsContributed

string (int64 format)

可选。每个查询使用的最大群组贡献值。表示每个受保护的实体可贡献到的群组数量上限。更改此值不会改善或损害隐私。准确率和实用性的最佳值取决于查询和数据。

联合字段 _privacy_unit_column。

_privacy_unit_column 只能是下列其中一项：
privacyUnitColumn

string

可选。与相应政策相关联的隐私权单元列。差分隐私权政策对于每个数据源对象（表、视图）只能有一个隐私权单元列。

联合字段 _epsilon_budget。

_epsilon_budget 只能是下列其中一项：
epsilonBudget

number

可选。针对受隐私保护的视图的所有查询的总 epsilon 预算。每个针对此视图的订阅者查询都会收取相应查询中请求的 epsilon 金额。如果预算充足，订阅者查询会尝试完成。但由于其他原因，付款仍可能失败，在这种情况下，系统会退还相应款项。如果预算不足，则查询会被拒绝。如果单个查询引用了多个视图，系统可能会多次尝试扣款。在这种情况下，必须有足够的预算来支付所有费用，否则系统会拒绝查询，并尽最大努力退还费用。该预算没有刷新政策，只能通过 ALTER VIEW 进行更新，或者通过创建可使用新预算进行查询的新视图来规避此限制。

联合字段 _delta_budget。

_delta_budget 只能是下列其中一项：
deltaBudget

number

可选。针对受隐私保护的视图的所有查询的总 delta 预算。针对此视图的每个订阅者查询都会收取贡献者通过隐私权政策 delta_per_query 字段预定义的增量金额。如果预算充足，订阅者查询会尝试完成。但由于其他原因，付款仍可能失败，在这种情况下，系统会退还相应款项。如果预算不足，则查询会被拒绝。如果单个查询引用了多个视图，系统可能会多次尝试扣款。在这种情况下，必须有足够的预算来支付所有费用，否则系统会拒绝查询，并尽最大努力退还费用。该预算没有刷新政策，只能通过 ALTER VIEW 进行更新，或者通过创建可使用新预算进行查询的新视图来规避此限制。

联合字段 _epsilon_budget_remaining。

_epsilon_budget_remaining 只能是下列其中一项：
epsilonBudgetRemaining

number

仅限输出。剩余的 epsilon 预算。如果预算用尽，则不允许再进行查询。请注意，对于正在进行的查询，系统会在执行查询之前扣除相应预算。如果查询失败或被取消，则会退还预算。在这种情况下，剩余预算金额可能会增加。

联合字段 _delta_budget_remaining。

_delta_budget_remaining 只能是下列其中一项：
deltaBudgetRemaining

number

仅限输出。剩余的增量预算。如果预算用尽，则不允许再进行查询。请注意，对于正在进行的查询，系统会在执行查询之前扣除相应预算。如果查询失败或被取消，则会退还预算。在这种情况下，剩余预算金额可能会增加。
JSON 表示法 
{
  "joinAllowedColumns": [
    string
  ],

  // Union field _join_condition can be only one of the following:
  "joinCondition": enum (JoinCondition)
  // End of list of possible types for union field _join_condition.
}
字段
joinAllowedColumns[]

string

可选。允许进行联接的唯一列。对于 join_conditions JOIN_ANY 和 JOIN_ALL，必须指定此字段；对于 JOIN_BLOCKED，则无法设置此字段。

联合字段 _join_condition。

_join_condition 只能是下列其中一项：
joinCondition

enum (JoinCondition)

可选。指定是否需要对视图的查询执行联接。默认值为 JOIN_CONDITION_UNSPECIFIED。
JSON 表示法 
{
  "query": string,
  "dialect": string
}
字段
query

string

必需。定义视图的查询。
dialect

string

可选。表示查询的方言。
JSON 表示法 
{
  "query": string,
  "lastRefreshTime": string,
  "enableRefresh": boolean,
  "refreshIntervalMs": string,
  "allowNonIncrementalDefinition": boolean
}
字段
query

string

必需。结果会持久保存的查询。
lastRefreshTime

string (int64 format)

仅限输出。上次刷新此物化视图的时间（以自纪元以来经历的毫秒数表示）。
enableRefresh

boolean

可选。在基表更新时启用具体化视图的自动刷新。默认值为“true”。
refreshIntervalMs

string (UInt64Value format)

可选。相应物化视图的刷新频率上限。默认值为“1800000”（30 分钟）。
allowNonIncrementalDefinition

boolean

可选。此选项用于声明打算构建不以增量方式刷新的具体化视图。非增量具体化视图支持扩展的 SQL 查询范围。创建具体化视图后，allow_non_incremental_definition 选项便无法更改。
JSON 表示法 
{
  "refreshWatermark": string,
  "lastRefreshStatus": {
    object (ErrorProto)
  }
}
字段
refreshWatermark

string (Timestamp format)

仅限输出。具体化视图的刷新水印。基表的数据收集到具体化视图缓存的时间点。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
lastRefreshStatus

object (ErrorProto)

仅限输出。上一次自动刷新的错误结果。如果存在，则表示上一次自动刷新失败。
JSON 表示法 
{
  "seconds": string,
  "nanos": integer
}
字段
seconds

string (int64 format)

表示世界协调时间 (UTC) 的秒数（从 Unix 时间 1970-01-01T00:00:00Z 开始算起）。必须介于 -62135596800 和 253402300799 之间（含边界值），对应于 0001-01-01T00:00:00Z 到 9999-12-31T23:59:59Z。
nanos

integer

秒数的非负小数部分（以纳秒为单位）。此字段是时长的纳秒部分，而不是秒的替代项。对于含小数部分的负秒数，仍必须包含按时间递升的非负纳秒值。必须介于 0 到 999,999,999 之间（含边界值）。
JSON 表示法 
{
  "reason": string,
  "location": string,
  "debugInfo": string,
  "message": string
}
字段
reason

string

简要的错误代码，用于总结错误。
location

string

指定发生错误的位置（如果有）。
debugInfo

string

调试信息。此属性是 Google 内部属性，不应使用。
message

string

人类可读的错误说明。
JSON 表示法 
{
  "sourceUris": [
    string
  ],
  "fileSetSpecType": enum (FileSetSpecType),
  "schema": {
    object (TableSchema)
  },
  "sourceFormat": string,
  "maxBadRecords": integer,
  "autodetect": boolean,
  "ignoreUnknownValues": boolean,
  "compression": string,
  "csvOptions": {
    object (CsvOptions)
  },
  "jsonOptions": {
    object (JsonOptions)
  },
  "bigtableOptions": {
    object (BigtableOptions)
  },
  "googleSheetsOptions": {
    object (GoogleSheetsOptions)
  },
  "maxBadRecordsAlternative": [
    integer
  ],
  "hivePartitioningOptions": {
    object (HivePartitioningOptions)
  },
  "connectionId": string,
  "decimalTargetTypes": [
    enum (DecimalTargetType)
  ],
  "avroOptions": {
    object (AvroOptions)
  },
  "jsonExtension": enum (JsonExtension),
  "parquetOptions": {
    object (ParquetOptions)
  },
  "referenceFileSchemaUri": string,
  "metadataCacheMode": enum (MetadataCacheMode),
  "timestampTargetPrecision": [
    integer
  ],

  // Union field _object_metadata can be only one of the following:
  "objectMetadata": enum (ObjectMetadata)
  // End of list of possible types for union field _object_metadata.

  // Union field _time_zone can be only one of the following:
  "timeZone": string
  // End of list of possible types for union field _time_zone.

  // Union field _date_format can be only one of the following:
  "dateFormat": string
  // End of list of possible types for union field _date_format.

  // Union field _datetime_format can be only one of the following:
  "datetimeFormat": string
  // End of list of possible types for union field _datetime_format.

  // Union field _time_format can be only one of the following:
  "timeFormat": string
  // End of list of possible types for union field _time_format.

  // Union field _timestamp_format can be only one of the following:
  "timestampFormat": string
  // End of list of possible types for union field _timestamp_format.
}
字段
sourceUris[]

string

[必需] 指向 Google Cloud 中数据的完全限定 URI。对于 Google Cloud Storage URI：每个 URI 都可以包含一个“*”通配符，此通配符必须位于“存储桶”名称之后。与加载作业相关的大小限制适用于外部数据源。对于 Google Cloud Bigtable URI：您只能指定一个 URI，并且此 URI 必须是 Google Cloud Bigtable 表的完整有效 HTTPS 网址。对于 Google Cloud Datastore 备份，您只能指定一个 URI。此外，不允许使用“*”通配符。
fileSetSpecType

enum (FileSetSpecType)

可选。指定如何解读源 URI 以构建要加载的文件集。默认情况下，系统会根据底层存储空间展开源 URI。其他选项包括指定清单文件。仅适用于对象存储系统。
schema

object (TableSchema)

可选。数据的架构。如果未开启自动检测，则 CSV 和 JSON 格式需要架构。Google Cloud Bigtable、Cloud Datastore 备份、Avro、ORC 和 Parquet 格式不允许使用架构。
sourceFormat

string

[必需] 数据格式。对于 CSV 文件，请指定“CSV”。对于 Google 表格，请指定“GOOGLE_SHEETS”。对于以换行符分隔的 JSON，请指定“NEWLINE_DELIMITED_JSON”。对于 Avro 文件，请指定“AVRO”。对于 Google Cloud Datastore 备份，请指定“DATASTORE_BACKUP”。对于 Apache Iceberg 表，请指定“ICEBERG”。对于 ORC 文件，请指定“ORC”。对于 Parquet 文件，请指定“PARQUET”。[Beta] 对于 Google Cloud Bigtable，请指定“BIGTABLE”。
maxBadRecords

integer

可选。BigQuery 在读取数据时可忽略的错误记录数上限。如果错误记录数超过此值，作业结果中将返回无效错误。默认值为 0，表示所有记录都必须有效。对于 Google Cloud Bigtable、Google Cloud Datastore 备份、Avro、ORC 和 Parquet 格式，系统会忽略此设置。
autodetect

boolean

尝试自动检测架构和格式选项。系统会遵循明确指定的任何选项。
ignoreUnknownValues

boolean

可选。表示 BigQuery 是否应允许表架构中不存在的额外值。如果值为 true，将忽略其他值。如果值为 false，则含有额外列的记录将被视为错误记录；如果错误记录太多，作业结果中将返回无效错误。默认值为 false。sourceFormat 属性决定了 BigQuery 将哪些项视为额外值： CSV：末尾列 JSON：与所有列名称均不匹配的指定值 Google Cloud Bigtable：系统会忽略此设置。 Google Cloud Datastore 备份：系统会忽略此设置。Avro：系统会忽略此设置。ORC：系统会忽略此设置。Parquet：系统会忽略此设置。
compression

string

可选。数据源的压缩类型。可能的值包括 GZIP 和 NONE。默认值为 NONE。对于 Google Cloud Bigtable、Google Cloud Datastore 备份、Avro、ORC 和 Parquet 格式，系统会忽略此设置。空字符串是无效值。
csvOptions

object (CsvOptions)

可选。如果 sourceFormat 设置为 CSV，则要设置的其他属性。
jsonOptions

object (JsonOptions)

可选。如果 sourceFormat 设置为 JSON，则要设置的其他属性。
bigtableOptions

object (BigtableOptions)

可选。如果 sourceFormat 设置为 BIGTABLE，则可使用其他选项。
googleSheetsOptions

object (GoogleSheetsOptions)

可选。如果 sourceFormat 设置为 GOOGLE_SHEETS，则可使用其他选项。
maxBadRecordsAlternative[]

integer

不应使用此字段。
hivePartitioningOptions

object (HivePartitioningOptions)

可选。设置后，配置 Hive 分区支持。并非所有存储格式都支持 Hive 分区，如果对不支持的格式请求 Hive 分区，或者提供无效的规范，都会导致错误。
connectionId

string

可选。用于指定读取外部存储空间（例如 Azure Blob、Cloud Storage 或 S3）时要使用的凭据的连接。connection_id 的格式可以是 {project_id}.{location_id};{connection_id} 或 projects/{project_id}/locations/{location_id}/connections/{connection_id}。
decimalTargetTypes[]

enum (DecimalTargetType)

定义源小数值可转换为的可能 SQL 数据类型的列表。此列表以及 decimal 字段的精度和比例参数决定了目标类型。按照 NUMERIC、BIGNUMERIC 和 STRING 的顺序，如果类型在指定的列表中并且支持精度和比例，则系统会选择该类型。STRING 支持所有精度和比例值。如果列出的类型均不支持精度和小数位数，系统会选择支持指定列表中最宽泛的范围的类型；如果在读取数据时值超出支持的范围，则会抛出错误。

示例：假设此字段的值为 ["NUMERIC", "BIGNUMERIC"]。如果（精度、标度）为：

  • (38,9) -> NUMERIC;
  • (39,9) -> BIGNUMERIC（NUMERIC 无法容纳 30 位整数）；
  • (38,10) -> BIGNUMERIC（NUMERIC 无法容纳 10 位小数）；
  • (76,38) -> BIGNUMERIC;
  • (77,38) -> BIGNUMERIC（如果值超出支持的范围，则会出错）。

此字段不能包含重复的类型。系统会忽略此字段中类型的顺序。例如，["BIGNUMERIC", "NUMERIC"] 与 ["NUMERIC", "BIGNUMERIC"] 相同，并且 NUMERIC 始终优先于 BIGNUMERIC。

对于 ORC，默认为 ["NUMERIC", "STRING"]；对于其他文件格式，默认为 ["NUMERIC"]。
avroOptions

object (AvroOptions)

可选。如果 sourceFormat 设置为 AVRO，则要设置的其他属性。
jsonExtension

enum (JsonExtension)

可选。与 source_format newline-delimited JSON 搭配使用的加载选项，用于指示正在加载 JSON 的变体。如需加载以换行符分隔的 GeoJSON 文件，请指定 GEOJSON（并且必须将 source_format 设置为 NEWLINE_DELIMITED_JSON）。
parquetOptions

object (ParquetOptions)

可选。如果 sourceFormat 设置为 PARQUET，则要设置的其他属性。
referenceFileSchemaUri

string

可选。创建外部表时，用户可以提供包含表架构的参考文件。系统会为以下格式启用此功能：AVRO、PARQUET、ORC。
metadataCacheMode

enum (MetadataCacheMode)

可选。表的元数据缓存模式。将此属性设置为启用来自外部数据源的元数据缓存。
timestampTargetPrecision[]

integer

在自动检测模式下，允许用于目标表的时间戳类型的秒的精度（以 10 为底的总位数上限）。

适用于以下格式：CSV。

对于 CSV 格式，可能的值包括：未指定、[] 或 [6]：所有自动检测到的 TIMESTAMP 列的时间戳(6) [6, 12]：所有自动检测到的 TIMESTAMP 列的时间戳(6)，这些列的亚秒数位数小于 6。对于所有自动检测到的具有 6 位以上亚秒级精度的 TIMESTAMP 列，将精度设置为 timestamp(12)。[12]：所有自动检测到的 TIMESTAMP 列的时间戳均为 12。

系统会忽略此数组中元素的顺序。如果输入的精度高于此数组中的最高目标精度，则会被截断。

联合字段 _object_metadata。

_object_metadata 只能是下列其中一项：
objectMetadata

enum (ObjectMetadata)

可选。ObjectMetadata 用于创建对象表。对象表包含在 source_uris 中找到的对象（及其元数据）的列表。如果设置了 ObjectMetadata，则应省略 source_format。

目前，SIMPLE 是唯一受支持的对象元数据类型。

联合字段 _time_zone。

_time_zone 只能是下列其中一项：
timeZone

string

可选。解析没有特定时区信息（例如 2024-04-20 12:34:56）的时间戳值时使用的时区。预期格式为 IANA 时区字符串（例如 America/Los_Angeles）。

联合字段 _date_format。

_date_format 只能是下列其中一项：
dateFormat

string

可选。用于解析 DATE 值的格式。支持 C 样式和 SQL 样式的值。

联合字段 _datetime_format。

_datetime_format 只能是下列其中一项：
datetimeFormat

string

可选。用于解析 DATETIME 值的格式。支持 C 样式和 SQL 样式的值。

联合字段 _time_format。

_time_format 只能是下列其中一项：
timeFormat

string

可选。用于解析 TIME 值的格式。支持 C 样式和 SQL 样式的值。

联合字段 _timestamp_format。

_timestamp_format 只能是下列其中一项：
timestampFormat

string

可选。用于解析 TIMESTAMP 值的格式。支持 C 样式和 SQL 样式的值。
JSON 表示法 
{
  "value": integer
}
字段
value

integer

int32 值。
JSON 表示法 
{
  "fieldDelimiter": string,
  "skipLeadingRows": string,
  "quote": string,
  "allowQuotedNewlines": boolean,
  "allowJaggedRows": boolean,
  "encoding": string,
  "preserveAsciiControlCharacters": boolean,
  "nullMarker": string,
  "nullMarkers": [
    string
  ],
  "sourceColumnMatch": string
}
字段
fieldDelimiter

string

可选。CSV 文件中的字段分隔符。分隔符会被解读为单个字节。对于以 ISO-8859-1 编码的文件，任何单个字符都可以用作分隔符。对于采用 UTF-8 编码的文件，可以使用十进制范围 1-127 (U+0001-U+007F) 中的字符，无需进行任何修改。以多个字节编码的 UTF-8 字符（即 U+0080 及以上）将仅使用第一个字节来分隔字段。剩余字节将视为字段的一部分。BigQuery 也支持使用转义序列“\t”(U+0009) 来指定制表符分隔符。默认值为英文逗号（“,”，U+002C）。
skipLeadingRows

string (Int64Value format)

可选。BigQuery 在读取数据时将跳过的 CSV 文件顶部行数。默认值为 0。 如果文件中有应跳过的标题行，此属性会很有用。开启自动检测功能后，系统会执行以下操作：

  • 未指定 skipLeadingRows - 自动检测会尝试检测第一行中的标题。如果未检测到，则将相应行读取为数据。否则，系统会从第二行开始读取数据。
  • skipLeadingRows 为 0 - 指示自动检测功能没有标题，应从第一行开始读取数据。
  • skipLeadingRows = N > 0 - 自动检测会跳过 N-1 行，并尝试检测第 N 行中的标题。如果未检测到标题，系统只会跳过第 N 行。否则，系统会使用第 N 行提取检测到的架构的列名。
quote

string

可选。用于括起 CSV 文件中数据部分的值。BigQuery 会将字符串转换为 ISO-8859-1 编码格式，并使用编码字符串的第一个字节来拆分原始二进制状态的数据。默认值为英文双引号 (")。如果您的数据不包含括起部分，则将属性值设置为空字符串。如果您的数据包含括起的换行符，则还必须将 allowQuotedNewlines 属性设置为 true。如需在引用值中包含特定引号字符，请在前面加上一个匹配的引号字符。例如，如果您要转义默认字符“ " ”，请使用“ "" ”。
allowQuotedNewlines

boolean

可选。指示 BigQuery 是否应允许 CSV 文件中引号括起来的数据部分包含换行符。默认值为 false。
allowJaggedRows

boolean

可选。表示 BigQuery 是否应接受末尾处缺少可选列的行。如果为 true，BigQuery 会将缺少的尾随列视为 null 值。如果值为 false，则末尾处缺失列的记录将被视为错误记录；如果错误记录太多，作业结果中将返回一个无效记录错误。默认值为 false。
encoding

string

可选。数据的字符编码。支持的值包括 UTF-8、ISO-8859-1、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。默认值为 UTF-8 格式。使用 quote 和 fieldDelimiter 属性的值拆分原始二进制数据后，BigQuery 会对数据进行解码。
preserveAsciiControlCharacters

boolean

可选。表示是否保留嵌入的 ASCII 控制字符（ASCII 表中的前 32 个字符，从“\x00”到“\x1F”）。
nullMarker

string

可选。指定表示 CSV 文件中 null 值的字符串。例如，如果指定“\N”，BigQuery 将在查询 CSV 文件时将“\N”解读为 null 值。默认值为空字符串。如果将此属性设置为自定义值，那么在除 STRING 和 BYTE 之外的任意数据类型出现空字符串的情况下，BigQuery 将抛出一个错误。对于 STRING 和 BYTE 列，BigQuery 会将空字符串解读为空值。
nullMarkers[]

string

可选。CSV 文件中表示为 SQL NULL 值的字符串列表。

null_marker 和 null_markers 不能同时设置。如果设置了 null_marker，则不得设置 null_markers。如果设置了 null_markers，则不得设置 null_marker。如果同时设置了 null_marker 和 null_markers，系统会抛出用户错误。null_markers 中列出的任何字符串（包括空字符串）都将被解读为 SQL NULL。这适用于所有列类型。
sourceColumnMatch

string

可选。控制用于将加载的列与架构匹配的策略。如果未设置，则系统会根据架构的提供方式选择合理的默认值。如果使用自动检测，则按名称匹配列。否则，系统会按位置匹配列。这样做是为了保持行为的向后兼容性。可接受的值包括：POSITION - 按位置匹配。此选项假定列的顺序与架构相同。NAME - 按名称匹配。此选项会将标题行读取为列名称，并对列进行重新排序以匹配架构中的字段名称。
JSON 表示法 
{
  "encoding": string
}
字段
encoding

string

可选。数据的字符编码。支持的值包括 UTF-8、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。默认值为 UTF-8 格式。
JSON 表示法 
{
  "columnFamilies": [
    {
      object (BigtableColumnFamily)
    }
  ],
  "ignoreUnspecifiedColumnFamilies": boolean,
  "readRowkeyAsString": boolean,
  "outputColumnFamiliesAsJson": boolean
}
字段
columnFamilies[]

object (BigtableColumnFamily)

可选。要在表架构中公开的列族及其类型的列表。此列表限制可以在查询中引用的列族，并指定其值类型。您可以使用此列表执行类型转换 - 如需了解详情，请参阅“类型”字段。如果将此列表留空，则所有列族都会加入表架构中，并且列族的值会被读取为 BYTES。在查询期间，系统只会从 Bigtable 读取相应查询中引用的列族。
ignoreUnspecifiedColumnFamilies

boolean

可选。如果该字段为 true，则未在 columnFamilies 列表中指定的列族不会在表架构中公开。否则，系统会使用 BYTES 类型值读取这些内容。默认值为 false。
readRowkeyAsString

boolean

可选。如果该字段为 true，则系统会读取 rowkey 列族，并将其转换为字符串。否则，系统会使用 BYTES 类型值读取这些内容，用户需要使用 CAST 手动转换这些值（如有必要）。默认值为 false。
outputColumnFamiliesAsJson

boolean

可选。如果该字段为 true，则每个列族都将作为单个 JSON 列进行读取。否则，系统会将其读取为包含时间戳/值元组的重复单元结构。默认值为 false。
JSON 表示法 
{
  "familyId": string,
  "type": string,
  "encoding": string,
  "columns": [
    {
      object (BigtableColumn)
    }
  ],
  "onlyReadLatest": boolean,
  "protoConfig": {
    object (BigtableProtoConfig)
  }
}
字段
familyId

string

列族的标识符。
type

string

可选。要转换相应列族中单元格的值的类型。如果使用 BINARY 编码值，则预期这些值会使用 HBase Bytes.toBytes 函数进行编码。允许使用以下 BigQuery 类型（区分大小写）：

  • BYTES
  • STRING
  • INTEGER
  • FLOAT
  • BOOLEAN
  • JSON

默认类型为 BYTES。您可以在“columns”中列出特定列并为其指定类型，以覆盖此设置。
encoding

string

可选。当类型不是 STRING 时，值的编码。可接受的编码值包括：TEXT - 表示值是字母数字文本字符串。BINARY - 表示值是使用 HBase Bytes.toBytes 系列函数进行编码的。PROTO_BINARY - 表示值是使用序列化 proto 消息进行编码的。此函数只能与 JSON 类型结合使用。您可以在“columns”中列出特定列并为其指定编码，以覆盖此设置。
columns[]

object (BigtableColumn)

可选。应作为单独字段（而非 [列名称, 值] 对的列表）公开的列的列表。限定符与此列表中的限定符匹配的所有列都可以作为 <family field name>.<column field name> 进行访问。其他列可以通过 <family field name>.Column 字段作为列表进行访问。
onlyReadLatest

boolean

可选。如果设置了此属性，则仅公开相应列族中所有列的最新版本的值。您可以在“columns”中列出特定列并为其指定其他设置，以覆盖此设置。
protoConfig

object (BigtableProtoConfig)

可选。特定于 Protobuf 的配置，仅在编码为 PROTO_BINARY 时生效。
JSON 表示法 
{
  "qualifierEncoded": string,
  "qualifierString": string,
  "fieldName": string,
  "type": string,
  "encoding": string,
  "onlyReadLatest": boolean,
  "protoConfig": {
    object (BigtableProtoConfig)
  }
}
字段
qualifierEncoded

string (BytesValue format)

[必需] 列的限定符。具有此确切限定符的父列族中的列会作为 <family field name>.<column field name> 字段公开。如果限定符是有效的 UTF-8 字符串，则可以在 qualifier_string 字段中指定。否则，必须将 base-64 编码的值设置为 qualifier_encoded。列字段名称与列限定符相同。不过，如果限定符不是有效的 BigQuery 字段标识符（即不符合 [a-zA-Z][a-zA-Z0-9_]*），则必须以 field_name 形式提供有效的标识符。
qualifierString

string

限定符字符串。
fieldName

string

可选。如果限定符不是有效的 BigQuery 字段标识符（即不符合 [a-zA-Z][a-zA-Z0-9_]*），则必须提供有效的标识符作为列字段名称，并在查询中用作字段名称。
type

string

可选。要转换此列中单元格的值的类型。如果使用 BINARY 编码值，则预期这些值会使用 HBase Bytes.toBytes 函数进行编码。允许使用以下 BigQuery 类型（区分大小写）：

  • BYTES
  • STRING
  • INTEGER
  • FLOAT
  • BOOLEAN
  • JSON

默认类型为 BYTES。还可以在列族级别设置“type”。不过，如果同时在两个级别设置了“type”，则此级别的设置具有优先权。
encoding

string

可选。当类型不是 STRING 时，值的编码。可接受的编码值包括：TEXT - 表示值是字母数字文本字符串。BINARY - 表示值是使用 HBase Bytes.toBytes 系列函数进行编码的。PROTO_BINARY - 表示值是使用序列化 proto 消息进行编码的。此函数只能与 JSON 类型结合使用。您也可以在列族级设置“encoding”。不过，如果同时在两个级别设置了“编码”，则此级别的设置具有优先权。
onlyReadLatest

boolean

可选。如果设置了此属性，则仅公开此列中的最新版本的值。还可以在列族级别设置“onlyReadLatest”。不过，如果这两个级别都设置了“onlyReadLatest”，则此级别的设置具有优先权。
protoConfig

object (BigtableProtoConfig)

可选。特定于 Protobuf 的配置，仅在编码为 PROTO_BINARY 时生效。
JSON 表示法 
{
  "value": string
}
字段
value

string (bytes format)

字节值。

使用 base64 编码的字符串。
JSON 表示法 
{
  "schemaBundleId": string,
  "protoMessageName": string
}
字段
schemaBundleId

string

可选。与相应 protobuf 关联的 Bigtable SchemaBundle 资源的 ID。该 ID 应在父表中引用，例如：foo，而不是 projects/{project}/instances/{instance}/tables/{table}/schemaBundles/foo。如需详细了解 Bigtable SchemaBundle，请参阅相关文档。
protoMessageName

string

可选。相应 protobuf 的完全限定 proto 消息名称。格式为“foo.bar.Message”。
JSON 表示法 
{
  "skipLeadingRows": string,
  "range": string
}
字段
skipLeadingRows

string (Int64Value format)

可选。BigQuery 在读取数据时将跳过的表单顶部行数。默认值为 0。 如果您有应跳过的标题行，此属性会非常有用。如果自动检测处于开启状态，则行为如下：* 未指定 skipLeadingRows - 自动检测会尝试检测第一行中的标题。如果未检测到，则将相应行读取为数据。否则，系统会从第二行开始读取数据。* skipLeadingRows 为 0 - 指示自动检测功能没有标题，应从第一行开始读取数据。* skipLeadingRows = N > 0 - 自动检测会跳过前 N-1 行，并尝试检测第 N 行中的标题。如果未检测到标题，系统只会跳过第 N 行。否则，系统会使用第 N 行提取检测到的架构的列名。
range

string

可选。要查询的工作表的范围。仅在非空时使用。典型格式：sheet_name!top_left_cell_id:bottom_right_cell_id 例如：sheet1!A1:B20
JSON 表示法 
{
  "mode": string,
  "sourceUriPrefix": string,
  "requirePartitionFilter": boolean,
  "fields": [
    string
  ]
}
字段
mode

string

可选。设置后，读取数据时要使用的 Hive 分区模式。支持以下模式：

  • AUTO：自动推断分区键名称和类型。

  • STRINGS：自动推断分区键名称。所有类型均为字符串。

  • CUSTOM：您可以将分区键架构编码到源 URI 前缀中。

并非所有存储格式都支持 Hive 分区。如果对不受支持的格式请求 Hive 分区，则会导致错误。目前支持的格式包括：JSON、CSV、ORC、Avro 和 Parquet。
sourceUriPrefix

string

可选。当请求 Hive 分区检测时，必须要求所有源 URI 具有共同的前缀。前缀必须在分区键编码开始之前立即结束。例如，假设文件遵循以下数据布局：

gs://bucket/path_to_table/dt=2019-06-01/country=USA/id=7/file.avro

gs://bucket/path_to_table/dt=2019-05-31/country=CA/id=3/file.avro

当请求使用 AUTO 或 STRINGS 检测进行 Hive 分区时，常见前缀可以是 gs://bucket/path_to_table 或 gs://bucket/path_to_table/。

CUSTOM 检测模式需要将分区架构编码在通用前缀之后。对于 CUSTOM，以下任何一项：

  • gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:INTEGER}

  • gs://bucket/path_to_table/{dt:STRING}/{country:STRING}/{id:INTEGER}

  • gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:STRING}

都将是有效的来源 URI 前缀。
requirePartitionFilter

boolean

可选。如果设置为 true，则对此表进行的所有查询都需要指定可用于执行分区消除的分区过滤条件。

请注意，仅在创建永久外部表或查询临时外部表时，此字段才应为 true。

如果将 require_partition_filter 明确设置为 true，则 Hive 分区加载会失败。
fields[]

string

仅限输出。对于永久外部表，此字段会填充推断出的 Hive 分区键，并按推断顺序排列。您可以通过检查表架构（其中将包含分区键）来推断分区键的类型。并非每个 API 都会在输出中填充此字段。例如，Tables.Get 会填充此字段，但 Tables.List 不会包含此字段。
JSON 表示法 
{
  "useAvroLogicalTypes": boolean
}
字段
useAvroLogicalTypes

boolean

可选。如果 sourceFormat 设置为“AVRO”，此标志表示是否将逻辑类型解释为相应的 BigQuery 数据类型（例如 TIMESTAMP），而不是使用原始类型（例如 INTEGER）。
JSON 表示法 
{
  "enumAsString": boolean,
  "enableListInference": boolean,
  "mapTargetType": enum (MapTargetType)
}
字段
enumAsString

boolean

可选。指示是否默认将 Parquet ENUM 逻辑类型推断为 STRING 而不是 BYTES。
enableListInference

boolean

可选。指示是否专门为 Parquet LIST 逻辑类型使用架构推断。
mapTargetType

enum (MapTargetType)

可选。指示如何表示 Parquet 映射（如果存在）。
JSON 表示法 
{
  "connectionId": string,
  "storageUri": string,
  "fileFormat": enum (FileFormat),
  "tableFormat": enum (TableFormat)
}
字段
connectionId

string

可选。用于指定凭据的连接，这些凭据将用于读取和写入外部存储空间（例如 Cloud Storage）。connection_id 可以采用 {project}.{location}.{connection_id} 或“projects/{project}/locations/{location}/connections/{connection_id}”格式。
storageUri

string

可选。存储表数据的外部文件夹的完全限定位置前缀。不允许使用“*”通配符。URI 应采用 gs://bucket/path_to_table/ 格式
fileFormat

enum (FileFormat)

可选。表格数据存储的文件格式。
tableFormat

enum (TableFormat)

可选。仅存储元数据的快照所采用的表格式。
JSON 表示法 
{
  "estimatedBytes": string,
  "estimatedRows": string,
  "oldestEntryTime": string
}
字段
estimatedBytes

string

仅限输出。流式传输缓冲区中当前字节数的下限估计值。
estimatedRows

string

仅限输出。流式缓冲区的当前行数的下限估计值。
oldestEntryTime

string (uint64 format)

仅限输出。如果流式缓冲区可用，则包含流式缓冲区中最旧条目的时间戳（以自纪元以来的毫秒数表示）。
JSON 表示法 
{
  "kmsKeyName": string
}
字段
kmsKeyName

string

可选。描述将用于保护目标 BigQuery 表的 Cloud KMS 加密密钥。与您的项目关联的 BigQuery 服务账号需要具有对相应加密密钥的访问权限。
JSON 表示法 
{
  "baseTableReference": {
    object (TableReference)
  },
  "snapshotTime": string
}
字段
baseTableReference

object (TableReference)

必需。用于描述已拍摄快照的表的 ID 的参考。
snapshotTime

string (Timestamp format)

必需。基表被拍摄快照的时间。此值以 RFC3339 格式在 JSON 响应中报告。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
JSON 表示法 
{
  "baseTableReference": {
    object (TableReference)
  },
  "cloneTime": string
}
字段
baseTableReference

object (TableReference)

必需。用于描述克隆的表的 ID 的参考。
cloneTime

string (Timestamp format)

必需。克隆基表的时间。此值以 RFC3339 格式在 JSON 响应中报告。

采用 RFC 3339 标准，生成的输出将始终进行 Z 规范化（即转换为 UTC 零时区格式并在末尾附加 Z），并使用 0、3、6 或 9 个小数位。不带“Z”的偏差时间也是可以接受的。示例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
JSON 表示法 
{
  "type": enum (RestrictionType)
}
字段
type

enum (RestrictionType)

仅限输出。指定数据集/表限制的类型。
JSON 表示法 
{
  "primaryKey": {
    object (PrimaryKey)
  },
  "foreignKeys": [
    {
      object (ForeignKey)
    }
  ]
}
字段
primaryKey

object (PrimaryKey)

可选。表示表列的主键限制条件。仅当表具有主键时才显示。系统不会强制执行主键。
foreignKeys[]

object (ForeignKey)

可选。仅当表具有外键时才显示。外键未强制执行。
JSON 表示法 
{
  "columns": [
    string
  ]
}
字段
columns[]

string

必需。构成主键限制条件的列。
JSON 表示法 
{
  "name": string,
  "referencedTable": {
    object (TableReference)
  },
  "columnReferences": [
    {
      object (ColumnReference)
    }
  ]
}
字段
name

string

可选。仅当外键限制条件已命名时才设置。
referencedTable

object (TableReference)

必需。包含主键且被相应外键引用的表。
columnReferences[]

object (ColumnReference)

必需。构成外键的列。
JSON 表示法 
{
  "referencingColumn": string,
  "referencedColumn": string
}
字段
referencingColumn

string

必需。构成外键的列。
referencedColumn

string

必需。主键中被 referencing_column 引用的列。
JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string
JSON 表示法 
{
  "sourceTable": {
    object (TableReference)
  },
  "replicationIntervalMs": string,
  "replicatedSourceLastRefreshTime": string,
  "replicationStatus": enum (ReplicationStatus),
  "replicationError": {
    object (ErrorProto)
  }
}
字段
sourceTable

object (TableReference)

必需。复制的源表引用。
replicationIntervalMs

string (int64 format)

可选。指定轮询源表以获取更新的间隔。此步骤为可选步骤。如果未指定，系统将应用默认复制间隔。
replicatedSourceLastRefreshTime

string (int64 format)

可选。仅限输出。如果来源是具体化视图，此字段表示来源的上次刷新时间。
replicationStatus

enum (ReplicationStatus)

可选。仅限输出。已配置复制的复制状态。
replicationError

object (ErrorProto)

可选。仅限输出。将永久停止表复制的复制错误。
JSON 表示法 
{
  "parameters": {
    string: string,
    ...
  },
  "storageDescriptor": {
    object (StorageDescriptor)
  },
  "connectionId": string
}
字段
parameters

map (key: string, value: string)

可选。一个键值对映射，用于定义开源表的参数和属性。与 Hive Metastore 表参数相对应。大小上限为 4 MiB。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
storageDescriptor

object (StorageDescriptor)

可选。一个存储描述符，包含有关相应表的物理存储的信息。
connectionId

string

可选。一个连接 ID，用于指定读取外部存储空间（例如 Azure Blob、Cloud Storage 或 Amazon S3）时要使用的凭据。需要此连接才能从 BigQuery 读取开源表。connection_id 格式必须为 <project_id>.<location_id>.<connection_id> 或 projects/<project_id>/locations/<location_id>/connections/<connection_id>。
JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string
JSON 表示法 
{
  "locationUri": string,
  "inputFormat": string,
  "outputFormat": string,
  "serdeInfo": {
    object (SerDeInfo)
  }
}
字段
locationUri

string

可选。表的实际位置（例如 gs://spark-dataproc-data/pangea-data/case_sensitive/ 或 gs://spark-dataproc-data/pangea-data/*）。长度上限为 2056 个字节。
inputFormat

string

可选。指定 InputFormat 的完全限定类名称（例如“org.apache.hadoop.hive.ql.io.orc.OrcInputFormat”）。长度上限为 128 个字符。
outputFormat

string

可选。指定 OutputFormat 的完全限定类名（例如“org.apache.hadoop.hive.ql.io.orc.OrcOutputFormat”）。长度上限为 128 个字符。
serdeInfo

object (SerDeInfo)

可选。序列化程序和反序列化程序信息。
JSON 表示法 
{
  "name": string,
  "serializationLibrary": string,
  "parameters": {
    string: string,
    ...
  }
}
字段
name

string

可选。SerDe 的名称。长度上限为 256 个字符。
serializationLibrary

string

必需。指定负责在表格表示形式与底层低级输入和输出格式结构之间转换数据的序列化库的完全限定类名。长度上限为 256 个字符。
parameters

map (key: string, value: string)

可选。用于定义序列化库的初始化参数的键值对。大小上限为 10 Kib。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。
JSON 表示法 
{
  "key": string,
  "value": string
}
字段
key

string
value

string

工具注释

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：❌