Class Table (3.39.0)
- 3.39.0 (latest)
- 3.38.0
- 3.37.0
- 3.36.0
- 3.35.1
- 3.34.0
- 3.33.0
- 3.31.0
- 3.30.0
- 3.29.0
- 3.27.0
- 3.26.0
- 3.25.0
- 3.24.0
- 3.23.1
- 3.22.0
- 3.21.0
- 3.20.1
- 3.19.0
- 3.18.0
- 3.17.2
- 3.16.0
- 3.15.0
- 3.14.1
- 3.13.0
- 3.12.0
- 3.11.4
- 3.4.0
- 3.3.6
- 3.2.0
- 3.1.0
- 3.0.1
- 2.34.4
- 2.33.0
- 2.32.0
- 2.31.0
- 2.30.1
- 2.29.0
- 2.28.1
- 2.27.1
- 2.26.0
- 2.25.2
- 2.24.1
- 2.23.3
- 2.22.1
- 2.21.0
- 2.20.0
- 2.19.0
- 2.18.0
- 2.17.0
- 2.16.1
- 2.15.0
- 2.14.0
- 2.13.1
- 2.12.0
- 2.11.0
- 2.10.0
- 2.9.0
- 2.8.0
- 2.7.0
- 2.6.2
- 2.5.0
- 2.4.0
- 2.3.1
- 2.2.0
- 2.1.0
- 2.0.0
- 1.28.2
- 1.27.2
- 1.26.1
- 1.25.0
- 1.24.0
- 1.23.1
- 1.22.0
- 1.21.0
- 1.20.0
- 1.19.0
- 1.18.0
- 1.17.0
- 1.16.0
Table(table_ref,schema=None)Tables represent a set of rows whose values correspond to a schema.
Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/tables#resource-table
Parameters | |
|---|---|
| Name | Description |
table_ref | Union[google.cloud.bigquery.table.TableReference, str]A pointer to a table. If |
schema | Optional[Sequence[Union[SchemaField, Mapping[str, Any] ]]]The table's schema. If any item is a mapping, its content must be compatible withfrom_api_repr. |
Properties
biglake_configuration
google.cloud.bigquery.table.BigLakeConfiguration: Configurationfor managed tables for Apache Iceberg.
Seehttps://cloud.google.com/bigquery/docs/iceberg-tables for more information.
clone_definition
Information about the clone. This value is set via clone creation.
See:https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#Table.FIELDS.clone_definition
clustering_fields
Union[List[str], None]: Fields defining clustering for the table
(Defaults to :data:None).
Clustering fields are immutable after table creation.
Note:BigQuery supports clustering for both partitioned andnon-partitioned tables.created
Union[datetime.datetime, None]: Datetime at which the table wascreated (:data:None until set from the server).
description
Union[str, None]: Description of the table (defaults to:data:None).
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
encryption_configuration
google.cloud.bigquery.encryption_configuration.EncryptionConfiguration: Customencryption configuration for the table.
Custom encryption configuration (e.g., Cloud KMS keys) or :data:Noneif using default encryption.
Seeprotecting data with Cloud KMS keys<https://cloud.google.com/bigquery/docs/customer-managed-encryption>;_in the BigQuery documentation.
etag
Union[str, None]: ETag for the table resource (:data:None untilset from the server).
expires
Union[datetime.datetime, None]: Datetime at which the table will bedeleted.
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
external_catalog_table_options
Options defining open source compatible datasets living in theBigQuery catalog. Contains metadata of open source database, schemaor namespace represented by the current dataset.
external_data_configuration
Union[google.cloud.bigquery.ExternalConfig, None]: Configuration foran external data source (defaults to :data:None).
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
foreign_type_info
Optional. Specifies metadata of the foreign data type definition infield schema (TableFieldSchema.foreign_type_definition).
| Returns | |
|---|---|
| Type | Description |
Optional[schema.ForeignTypeInfo] .. Note:: foreign_type_info is only required if you are referencing an external catalog such as a Hive table. For details, see: https://cloud.google.com/bigquery/docs/external-tables https://cloud.google.com/bigquery/docs/datasets-intro#external_datasets | Foreign type information, or :data:None if not set. |
friendly_name
Union[str, None]: Title of the table (defaults to :data:None).
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
full_table_id
Union[str, None]: ID for the table (:data:None until set from theserver).
In the formatproject-id:dataset_id.table_id.
labels
Dict[str, str]: Labels for the table.
This method always returns a dict. To change a table's labels,modify the dict, then callClient.update_table. To delete alabel, set its value to :data:None before updating.
| Exceptions | |
|---|---|
| Type | Description |
ValueError | Ifvalue type is invalid. |
location
Union[str, None]: Location in which the table is hosted
Defaults to :data:None.
max_staleness
Union[str, None]: The maximum staleness of data that could be returned when the table is queried.
Staleness encoded as a string encoding of sql IntervalValue type.This property is optional and defaults to None.
According to the BigQuery API documentation, maxStaleness specifies the maximum timeinterval for which stale data can be returned when querying the table.It helps control data freshness in scenarios like metadata-cached external tables.
| Returns | |
|---|---|
| Type | Description |
Optional[str] | A string representing the maximum staleness interval (e.g., '1h', '30m', '15s' for hours, minutes, seconds respectively). |
modified
Union[datetime.datetime, None]: Datetime at which the table was lastmodified (:data:None until set from the server).
mview_allow_non_incremental_definition
Optional[bool]: This option declares the intention to construct amaterialized view that isn't refreshed incrementally.The default value is :data:False.
mview_enable_refresh
Optional[bool]: Enable automatic refresh of the materialized viewwhen the base table is updated. The default value is :data:True.
mview_last_refresh_time
Optional[datetime.datetime]: Datetime at which the materialized view was lastrefreshed (:data:None until set from the server).
mview_query
Optional[str]: SQL query defining the table as a materializedview (defaults to :data:None).
mview_refresh_interval
Optional[datetime.timedelta]: The maximum frequency at which thismaterialized view will be refreshed. The default value is 1800000milliseconds (30 minutes).
num_bytes
Union[int, None]: The size of the table in bytes (:data:None untilset from the server).
num_rows
Union[int, None]: The number of rows in the table (:data:Noneuntil set from the server).
partition_expiration
Union[int, None]: Expiration time in milliseconds for a partition.
Ifpartition_expiration is set andtype_ isnot set,type_ will default toDAY.
partitioning_type
Union[str, None]: Time partitioning of the table if it ispartitioned (Defaults to :data:None).
range_partitioning
Optional[google.cloud.bigquery.table.RangePartitioning]:Configures range-based partitioning for a table.
Note:Beta. The integer range partitioning feature is in apre-release state and might change or have limited support.Only specify at most one ofxref_time_partitioning orxref_range_partitioning.| Exceptions | |
|---|---|
| Type | Description |
ValueError | If the value is notRangePartitioning or :data:None. |
reference
A xref_TableReference pointing tothis table.
| Returns | |
|---|---|
| Type | Description |
google.cloud.bigquery.table.TableReference | pointer to this table. |
require_partition_filter
bool: If set to true, queries over the partitioned table require apartition filter that can be used for partition elimination to bespecified.
resource_tags
Dict[str, str]: Resource tags for the table.
See:https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#Table.FIELDS.resource_tags
schema
Sequence[Union[ xref_SchemaField, Mapping[str, Any] ]]: Table's schema.
| Exceptions | |
|---|---|
| Type | Description |
Exception | Ifschema is not a sequence, or if any item in the sequence is not aSchemaField instance or a compatible mapping representation of the field. .. Note:: If you are referencing a schema for an external catalog table such as a Hive table, it will also be necessary to populate the foreign_type_info attribute. This is not necessary if defining the schema for a BigQuery table. For details, see: https://cloud.google.com/bigquery/docs/external-tables https://cloud.google.com/bigquery/docs/datasets-intro#external_datasets |
self_link
Union[str, None]: URL for the table resource (:data:None until setfrom the server).
snapshot_definition
Information about the snapshot. This value is set via snapshot creation.
See:https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#Table.FIELDS.snapshot_definition
streaming_buffer
google.cloud.bigquery.StreamingBuffer: Information about a table'sstreaming buffer.
table_constraints
Tables Primary Key and Foreign Key information.
table_type
Union[str, None]: The type of the table (:data:None until set fromthe server).
Possible values are'TABLE','VIEW','MATERIALIZED_VIEW' or'EXTERNAL'.
time_partitioning
Optional[google.cloud.bigquery.table.TimePartitioning]: Configures time-basedpartitioning for a table.
Only specify at most one ofxref_time_partitioning orxref_range_partitioning.
| Exceptions | |
|---|---|
| Type | Description |
ValueError | If the value is notTimePartitioning or :data:None. |
view_query
Union[str, None]: SQL query defining the table as a view (defaultsto :data:None).
By default, the query is treated as Standard SQL. To use LegacySQL, setview_use_legacy_sql to :data:True.
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
view_use_legacy_sql
bool: Specifies whether to execute the view with Legacy or Standard SQL.
This boolean specifies whether to execute the view with Legacy SQL(:data:True) or Standard SQL (:data:False). The client side default is:data:False. The server-side default is :data:True. If this table isnot a view, :data:None is returned.
| Exceptions | |
|---|---|
| Type | Description |
ValueError | For invalid value types. |
Methods
from_api_repr
from_api_repr(resource:dict)->google.cloud.bigquery.table.TableFactory: construct a table given its API representation
| Parameter | |
|---|---|
| Name | Description |
resource | Dict[str, object]Table resource representation from the API |
| Exceptions | |
|---|---|
| Type | Description |
KeyError | If theresource lacks the key'tableReference', or if thedict stored within the key'tableReference' lacks the keys'tableId','projectId', or'datasetId'. |
| Returns | |
|---|---|
| Type | Description |
google.cloud.bigquery.table.Table | Table parsed fromresource. |
from_string
from_string(full_table_id:str)->google.cloud.bigquery.table.TableConstruct a table from fully-qualified table ID.
| Parameter | |
|---|---|
| Name | Description |
full_table_id | strA fully-qualified table ID in standard SQL format. Must included a project ID, dataset ID, and table ID, each separated by |
| Exceptions | |
|---|---|
| Type | Description |
ValueError | Iffull_table_id is not a fully-qualified table ID in standard SQL format. |
| Returns | |
|---|---|
| Type | Description |
Table .. rubric:: Examples >>> Table.from_string('my-project.mydataset.mytable') Table(TableRef...(D...('my-project', 'mydataset'), 'mytable')) | Table parsed fromfull_table_id. |
to_api_repr
to_api_repr()->dictConstructs the API resource of this table
| Returns | |
|---|---|
| Type | Description |
Dict[str, object] | Table represented as an API resource |
to_bqstorage
to_bqstorage()->strConstruct a BigQuery Storage API representation of this table.
| Returns | |
|---|---|
| Type | Description |
str | A reference to this table in the BigQuery Storage API. |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-16 UTC.