Tables#

Define API Datasets.

class google.cloud.bigquery.table.Table(name, dataset, schema=())[source]#

Bases: object

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

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tables

Parameters:
create(client=None)[source]#

API call: create the dataset via a PUT request

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/insert

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
created#

Datetime at which the table was created.

Return type:datetime.datetime, or NoneType
Returns:the creation time (None until set from the server).
dataset_name#

Name of dataset containing the table.

Return type:str
Returns:the ID (derived from the dataset).
delete(client=None)[source]#

API call: delete the table via a DELETE request

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/delete

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
description#

Description of the table.

Return type:str, or NoneType
Returns:The description as set by the user, or None (the default).
etag#

ETag for the table resource.

Return type:str, or NoneType
Returns:the ETag (None until set from the server).
exists(client=None)[source]#

API call: test for the existence of the table via a GET request

See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/get

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
Return type:bool
Returns:Boolean indicating existence of the table.
expires#

Datetime at which the table will be removed.

Return type:datetime.datetime, or NoneType
Returns:the expiration time, or None
fetch_data(max_results=None, page_token=None, client=None)[source]#

API call: fetch the table data via a GET request

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tabledata/list

Note

This method assumes that its instance’s schema attribute is up-to-date with the schema as defined on the back-end: if the two schemas are not identical, the values returned may be incomplete. To ensure that the local copy of the schema is up-to-date, call reload().

Parameters:
  • max_results (int) – (Optional) Maximum number of rows to return.
  • page_token (str) – (Optional) Token representing a cursor into the table’s rows.
  • client (Client) – (Optional) The client to use. If not passed, falls back to the client stored on the current dataset.
Return type:

Iterator

Returns:

Iterator of row data tuple`s. During each page, the iterator will have the ``total_rows` attribute set, which counts the total number of rows in the table (this is distinct from the total number of rows in the current page: iterator.page.num_items).

friendly_name#

Title of the table.

Return type:str, or NoneType
Returns:The name as set by the user, or None (the default).
classmethod from_api_repr(resource, dataset)[source]#

Factory: construct a table given its API representation

Parameters:
Return type:

google.cloud.bigquery.table.Table

Returns:

Table parsed from resource.

insert_data(rows, row_ids=None, skip_invalid_rows=None, ignore_unknown_values=None, template_suffix=None, client=None)[source]#

API call: insert table data via a POST request

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/tabledata/insertAll

Parameters:
  • rows (list of tuples) – Row data to be inserted. Each tuple should contain data for each schema field on the current table and in the same order as the schema fields.
  • row_ids (list of string) – Unique ids, one per row being inserted. If not passed, no de-duplication occurs.
  • skip_invalid_rows (bool) – (Optional) skip rows w/ invalid data?
  • ignore_unknown_values (bool) – (Optional) ignore columns beyond schema?
  • template_suffix (str) – (Optional) treat name as a template table and provide a suffix. BigQuery will create the table <name> + <template_suffix> based on the schema of the template table. See: https://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
Return type:

list of mappings

Returns:

One mapping per row with insert errors: the “index” key identifies the row, and the “errors” key contains a list of the mappings describing one or more problems with the row.

Raises:

ValueError if table’s schema is not set

list_partitions(client=None)[source]#

List the partitions in a table.

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
Return type:list
Returns:a list of time partitions
location#

Location in which the table is hosted.

Return type:str, or NoneType
Returns:The location as set by the user, or None (the default).
modified#

Datetime at which the table was last modified.

Return type:datetime.datetime, or NoneType
Returns:the modification time (None until set from the server).
num_bytes#

The size of the table in bytes.

Return type:int, or NoneType
Returns:the byte count (None until set from the server).
num_rows#

The number of rows in the table.

Return type:int, or NoneType
Returns:the row count (None until set from the server).
partition_expiration#

Expiration time in ms for a partition :rtype: int, or NoneType :returns: Returns the time in ms for partition expiration

partitioning_type#

Time partitioning of the table. :rtype: str, or NoneType :returns: Returns type if the table is partitioned, None otherwise.

patch(client=None, friendly_name=<object object>, description=<object object>, location=<object object>, expires=<object object>, view_query=<object object>, schema=<object object>)[source]#

API call: update individual table properties via a PATCH request

See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/patch

Parameters:
  • client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
  • friendly_name (str) – (Optional) a descriptive name for this table.
  • description (str) – (Optional) a description of this table.
  • location (str) – (Optional) the geographic location where the table resides.
  • expires (datetime.datetime) – (Optional) point in time at which the table expires.
  • view_query (str) – SQL query defining the table as a view
  • schema (list of SchemaField) – fields describing the schema
Raises:

ValueError for invalid value types.

path#

URL path for the table’s APIs.

Return type:str
Returns:the path based on project and dataste name.
project#

Project bound to the table.

Return type:str
Returns:the project (derived from the dataset).
reload(client=None)[source]#

API call: refresh table properties via a GET request

See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/get

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
schema#

Table’s schema.

Return type:list of SchemaField
Returns:fields describing the schema

URL for the table resource.

Return type:str, or NoneType
Returns:the URL (None until set from the server).
table_id#

ID for the table resource.

Return type:str, or NoneType
Returns:the ID (None until set from the server).
table_type#

The type of the table.

Possible values are “TABLE” or “VIEW”.

Return type:str, or NoneType
Returns:the URL (None until set from the server).
update(client=None)[source]#

API call: update table properties via a PUT request

See https://cloud.google.com/bigquery/docs/reference/rest/v2/tables/update

Parameters:client (Client or NoneType) – the client to use. If not passed, falls back to the client stored on the current dataset.
upload_from_file(file_obj, source_format, rewind=False, size=None, num_retries=6, allow_jagged_rows=None, allow_quoted_newlines=None, create_disposition=None, encoding=None, field_delimiter=None, ignore_unknown_values=None, max_bad_records=None, quote_character=None, skip_leading_rows=None, write_disposition=None, client=None)[source]#

Upload the contents of this table from a file-like object.

The content type of the upload will either be - The value passed in to the function (if any) - text/csv.

Parameters:
  • file_obj (file) – A file handle opened in binary mode for reading.
  • source_format (str) – one of ‘CSV’ or ‘NEWLINE_DELIMITED_JSON’. job configuration option; see google.cloud.bigquery.job.LoadJob()
  • rewind (bool) – If True, seek to the beginning of the file handle before writing the file to Cloud Storage.
  • size (int) – The number of bytes to read from the file handle. If not provided, we’ll try to guess the size using os.fstat(). (If the file handle is not from the filesystem this won’t be possible.)
  • num_retries (int) – Number of upload retries. Defaults to 6.
  • allow_jagged_rows (bool) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • allow_quoted_newlines (bool) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • create_disposition (str) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • encoding (str) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • field_delimiter (str) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • ignore_unknown_values (bool) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • max_bad_records (int) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • quote_character (str) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • skip_leading_rows (int) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • write_disposition (str) – job configuration option; see google.cloud.bigquery.job.LoadJob().
  • client (Client or NoneType) – Optional. The client to use. If not passed, falls back to the client stored on the current dataset.
Return type:

google.cloud.bigquery.jobs.LoadTableFromStorageJob

Returns:

the job instance used to load the data (e.g., for querying status). Note that the job is already started: do not call job.begin().

Raises:

ValueError if size is not passed in and can not be determined, or if the file_obj can be detected to be a file opened in text mode.

view_query#

SQL query defining the table as a view.

Return type:str, or NoneType
Returns:The query as set by the user, or None (the default).