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/v2/tables
Parameters: - name (str) – the name of the table
- dataset (
google.cloud.bigquery.dataset.Dataset
) – The dataset which contains the table. - schema (list of
SchemaField
) – The table’s schema
-
create
(client=None)[source]# API call: create the dataset via a PUT request
See: https://cloud.google.com/bigquery/docs/reference/v2/tables/insert
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current dataset.
-
created
# Datetime at which the table was created.
Return type: datetime.datetime
, orNoneType
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/v2/tables/delete
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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/v2/tables/get
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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
, orNoneType
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/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 the table’sreload
method.Parameters: - max_results (integer or
NoneType
) – maximum number of rows to return. - page_token (str or
NoneType
) – token representing a cursor into the table’s rows. - client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current dataset.
Return type: Returns: (row_data, total_rows, page_token)
, whererow_data
is a list of tuples, one per result row, containing only the values;total_rows
is a count of the total number of rows in the table; andpage_token
is an opaque string which can be used to fetch the next batch of rows (None
if no further batches can be fetched).- max_results (integer or
-
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: - resource (dict) – table resource representation returned from the API
- dataset (
google.cloud.bigquery.dataset.Dataset
) – The dataset containing the table.
Return type: 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/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 (boolean or
NoneType
) – skip rows w/ invalid data? - ignore_unknown_values (boolean or
NoneType
) – ignore columns beyond schema? - template_suffix (str or
NoneType
) – treatname
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
orNoneType
) – the client to use. If not passed, falls back to theclient
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
orNoneType
) – the client to use. If not passed, falls back to theclient
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
, orNoneType
Returns: the modification time (None until set from the server).
-
num_bytes
# The size of the table in bytes.
Return type: integer, or NoneType
Returns: the byte count (None until set from the server).
-
num_rows
# The number of rows in the table.
Return type: integer, 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/v2/tables/patch
Parameters: - client (
Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current dataset. - friendly_name (str or
NoneType
) – point in time at which the table expires. - description (str or
NoneType
) – point in time at which the table expires. - location (str or
NoneType
) – point in time at which the table expires. - expires (
datetime.datetime
orNoneType
) – 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.
- client (
-
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/v2/tables/get
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
stored on the current dataset.
-
schema
# Table’s schema.
Return type: list of SchemaField
Returns: fields describing the schema
-
self_link
# 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/v2/tables/update
Parameters: client ( Client
orNoneType
) – the client to use. If not passed, falls back to theclient
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 (boolean) – 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 (integer) – Number of upload retries. Defaults to 6.
- allow_jagged_rows (boolean) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - allow_quoted_newlines (boolean) – 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 (boolean) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - max_bad_records (integer) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - quote_character (str) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - skip_leading_rows (integer) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - write_disposition (str) – job configuration option; see
google.cloud.bigquery.job.LoadJob()
. - client (
Client
orNoneType
) – Optional. The client to use. If not passed, falls back to theclient
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
ifsize
is not passed in and can not be determined, or if thefile_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).