BigQuery Client#

Client for interacting with the Google BigQuery API.

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

Bases: google.cloud.client.ClientWithProject

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 (Credentials) – (Optional) The OAuth2 Credentials to use for this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (Http) – (Optional) HTTP object to make requests. Can be any object that defines request() with the same interface as request(). If not passed, an http object is created that is bound to the credentials for the current object.
SCOPE = ('https://www.googleapis.com/auth/bigquery', 'https://www.googleapis.com/auth/cloud-platform')#

The scopes required for authenticating as a BigQuery consumer.

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/rest/v2/jobs#configuration.copy

Parameters:
Return type:

google.cloud.bigquery.job.CopyJob

Returns:

a new CopyJob instance

dataset(dataset_name, project=None)[source]#

Construct a dataset bound to this client.

Parameters:
  • dataset_name (str) – Name of the dataset.
  • project (str) – (Optional) project ID for the dataset (defaults to the project of the client).
Return type:

google.cloud.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/rest/v2/jobs#configuration.extract

Parameters:
  • job_name (str) – Name of the job.
  • source (google.cloud.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:

google.cloud.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: google.cloud.bigquery.job.LoadTableFromStorageJob, google.cloud.bigquery.job.CopyJob, google.cloud.bigquery.job.ExtractTableToStorageJob, google.cloud.bigquery.job.QueryJob, google.cloud.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/rest/v2/datasets/list

Parameters:
  • include_all (bool) – 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:

Iterator

Returns:

Iterator of Dataset. accessible to the current client.

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/rest/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 (bool) – 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:

Iterator

Returns:

Iterable of job instances.

list_projects(max_results=None, page_token=None)[source]#

List projects for the project associated with this client.

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

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

Iterator

Returns:

Iterator of Project accessible to the current client.

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/rest/v2/jobs#configuration.load

Parameters:
  • job_name (str) – Name of the job.
  • destination (google.cloud.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:

google.cloud.bigquery.job.LoadTableFromStorageJob

Returns:

a new LoadTableFromStorageJob instance

run_async_query(job_name, query, udf_resources=(), query_parameters=())[source]#

Construct a job for running a SQL query asynchronously.

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

Parameters:
  • job_name (str) – Name of the job.
  • query (str) – SQL query to be executed
  • udf_resources (tuple) – An iterable of google.cloud.bigquery._helpers.UDFResource (empty by default)
  • query_parameters (tuple) – An iterable of google.cloud.bigquery._helpers.AbstractQueryParameter (empty by default)
Return type:

google.cloud.bigquery.job.QueryJob

Returns:

a new QueryJob instance

run_sync_query(query, udf_resources=(), query_parameters=())[source]#

Run a SQL query synchronously.

Parameters:
  • query (str) – SQL query to be executed
  • udf_resources (tuple) – An iterable of google.cloud.bigquery._helpers.UDFResource (empty by default)
  • query_parameters (tuple) – An iterable of google.cloud.bigquery._helpers.AbstractQueryParameter (empty by default)
Return type:

google.cloud.bigquery.query.QueryResults

Returns:

a new QueryResults instance

class google.cloud.bigquery.client.Project(project_id, numeric_id, friendly_name)[source]#

Bases: object

Wrapper for resource describing a BigQuery project.

Parameters:
  • project_id (str) – Opaque ID of the project
  • numeric_id (int) – Numeric ID of the project
  • friendly_name (str) – Display name of the project
classmethod from_api_repr(resource)[source]#

Factory: construct an instance from a resource dict.