As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

google.cloud.bigquery.table.Table

class google.cloud.bigquery.table.Table(table_ref, schema=None)

Tables represent a set of rows whose values correspond to a schema.

See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables#resource-table

Parameters

• table_ref (Union[google.cloud.bigquery.table.TableReference, str]) – A pointer to a table. If table_ref is a string, it must included a project ID, dataset ID, and table ID, each separated by ..

• schema (Optional[Sequence[Union[ SchemaField, Mapping[str, Any] ]]]) – The table’s schema. If any item is a mapping, its content must be compatible with from_api_repr().

__init__(table_ref, schema=None) → None

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(table_ref[, schema])	Initialize self.
from_api_repr(resource)	Factory: construct a table given its API representation
from_string(full_table_id)	Construct a table from fully-qualified table ID.
to_api_repr()	Constructs the API resource of this table
to_bqstorage()	Construct a BigQuery Storage API representation of this table.

Attributes

clone_definition	Information about the clone.
clustering_fields	Fields defining clustering for the table
created	Datetime at which the table was created (None until set from the server).
dataset_id	ID of dataset containing the table.
description	Description of the table (defaults to None).
encryption_configuration	Custom encryption configuration for the table.
etag	ETag for the table resource (None until set from the server).
expires	Datetime at which the table will be deleted.
external_data_configuration	Configuration for an external data source (defaults to None).
friendly_name	Title of the table (defaults to None).
full_table_id	ID for the table (None until set from the server).
labels	Labels for the table.
location	Location in which the table is hosted
modified	Datetime at which the table was last modified (None until set from the server).
mview_enable_refresh	Enable automatic refresh of the materialized view when the base table is updated.
mview_last_refresh_time	Datetime at which the materialized view was last refreshed (None until set from the server).
mview_query	SQL query defining the table as a materialized view (defaults to None).
mview_refresh_interval	The maximum frequency at which this materialized view will be refreshed.
num_bytes	The size of the table in bytes (None until set from the server).
num_rows	The number of rows in the table (None until set from the server).
partition_expiration	Expiration time in milliseconds for a partition.
partitioning_type	Time partitioning of the table if it is partitioned (Defaults to None).
path	URL path for the table’s APIs.
project	Project bound to the table.
range_partitioning	Optional[google.cloud.bigquery.table.RangePartitioning]: Configures range-based partitioning for a table.
reference	A TableReference pointing to this table.
require_partition_filter	If set to true, queries over the partitioned table require a partition filter that can be used for partition elimination to be specified.
schema	Sequence[Union[ SchemaField, Mapping[str, Any] ]]:
self_link	URL for the table resource (None until set from the server).
snapshot_definition	Information about the snapshot.
streaming_buffer	Information about a table’s streaming buffer.
table_constraints	Tables Primary Key and Foreign Key information.
table_id	The table ID.
table_type	The type of the table (None until set from the server).
time_partitioning	Configures time-based partitioning for a table.
view_query	SQL query defining the table as a view (defaults to None).
view_use_legacy_sql	Specifies whether to execute the view with Legacy or Standard SQL.

property clone_definition: Optional[google.cloud.bigquery.table.CloneDefinition]

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

property clustering_fields

Fields defining clustering for the table

(Defaults to None).

Clustering fields are immutable after table creation.

Note

BigQuery supports clustering for both partitioned and non-partitioned tables.

Type

Union[List[str], None]

property created

Datetime at which the table was created (None until set from the server).

Type

Union[datetime.datetime, None]

property dataset_id: str

ID of dataset containing the table.

property description

Description of the table (defaults to None).

Raises

ValueError – For invalid value types.

Type

Union[str, None]

property encryption_configuration

Custom encryption configuration for the table.

Custom encryption configuration (e.g., Cloud KMS keys) or None if using default encryption.

See protecting data with Cloud KMS keys in the BigQuery documentation.

Type

google.cloud.bigquery.encryption_configuration.EncryptionConfiguration

property etag

ETag for the table resource (None until set from the server).

Type

Union[str, None]

property expires

Datetime at which the table will be deleted.

Raises

ValueError – For invalid value types.

Type

Union[datetime.datetime, None]

property external_data_configuration

Configuration for an external data source (defaults to None).

Raises

ValueError – For invalid value types.

Type

Union[google.cloud.bigquery.ExternalConfig, None]

property friendly_name

Title of the table (defaults to None).

Raises

ValueError – For invalid value types.

Type

Union[str, None]

classmethod from_api_repr(resource: dict) → google.cloud.bigquery.table.Table

Factory: construct a table given its API representation

Parameters

resource (Dict[str, object]) – Table resource representation from the API

Returns

Table parsed from resource.

Return type

google.cloud.bigquery.table.Table

Raises

KeyError – If the resource lacks the key 'tableReference', or if the dict stored within the key 'tableReference' lacks the keys 'tableId', 'projectId', or 'datasetId'.

classmethod from_string(full_table_id: str) → google.cloud.bigquery.table.Table

Construct a table from fully-qualified table ID.

Parameters

full_table_id (str) – A fully-qualified table ID in standard SQL format. Must included a project ID, dataset ID, and table ID, each separated by ..

Returns

Table parsed from full_table_id.

Return type

Table

Examples

>>> Table.from_string('my-project.mydataset.mytable')
Table(TableRef...(D...('my-project', 'mydataset'), 'mytable'))

Raises

ValueError – If full_table_id is not a fully-qualified table ID in standard SQL format.

property full_table_id

ID for the table (None until set from the server).

In the format project-id:dataset_id.table_id.

Type

Union[str, None]

property labels

Labels for the table.

This method always returns a dict. To change a table’s labels, modify the dict, then call Client.update_table. To delete a label, set its value to None before updating.

Raises

ValueError – If value type is invalid.

Type

Dict[str, str]

property location

Location in which the table is hosted

Defaults to None.

Type

Union[str, None]

property modified

Datetime at which the table was last modified (None until set from the server).

Type

Union[datetime.datetime, None]

property mview_enable_refresh

Enable automatic refresh of the materialized view when the base table is updated. The default value is True.

Type

Optional[bool]

property mview_last_refresh_time

Datetime at which the materialized view was last refreshed (None until set from the server).

Type

Optional[datetime.datetime]

property mview_query

SQL query defining the table as a materialized view (defaults to None).

Type

Optional[str]

property mview_refresh_interval

The maximum frequency at which this materialized view will be refreshed. The default value is 1800000 milliseconds (30 minutes).

Type

Optional[datetime.timedelta]

property num_bytes

The size of the table in bytes (None until set from the server).

Type

Union[int, None]

property num_rows

The number of rows in the table (None until set from the server).

Type

Union[int, None]

property partition_expiration

Expiration time in milliseconds for a partition.

If partition_expiration is set and type_ is not set, type_ will default to DAY.

Type

Union[int, None]

property partitioning_type

Time partitioning of the table if it is partitioned (Defaults to None).

Type

Union[str, None]

property path: str

URL path for the table’s APIs.

property project: str

Project bound to the table.

property range_partitioning

Optional[google.cloud.bigquery.table.RangePartitioning]: Configures range-based partitioning for a table.

Note

Beta. The integer range partitioning feature is in a pre-release state and might change or have limited support.

Only specify at most one of time_partitioning or range_partitioning.

Raises

ValueError – If the value is not RangePartitioning or None.

property reference

A TableReference pointing to this table.

Returns

pointer to this table.

Return type

google.cloud.bigquery.table.TableReference

property require_partition_filter

If set to true, queries over the partitioned table require a partition filter that can be used for partition elimination to be specified.

Type

bool

property schema

Sequence[Union[ SchemaField, Mapping[str, Any] ]]:

Table’s schema.

Raises

Exception – If schema is not a sequence, or if any item in the sequence is not a SchemaField instance or a compatible mapping representation of the field.

property self_link

URL for the table resource (None until set from the server).

Type

Union[str, None]

property snapshot_definition: Optional[google.cloud.bigquery.table.SnapshotDefinition]

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

property streaming_buffer

Information about a table’s streaming buffer.

Type

google.cloud.bigquery.StreamingBuffer

property table_constraints: Optional[google.cloud.bigquery.table.TableConstraints]

Tables Primary Key and Foreign Key information.

property table_id: str

The table ID.

property table_type

The type of the table (None until set from the server).

Possible values are 'TABLE', 'VIEW', 'MATERIALIZED_VIEW' or 'EXTERNAL'.

Type

Union[str, None]

property time_partitioning

Configures time-based partitioning for a table.

Only specify at most one of time_partitioning or range_partitioning.

Raises

ValueError – If the value is not TimePartitioning or None.

Type

Optional[google.cloud.bigquery.table.TimePartitioning]

to_api_repr() → dict

Constructs the API resource of this table

Returns

Table represented as an API resource

Return type

Dict[str, object]

to_bqstorage() → str

Construct a BigQuery Storage API representation of this table.

Returns

A reference to this table in the BigQuery Storage API.

Return type

str

property view_query

SQL query defining the table as a view (defaults to None).

By default, the query is treated as Standard SQL. To use Legacy SQL, set view_use_legacy_sql to True.

Raises

ValueError – For invalid value types.

Type

Union[str, None]

property view_use_legacy_sql

Specifies whether to execute the view with Legacy or Standard SQL.

This boolean specifies whether to execute the view with Legacy SQL (True) or Standard SQL (False). The client side default is False. The server-side default is True. If this table is not a view, None is returned.

Raises

ValueError – For invalid value types.

Type

bool