DB-API Reference

Google BigQuery implementation of the Database API Specification v2.0.

This module implements the Python Database API Specification v2.0 (DB-API) for Google BigQuery.

google.cloud.bigquery.dbapi.Binary(string)

Contruct a DB-API binary value.

• Parameters

  string( str ) – A string to encode as a binary value.

• Returns

  The UTF-8 encoded bytes representing the string.

• Return type

  bytes

class google.cloud.bigquery.dbapi.Connection(client, bqstorage_client=None)

Bases: object

DB-API Connection to Google BigQuery.

• Parameters

  • client( google.cloud.bigquery.Client ) – A client used to connect to BigQuery.

  • bqstorage_client( Optional [ google.cloud.bigquery_storage_v1beta1.BigQueryStorageClient ] ) – [Beta] An alternative client that uses the faster BigQuery Storage API to fetch rows from BigQuery. If both clients are given, bqstorage_client is used first to fetch query results, with a fallback on client , if necessary.

    NOTE: There is a known issue with the BigQuery Storage API with small anonymous result sets, which results in such fallback.

    https://github.com/googleapis/python-bigquery-storage/issues/2

close()

No-op.

commit()

No-op.

cursor()

Return a new cursor object.

• Returns

  A DB-API cursor that uses this connection.

• Return type

  google.cloud.bigquery.dbapi.Cursor

class google.cloud.bigquery.dbapi.Cursor(connection)

Bases: object

DB-API Cursor to Google BigQuery.

• Parameters

  connection( google.cloud.bigquery.dbapi.Connection ) – A DB-API connection to Google BigQuery.

close()

No-op.

execute(operation, parameters=None, job_id=None, job_config=None)

Prepare and execute a database operation.

NOTE: When setting query parameters, values which are “text” ( unicode in Python2, str in Python3) will use the ‘STRING’ BigQuery type. Values which are “bytes” ( str in Python2, bytes in Python3), will use using the ‘BYTES’ type.

A ~datetime.datetime parameter without timezone information uses the ‘DATETIME’ BigQuery type (example: Global Pi Day Celebration March 14, 2017 at 1:59pm). A ~datetime.datetime parameter with timezone information uses the ‘TIMESTAMP’ BigQuery type (example: a wedding on April 29, 2011 at 11am, British Summer Time).

For more information about BigQuery data types, see: https://cloud.google.com/bigquery/docs/reference/standard-sql/data-types

STRUCT / RECORD and REPEATED query parameters are not yet supported. See: https://github.com/GoogleCloudPlatform/google-cloud-python/issues/3524

• Parameters

  • operation( str ) – A Google BigQuery query string.

  • parameters( Union [ Mapping [ str , **Any ] , **Sequence [ Any ] ] ) – (Optional) dictionary or sequence of parameter values.

  • job_id( str ) – (Optional) The job_id to use. If not set, a job ID is generated at random.

  • job_config( google.cloud.bigquery.job.QueryJobConfig ) – (Optional) Extra configuration options for the query job.

executemany(operation, seq_of_parameters)

Prepare and execute a database operation multiple times.

• Parameters

  • operation( str ) – A Google BigQuery query string.

  • seq_of_parameters( Union [ Sequence [ Mapping [ str , **Any ] , **Sequence [ Any ] ] ] ) – Sequence of many sets of parameter values.

fetchall()

Fetch all remaining results from the last execute\*() call.

• Returns

  A list of all the rows in the results.

• Return type

  List[Tuple]

• Raises

  google.cloud.bigquery.dbapi.InterfaceError– if called before execute() .

fetchmany(size=None)

Fetch multiple results from the last execute\*() call.

NOTE: The size parameter is not used for the request/response size. Set the arraysize attribute before calling execute() to set the batch size.

• Parameters

  size( int ) – (Optional) Maximum number of rows to return. Defaults to the arraysize property value. If arraysize is not set, it defaults to 1 .

• Returns

  A list of rows.

• Return type

  List[Tuple]

• Raises

  google.cloud.bigquery.dbapi.InterfaceError– if called before execute() .

fetchone()

Fetch a single row from the results of the last execute\*() call.

• Returns

  A tuple representing a row or None if no more data is available.

• Return type

  Tuple

• Raises

  google.cloud.bigquery.dbapi.InterfaceError– if called before execute() .

setinputsizes(sizes)

No-op.

setoutputsize(size, column=None)

No-op.

exception google.cloud.bigquery.dbapi.DataError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API error due to problems with the processed data.

exception google.cloud.bigquery.dbapi.DatabaseError()

Bases: google.cloud.bigquery.dbapi.exceptions.Error

DB-API error related to the database.

google.cloud.bigquery.dbapi.Date()

alias of datetime.date

google.cloud.bigquery.dbapi.DateFromTicks(timestamp, /)

Create a date from a POSIX timestamp.

The timestamp is a number, e.g. created via time.time(), that is interpreted as local time.

exception google.cloud.bigquery.dbapi.Error()

Bases: Exception

Exception representing all non-warning DB-API errors.

exception google.cloud.bigquery.dbapi.IntegrityError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API error when integrity of the database is affected.

exception google.cloud.bigquery.dbapi.InterfaceError()

Bases: google.cloud.bigquery.dbapi.exceptions.Error

DB-API error related to the database interface.

exception google.cloud.bigquery.dbapi.InternalError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API error when the database encounters an internal error.

exception google.cloud.bigquery.dbapi.NotSupportedError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API error for operations not supported by the database or API.

exception google.cloud.bigquery.dbapi.OperationalError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API error related to the database operation.

These errors are not necessarily under the control of the programmer.

exception google.cloud.bigquery.dbapi.ProgrammingError()

Bases: google.cloud.bigquery.dbapi.exceptions.DatabaseError

DB-API exception raised for programming errors.

google.cloud.bigquery.dbapi.Time()

alias of datetime.time

google.cloud.bigquery.dbapi.TimeFromTicks(ticks, tz=None)

Construct a DB-API time value from the given ticks value.

• Parameters

  • ticks( float ) – a number of seconds since the epoch; see the documentation of the standard Python time module for details.

  • tz( datetime.tzinfo ) – (Optional) time zone to use for conversion

• Returns

  time represented by ticks.

• Return type

  datetime.time

google.cloud.bigquery.dbapi.Timestamp()

alias of datetime.datetime

google.cloud.bigquery.dbapi.TimestampFromTicks()

timestamp[, tz] -> tz’s local time from POSIX timestamp.

exception google.cloud.bigquery.dbapi.Warning()

Bases: Exception

Exception raised for important DB-API warnings.

google.cloud.bigquery.dbapi.connect(client=None, bqstorage_client=None)

Construct a DB-API connection to Google BigQuery.

• Parameters

  • client( Optional [ google.cloud.bigquery.Client ] ) – A client used to connect to BigQuery. If not passed, a client is created using default options inferred from the environment.

  • bqstorage_client( Optional [ google.cloud.bigquery_storage_v1beta1.BigQueryStorageClient ] ) – [Beta] An alternative client that uses the faster BigQuery Storage API to fetch rows from BigQuery. If both clients are given, bqstorage_client is used first to fetch query results, with a fallback on client , if necessary.

    NOTE: There is a known issue with the BigQuery Storage API with small anonymous result sets, which results in such fallback.

    https://github.com/googleapis/python-bigquery-storage/issues/2

• Returns

  A new DB-API connection to BigQuery.

• Return type

  google.cloud.bigquery.dbapi.Connection