On January 1, 2020 this library will no longer support Python 2 on the latest released version. Previously released library versions 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)[source]

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)[source]

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

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).

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).

streaming_buffer

Information about a table’s streaming buffer.

table_id

ID of the table.

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 clustering_fields

Fields defining clustering for the table

(Defaults to None).

Clustering fields are immutable after table creation.

Note

As of 2018-06-29, clustering fields cannot be set on a table which does not also have time partioning defined.

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

ID of dataset containing the table.

Type

str

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)[source]

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)[source]

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 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).

The only partitioning type that is currently supported is DAY.

Type

Union[str, None]

property path

URL path for the table’s APIs.

Type

str

property project

Project bound to the table.

Type

str

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.

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

Type

Union[str, None]

property streaming_buffer

Information about a table’s streaming buffer.

Type

google.cloud.bigquery.StreamingBuffer

property table_id

ID of the table.

Type

str

property table_type

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

Possible values are 'TABLE', '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()[source]

Constructs the API resource of this table

Returns

Table represented as an API resource

Return type

Dict[str, object]

to_bqstorage()[source]

Construct a BigQuery Storage API representation of this table.

Returns

A reference to this table in the BigQuery Storage API.

Return type

google.cloud.bigquery_storage_v1beta1.types.TableReference

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