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. This parameter should be considered private, and could change in the future.
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.