Version History (0.17.0)
Report an Issue

BigQuery Client#

Client for interacting with the Google BigQuery API.

class gcloud.bigquery.client.Client(project=None, credentials=None, http=None)[source]#

Bases: gcloud.client.JSONClient

Client to bundle configuration needed for API requests.

Parameters:
  • project (str) – the project which the client acts on behalf of. Will be passed when creating a dataset / job. If not passed, falls back to the default inferred from the environment.
  • credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.
copy_table(job_name, destination, *sources)[source]#

Construct a job for copying one or more tables into another table.

See: https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.copy

Parameters:
Return type:

gcloud.bigquery.job.CopyJob
Returns:

a new CopyJob instance
dataset(dataset_name)[source]#

Construct a dataset bound to this client.

Parameters:dataset_name (str) – Name of the dataset.
Return type:gcloud.bigquery.dataset.Dataset
Returns:a new Dataset instance
extract_table_to_storage(job_name, source, *destination_uris)[source]#

Construct a job for extracting a table into Cloud Storage files.

See: https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.extract

Parameters:
  • job_name (str) – Name of the job.
  • source (gcloud.bigquery.table.Table) – table to be extracted.
  • destination_uris (sequence of string) – URIs of CloudStorage file(s) into which table data is to be extracted; in format gs://<bucket_name>/<object_name_or_glob>.
Return type:

gcloud.bigquery.job.ExtractTableToStorageJob
Returns:

a new ExtractTableToStorageJob instance
job_from_resource(resource)[source]#

Detect correct job type from resource and instantiate.

Parameters:resource (dict) – one job resource from API response
Return type:One of: gcloud.bigquery.job.LoadTableFromStorageJob, gcloud.bigquery.job.CopyJob, gcloud.bigquery.job.ExtractTableToStorageJob, gcloud.bigquery.job.QueryJob, gcloud.bigquery.job.RunSyncQueryJob
Returns:the job instance, constructed via the resource
list_datasets(include_all=False, max_results=None, page_token=None)[source]#

List datasets for the project associated with this client.

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

Parameters:
  • include_all (boolean) – True if results include hidden datasets.
  • max_results (int) – maximum number of datasets to return, If not passed, defaults to a value set by the API.
  • page_token (str) – opaque marker for the next “page” of datasets. If not passed, the API will return the first page of datasets.
Return type:

tuple, (list, str)
Returns:

list of gcloud.bigquery.dataset.Dataset, plus a “next page token” string: if the token is not None, indicates that more datasets can be retrieved with another call (pass that value as page_token).
list_jobs(max_results=None, page_token=None, all_users=None, state_filter=None)[source]#

List jobs for the project associated with this client.

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

Parameters:
  • max_results (int) – maximum number of jobs to return, If not passed, defaults to a value set by the API.
  • page_token (str) – opaque marker for the next “page” of jobs. If not passed, the API will return the first page of jobs.
  • all_users (boolean) – if true, include jobs owned by all users in the project.
  • state_filter (str) –

    if passed, include only jobs matching the given state. One of

    • "done"
    • "pending"
    • "running"
Return type:

tuple, (list, str)
Returns:

list of job instances, plus a “next page token” string: if the token is not None, indicates that more jobs can be retrieved with another call, passing that value as page_token).
load_table_from_storage(job_name, destination, *source_uris)[source]#

Construct a job for loading data into a table from CloudStorage.

See: https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.load

Parameters:
  • job_name (str) – Name of the job.
  • destination (gcloud.bigquery.table.Table) – Table into which data is to be loaded.
  • source_uris (sequence of string) – URIs of data files to be loaded; in format gs://<bucket_name>/<object_name_or_glob>.
Return type:

gcloud.bigquery.job.LoadTableFromStorageJob
Returns:

a new LoadTableFromStorageJob instance
run_async_query(job_name, query)[source]#

Construct a job for running a SQL query asynchronously.

See: https://cloud.google.com/bigquery/docs/reference/v2/jobs#configuration.query

Parameters:
  • job_name (str) – Name of the job.
  • query (str) – SQL query to be executed
Return type:

gcloud.bigquery.job.QueryJob
Returns:

a new QueryJob instance
run_sync_query(query)[source]#

Run a SQL query synchronously.

Parameters:query (str) – SQL query to be executed
Return type:gcloud.bigquery.query.QueryResults
Returns:a new QueryResults instance

Connection#

Create / interact with gcloud bigquery connections.

class gcloud.bigquery.connection.Connection(credentials=None, http=None)[source]#

Bases: gcloud.connection.JSONConnection

A connection to Google Cloud BigQuery via the JSON REST API.

API_BASE_URL = 'https://www.googleapis.com'#

The base of the API call URL.

API_URL_TEMPLATE = '{api_base_url}/bigquery/{api_version}{path}'#

A template for the URL of a particular API call.

API_VERSION = 'v2'#

The version of the API, used in building the API call’s URL.

SCOPE = ('https://www.googleapis.com/auth/bigquery', 'https://www.googleapis.com/auth/cloud-platform')#

The scopes required for authenticating as a Cloud BigQuery consumer.