Class Client (2.0.0)

Client(project=None,credentials=None,_http=None,location=None,default_query_job_config=None,client_info=None,client_options=None,)

Client to bundle configuration needed for API requests.

Parameters

NameDescription
projectOptional[str]

Project ID for 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.

credentialsOptional[google.auth.credentials.Credentials]

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.

_httpOptional[requests.Session]

HTTP object to make requests. Can be any object that definesrequest() with the same interface asrequests.Session.request. If not passed, an_http object is created that is bound to thecredentials for the current object. This parameter should be considered private, and could change in the future.

locationOptional[str]

Default location for jobs / datasets / tables.

default_query_job_configOptional[google.cloud.bigquery.job.QueryJobConfig]

DefaultQueryJobConfig. Will be merged into job configs passed into thequery method.

client_infoOptional[google.api_core.client_info.ClientInfo]

The client info used to send a user-agent string along with API requests. IfNone, then default info will be used. Generally, you only need to set this if you're developing your own library or partner tool.

client_optionsOptional[Union[google.api_core.client_options.ClientOptions, Dict]]

Client options used to set user options on the client. API Endpoint should be set through client_options.

Inheritance

builtins.object >google.cloud.client._ClientFactoryMixin >google.cloud.client.Client >builtins.object >google.cloud.client._ClientProjectMixin >google.cloud.client.ClientWithProject >Client

Properties

location

Default location for jobs / datasets / tables.

Methods

__getstate__

__getstate__()

Explicitly state that clients are not pickleable.

cancel_job

cancel_job(job_id,project=None,location=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameter
NameDescription
job_idstr :keyword project: ID of the project which owns the job (defaults to the client's project). :kwtype project: Optional[str] :keyword location: Location where the job was run. :kwtype location: Optional[str] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float]

Unique job identifier.

Returns
TypeDescription
Union[ google.cloud.bigquery.job.LoadJob,google.cloud.bigquery.job.CopyJob, google.cloud.bigquery.job.ExtractJob, google.cloud.bigquery.job.QueryJob, ]Job instance, based on the resource returned by the API.

close

close()

copy_table

Parameters
NameDescription
sourcesUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, Sequence[ Union[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ] ], ]

Table or tables to be copied.

destinationUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ] :keyword job_id: The ID of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of any source table as well as the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. :kwtype job_config: Optional[google.cloud.bigquery.job.CopyJobConfig] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float]

Table into which data is to be copied.

Exceptions
TypeDescription
TypeErrorIf ``job_config`` is not an instance ofCopyJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.CopyJobA new copy job instance.

create_dataset

create_dataset(dataset,exists_ok=False,retry=<google.api_core.retry.Retryobject>,timeout=None)

API call: create the dataset via a POST request.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/insert

Parameters
NameDescription
datasetUnion[google.cloud.bigquery.dataset.Dataset,google.cloud.bigquery.dataset.DatasetReference, str, ]

ADataset to create. Ifdataset is a reference, an empty dataset is created with the specified ID and client's default location.

exists_okOptional[bool]

Defaults toFalse. IfTrue, ignore "already exists" errors when creating the dataset.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Exceptions
TypeDescription
google.cloud.exceptions.ConflictIf the dataset already exists. .. rubric:: Example >>> from google.cloud import bigquery >>> client = bigquery.Client() >>> dataset = bigquery.Dataset('my_project.my_dataset') >>> dataset = client.create_dataset(dataset)
Returns
TypeDescription
google.cloud.bigquery.dataset.DatasetA new ``Dataset`` returned from the API.

create_job

create_job(job_config,retry=<google.api_core.retry.Retryobject>)

Create a new job.

Parameter
NameDescription
job_configdict :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry]

configuration job representation returned from the API.

Returns
TypeDescription
Union[ google.cloud.bigquery.job.LoadJob,google.cloud.bigquery.job.CopyJob, google.cloud.bigquery.job.ExtractJob, google.cloud.bigquery.job.QueryJob ]A new job instance.

create_routine

create_routine(routine,exists_ok=False,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
routinegoogle.cloud.bigquery.routine.Routine

ARoutine to create. The dataset that the routine belongs to must already exist.

exists_okOptional[bool]

Defaults toFalse. IfTrue, ignore "already exists" errors when creating the routine.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Exceptions
TypeDescription
google.cloud.exceptions.ConflictIf the routine already exists.
Returns
TypeDescription
google.cloud.bigquery.routine.RoutineA new ``Routine`` returned from the service.

create_table

create_table(table,exists_ok=False,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

ATable to create. Iftable is a reference, an empty table is created with the specified ID. The dataset that the table belongs to must already exist.

exists_okOptional[bool]

Defaults toFalse. IfTrue, ignore "already exists" errors when creating the table.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Exceptions
TypeDescription
google.cloud.exceptions.ConflictIf the table already exists.
Returns
TypeDescription
google.cloud.bigquery.table.TableA new ``Table`` returned from the service.

dataset

dataset(dataset_id,project=None)
Parameters
NameDescription
dataset_idstr

ID of the dataset.

projectOptional[str]

Project ID for the dataset (defaults to the project of the client).

Returns
TypeDescription
google.cloud.bigquery.dataset.DatasetReferencea new ``DatasetReference`` instance.

delete_dataset

delete_dataset(dataset,delete_contents=False,retry=<google.api_core.retry.Retryobject>,timeout=None,not_found_ok=False)
Parameters
NameDescription
datasetUnion[google.cloud.bigquery.dataset.Dataset,google.cloud.bigquery.dataset.DatasetReference, str, ]

A reference to the dataset to delete. If a string is passed in, this method attempts to create a dataset reference from a string usingfrom_string.

delete_contentsOptional[bool]

If True, delete all the tables in the dataset. If False and the dataset contains tables, the request will fail. Default is False.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

not_found_okOptional[bool]

Defaults toFalse. IfTrue, ignore "not found" errors when deleting the dataset.

delete_model

delete_model(model,retry=<google.api_core.retry.Retryobject>,timeout=None,not_found_ok=False)
Parameters
NameDescription
modelUnion[ google.cloud.bigquery.model.Model, google.cloud.bigquery.model.ModelReference, str, ]

A reference to the model to delete. If a string is passed in, this method attempts to create a model reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

not_found_okOptional[bool]

Defaults toFalse. IfTrue, ignore "not found" errors when deleting the model.

delete_routine

delete_routine(routine,retry=<google.api_core.retry.Retryobject>,timeout=None,not_found_ok=False)
Parameters
NameDescription
routineUnion[ google.cloud.bigquery.routine.Routine, google.cloud.bigquery.routine.RoutineReference, str, ]

A reference to the routine to delete. If a string is passed in, this method attempts to create a routine reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

not_found_okOptional[bool]

Defaults toFalse. IfTrue, ignore "not found" errors when deleting the routine.

delete_table

delete_table(table,retry=<google.api_core.retry.Retryobject>,timeout=None,not_found_ok=False)
Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

A reference to the table to delete. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

not_found_okOptional[bool]

Defaults toFalse. IfTrue, ignore "not found" errors when deleting the table.

extract_table

extract_table(source,destination_uris,job_id=None,job_id_prefix=None,location=None,project=None,job_config=None,retry=<google.api_core.retry.Retryobject>,timeout=None,source_type='Table')

Start a job to extract a table into Cloud Storage files.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationextract

Parameters
NameDescription
sourceUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, google.cloud.bigquery.model.Model, google.cloud.bigquery.model.ModelReference, src, ]

Table or Model to be extracted.

destination_urisUnion[str, Sequence[str]] :keyword job_id: The ID of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the source table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. :kwtype job_config: Optional[google.cloud.bigquery.job.ExtractJobConfig] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float] :keyword source_type: Type of source to be extracted.``Table`` or ``Model``. Defaults to ``Table``. :kwtype source_type: Optional[str]

URIs of Cloud Storage file(s) into which table data is to be extracted; in formatgs://<bucket_name>/<object_name_or_glob>.

Exceptions
TypeDescription
TypeErrorIf ``job_config`` is not an instance ofExtractJobConfig class.
ValueErrorIf ``source_type`` is not among ``Table``,``Model``.
Returns
TypeDescription
google.cloud.bigquery.job.ExtractJobA new extract job instance.

from_service_account_info

from_service_account_info(info,*args,**kwargs)

Factory to retrieve JSON credentials while creating client.

Parameters
NameDescription
argstuple

Remaining positional arguments to pass to constructor.

infodict

The JSON object with a private key and other credentials information (downloaded from the Google APIs console).

Exceptions
TypeDescription
TypeErrorif there is a conflict with the kwargs and the credentials created by the factory.
Returns
TypeDescription
`_ClientFactoryMixin`The client created with the retrieved JSON credentials.

from_service_account_json

from_service_account_json(json_credentials_path,*args,**kwargs)

Factory to retrieve JSON credentials while creating client.

Parameters
NameDescription
argstuple

Remaining positional arguments to pass to constructor.

json_credentials_pathstr

The path to a private key file (this file was given to you when you created the service account). This file must contain a JSON object with a private key and other credentials information (downloaded from the Google APIs console).

Exceptions
TypeDescription
TypeErrorif there is a conflict with the kwargs and the credentials created by the factory.
Returns
TypeDescription
`_ClientFactoryMixin`The client created with the retrieved JSON credentials.

get_dataset

get_dataset(dataset_ref,retry=<google.api_core.retry.Retryobject>,timeout=None)

Fetch the dataset referenced bydataset_ref

Parameters
NameDescription
dataset_refUnion[google.cloud.bigquery.dataset.DatasetReference, str, ]

A reference to the dataset to fetch from the BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.dataset.DatasetA ``Dataset`` instance.

get_job

get_job(job_id,project=None,location=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

Fetch a job for the project associated with this client.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/get

Parameter
NameDescription
job_idstr :keyword project: ID of the project which owns the job (defaults to the client's project). :kwtype project: Optional[str] :keyword location: Location where the job was run. :kwtype location: Optional[str] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float]

Unique job identifier.

Returns
TypeDescription
Union[ google.cloud.bigquery.job.LoadJob,google.cloud.bigquery.job.CopyJob, google.cloud.bigquery.job.ExtractJob, google.cloud.bigquery.job.QueryJob ]Job instance, based on the resource returned by the API.

get_model

get_model(model_ref,retry=<google.api_core.retry.Retryobject>,timeout=None)

[Beta] Fetch the model referenced bymodel_ref.

Parameters
NameDescription
model_refUnion[ google.cloud.bigquery.model.ModelReference, str, ]

A reference to the model to fetch from the BigQuery API. If a string is passed in, this method attempts to create a model reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.model.ModelA ``Model`` instance.

get_routine

get_routine(routine_ref,retry=<google.api_core.retry.Retryobject>,timeout=None)

[Beta] Get the routine referenced byroutine_ref.

Parameters
NameDescription
routine_refUnion[ google.cloud.bigquery.routine.Routine, google.cloud.bigquery.routine.RoutineReference, str, ]

A reference to the routine to fetch from the BigQuery API. If a string is passed in, this method attempts to create a reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the API call.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.routine.RoutineA ``Routine`` instance.

get_service_account_email

get_service_account_email(project=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

Get the email address of the project's BigQuery service account

Note:This is the service account that BigQuery uses to manage tablesencrypted by a key in KMS.
Parameters
NameDescription
projectOptional[str]

Project ID to use for retreiving service account email. Defaults to the client's project.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
str .. rubric:: Example >>> from google.cloud import bigquery >>> client = bigquery.Client() >>> client.get_service_account_email() my_service_account@my-project.iam.gserviceaccount.comservice account email address

get_table

get_table(table,retry=<google.api_core.retry.Retryobject>,timeout=None)

Fetch the table referenced bytable.

Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

A reference to the table to fetch from the BigQuery API. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.table.TableA ``Table`` instance.

insert_rows

insert_rows(table,rows,selected_fields=None,**kwargs)
Parameters
NameDescription
kwargsDict

Keyword arguments toinsert_rows_json.

tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

The destination table for the row data, or a reference to it.

rowsUnion[Sequence[Tuple], Sequence[Dict]]

Row data to be inserted. If a list of tuples is given, each tuple should contain data for each schema field on the current table and in the same order as the schema fields. If a list of dictionaries is given, the keys must include all required fields in the schema. Keys which do not correspond to a field in the schema are ignored.

selected_fieldsSequence[google.cloud.bigquery.schema.SchemaField]

The fields to return. Required iftable is aTableReference.

Exceptions
TypeDescription
ValueErrorif table's schema is not set or `rows` is not a `Sequence`.
Returns
TypeDescription
Sequence[Mappings]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.

insert_rows_from_dataframe

insert_rows_from_dataframe(table,dataframe,selected_fields=None,chunk_size=500,**kwargs)

Insert rows into a table from a dataframe via the streaming API.

Parameters
NameDescription
kwargsDict

Keyword arguments toinsert_rows_json.

tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

The destination table for the row data, or a reference to it.

dataframepandas.DataFrame

Apandas.DataFrame containing the data to load. AnyNaN values present in the dataframe are omitted from the streaming API request(s).

selected_fieldsSequence[google.cloud.bigquery.schema.SchemaField]

The fields to return. Required iftable is aTableReference.

chunk_sizeint

The number of rows to stream in a single chunk. Must be positive.

Exceptions
TypeDescription
ValueErrorif table's schema is not set
Returns
TypeDescription
Sequence[Sequence[Mappings]]A list with insert errors for each insert chunk. Each element is a list containing 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.

insert_rows_json

insert_rows_json(table,json_rows,row_ids=None,skip_invalid_rows=None,ignore_unknown_values=None,template_suffix=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

Insert rows into a table without applying local type conversions.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/tabledata/insertAll

Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table google.cloud.bigquery.table.TableReference, str ]

The destination table for the row data, or a reference to it.

json_rowsSequence[Dict]

Row data to be inserted. Keys must match the table schema fields and values must be JSON-compatible representations.

row_idsOptional[Sequence[Optional[str]]]

Unique IDs, one per row being inserted. An ID can also beNone, indicating that an explicit insert ID shouldnot be used for that row. If the argument is omitted altogether, unique IDs are created automatically.

skip_invalid_rowsOptional[bool]

Insert all valid rows of a request, even if invalid rows exist. The default value isFalse, which causes the entire request to fail if any invalid rows exist.

ignore_unknown_valuesOptional[bool]

Accept rows that contain values that do not match the schema. The unknown values are ignored. Default isFalse, which treats unknown values as errors.

template_suffixOptional[str]

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. Seehttps://cloud.google.com/bigquery/streaming-data-into-bigquery#template-tables

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Exceptions
TypeDescription
TypeErrorif `json_rows` is not a `Sequence`.
Returns
TypeDescription
Sequence[Mappings]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.

job_from_resource

job_from_resource(resource)

Detect correct job type from resource and instantiate.

Parameter
NameDescription
resourceDict

one job resource from API response

Returns
TypeDescription
Union[ google.cloud.bigquery.job.LoadJob,google.cloud.bigquery.job.CopyJob, google.cloud.bigquery.job.ExtractJob, google.cloud.bigquery.job.QueryJob ]The job instance, constructed via the resource.

list_datasets

list_datasets(project=None,include_all=False,filter=None,max_results=None,page_token=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

List datasets for the project associated with this client.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list

Parameters
NameDescription
projectOptional[str]

Project ID to use for retreiving datasets. Defaults to the client's project.

include_allOptional[bool]

True if results include hidden datasets. Defaults to False.

filterOptional[str]

An expression for filtering the results by label. For syntax, seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/datasets/list#body.QUERY_PARAMETERS.filter

max_resultsOptional[int]

Maximum number of datasets to return.

page_tokenOptional[str]

Token representing a cursor into the datasets. If not passed, the API will return the first page of datasets. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of thegoogle.api_core.page_iterator.HTTPIterator.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.api_core.page_iterator.IteratorIterator ofDatasetListItem. associated with the project.

list_jobs

list_jobs(project=None,parent_job=None,max_results=None,page_token=None,all_users=None,state_filter=None,retry=<google.api_core.retry.Retryobject>,timeout=None,min_creation_time=None,max_creation_time=None)

List jobs for the project associated with this client.

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/list

Parameters
NameDescription
projectOptional[str]

Project ID to use for retreiving datasets. Defaults to the client's project.

parent_jobOptional[Union[ google.cloud.bigquery.job._AsyncJob, str, ]]

If set, retrieve only child jobs of the specified parent.

max_resultsOptional[int]

Maximum number of jobs to return.

page_tokenOptional[str]

Opaque marker for the next "page" of jobs. If not passed, the API will return the first page of jobs. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token ofgoogle.api_core.page_iterator.HTTPIterator.

all_usersOptional[bool]

If true, include jobs owned by all users in the project. Defaults to :data:False.

state_filterOptional[str]

If set, include only jobs matching the given state. One of: *"done" *"pending" *"running"

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

min_creation_timeOptional[datetime.datetime]

Min value for job creation time. If set, only jobs created after or at this timestamp are returned. If the datetime has no time zone assumes UTC time.

max_creation_timeOptional[datetime.datetime]

Max value for job creation time. If set, only jobs created before or at this timestamp are returned. If the datetime has no time zone assumes UTC time.

Returns
TypeDescription
google.api_core.page_iterator.IteratorIterable of job instances.

list_models

list_models(dataset,max_results=None,page_token=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
datasetUnion[google.cloud.bigquery.dataset.Dataset,google.cloud.bigquery.dataset.DatasetReference, str, ]

A reference to the dataset whose models to list from the BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string usingfrom_string.

max_resultsOptional[int]

Maximum number of models to return. If not passed, defaults to a value set by the API.

page_tokenOptional[str]

Token representing a cursor into the models. If not passed, the API will return the first page of models. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of thegoogle.api_core.page_iterator.HTTPIterator.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float] Returns: google.api_core.page_iterator.Iterator: Iterator ofModel contained within the requested dataset.

The number of seconds to wait for the underlying HTTP transport before usingretry.

list_partitions

list_partitions(table,retry=<google.api_core.retry.Retryobject>,timeout=None)

List the partitions in a table.

Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ]

The table or reference from which to get partition info

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry. If multiple requests are made under the hood,timeout applies to each individual request.

Returns
TypeDescription
List[str]A list of the partition ids present in the partitioned table

list_projects

list_projects(max_results=None,page_token=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

List projects for the project associated with this client.

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

Parameters
NameDescription
max_resultsOptional[int]

Maximum number of projects to return, If not passed, defaults to a value set by the API.

page_tokenOptional[str]

Token representing a cursor into the projects. If not passed, the API will return the first page of projects. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of thegoogle.api_core.page_iterator.HTTPIterator.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.api_core.page_iterator.IteratorIterator ofProject accessible to the current client.

list_routines

list_routines(dataset,max_results=None,page_token=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
datasetUnion[google.cloud.bigquery.dataset.Dataset,google.cloud.bigquery.dataset.DatasetReference, str, ]

A reference to the dataset whose routines to list from the BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string usingfrom_string.

max_resultsOptional[int]

Maximum number of routines to return. If not passed, defaults to a value set by the API.

page_tokenOptional[str]

Token representing a cursor into the routines. If not passed, the API will return the first page of routines. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of thegoogle.api_core.page_iterator.HTTPIterator.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float] Returns: google.api_core.page_iterator.Iterator: Iterator of allRoutines contained within the requested dataset, limited by ``max_results``.

The number of seconds to wait for the underlying HTTP transport before usingretry.

list_rows

list_rows(table,selected_fields=None,max_results=None,page_token=None,start_index=None,page_size=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
tableUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableListItem, google.cloud.bigquery.table.TableReference, str, ]

The table to list, or a reference to it. When the table object does not contain a schema andselected_fields is not supplied, this method callsget_table to fetch the table schema.

selected_fieldsSequence[google.cloud.bigquery.schema.SchemaField]

The fields to return. If not supplied, data for all columns are downloaded.

max_resultsOptional[int]

Maximum number of rows to return.

page_tokenOptional[str]

Token representing a cursor into the table's rows. If not passed, the API will return the first page of the rows. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of theRowIterator.

start_indexOptional[int]

The zero-based index of the starting row to read.

page_sizeOptional[int]

The maximum number of rows in each page of results from this request. Non-positive values are ignored. Defaults to a sensible value set by the API.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry. If multiple requests are made under the hood,timeout applies to each individual request.

Returns
TypeDescription
google.cloud.bigquery.table.RowIteratorIterator of row dataRow-s. During each page, the iterator will have the ``total_rows`` attribute set, which counts the total number of rows **in the table** (this is distinct from the total number of rows in the current page: ``iterator.page.num_items``).

list_tables

list_tables(dataset,max_results=None,page_token=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
datasetUnion[google.cloud.bigquery.dataset.Dataset,google.cloud.bigquery.dataset.DatasetReference, str, ]

A reference to the dataset whose tables to list from the BigQuery API. If a string is passed in, this method attempts to create a dataset reference from a string usingfrom_string.

max_resultsOptional[int]

Maximum number of tables to return. If not passed, defaults to a value set by the API.

page_tokenOptional[str]

Token representing a cursor into the tables. If not passed, the API will return the first page of tables. The token marks the beginning of the iterator to be returned and the value of thepage_token can be accessed atnext_page_token of thegoogle.api_core.page_iterator.HTTPIterator.

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.api_core.page_iterator.IteratorIterator ofTableListItem contained within the requested dataset.

load_table_from_dataframe

load_table_from_dataframe(dataframe,destination,num_retries=6,job_id=None,job_id_prefix=None,location=None,project=None,job_config=None,parquet_compression="snappy",)
Parameters
NameDescription
dataframepandas.DataFrame

Apandas.DataFrame containing the data to load.

destinationgoogle.cloud.bigquery.table.TableReference :keyword num_retries: Number of upload retries. :kwtype num_retries: Optional[int] :keyword job_id: Name of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. To override the default pandas data type conversions, supply a value forschema with column names matching those of the dataframe. The BigQuery schema is used to determine the correct data type conversion. Indexes are not loaded. Requires the `pyarrow` library. :kwtype job_config: Optional[google.cloud.bigquery.job.LoadJobConfig] :keyword parquet_compression: [Beta] The compression method to use if intermittently serializing ``dataframe`` to a parquet file. If ``pyarrow`` and job config schema are used, the argument is directly passed as the ``compression`` argument to the underlying ``pyarrow.parquet.write_table()`` method (the default value "snappy" gets converted to uppercase). https://arrow.apache.org/docs/python/generated/pyarrow.parquet.write_table.html#pyarrow-parquet-write-table If either ``pyarrow`` or job config schema are missing, the argument is directly passed as the ``compression`` argument to the underlying ``DataFrame.to_parquet()`` method. https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_parquet.html#pandas.DataFrame.to_parquet :kwtype parquet_compression: Optional[str]

The destination table to use for loading the data. If it is an existing table, the schema of thepandas.DataFrame must match the schema of the destination table. If the table does not yet exist, the schema is inferred from thepandas.DataFrame. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

Exceptions
TypeDescription
ImportErrorIf a usable parquet engine cannot be found. This method requires `pyarrow` or `fastparquet` to be installed.
TypeErrorIf ``job_config`` is not an instance ofLoadJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.LoadJobA new load job.

load_table_from_file

load_table_from_file(file_obj,destination,rewind=False,size=None,num_retries=6,job_id=None,job_id_prefix=None,location=None,project=None,job_config=None,)

Upload the contents of this table from a file-like object.

Similar toload_table_from_uri, this method creates, starts andreturns a xref_LoadJob.

Parameters
NameDescription
file_objfile

A file handle opened in binary mode for reading.

destinationUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ] :keyword rewind: If True, seek to the beginning of the file handle before reading the file. :kwtype rewind: Optional[bool] :keyword size: The number of bytes to read from the file handle. If size is ``None`` or large, resumable upload will be used. Otherwise, multipart upload will be used. :kwtype size: Optional[int] :keyword num_retries: Number of upload retries. Defaults to 6. :kwtype num_retries: Optional[int] :keyword job_id: Name of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. :kwtype job_config: Optional[google.cloud.bigquery.job.LoadJobConfig]

Table into which data is to be loaded. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

Exceptions
TypeDescription
ValueErrorIf ``size`` is not passed in and can not be determined, or if the ``file_obj`` can be detected to be a file opened in text mode.
TypeErrorIf ``job_config`` is not an instance ofLoadJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.LoadJobA new load job.

load_table_from_json

load_table_from_json(json_rows,destination,num_retries=6,job_id=None,job_id_prefix=None,location=None,project=None,job_config=None,)

Upload the contents of a table from a JSON string or dict.

Parameters
NameDescription
json_rowsIterable[Dict[str, Any]]

Row data to be inserted. Keys must match the table schema fields and values must be JSON-compatible representations. .. note:: If your data is already a newline-delimited JSON string, it is best to wrap it into a file-like object and pass it toload_table_from_file:: import io from google.cloud import bigquery data = u'{"foo": "bar"}' data_as_file = io.StringIO(data) client = bigquery.Client() client.load_table_from_file(data_as_file, ...)

destinationUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ] :keyword num_retries: Number of upload retries. :kwtype num_retries: Optional[int] :keyword job_id: Name of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. The ``source_format`` setting is always set toNEWLINE_DELIMITED_JSON. :kwtype job_config: Optional[google.cloud.bigquery.job.LoadJobConfig]

Table into which data is to be loaded. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

Exceptions
TypeDescription
TypeErrorIf ``job_config`` is not an instance ofLoadJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.LoadJobA new load job.

load_table_from_uri

load_table_from_uri(source_uris,destination,job_id=None,job_id_prefix=None,location=None,project=None,job_config=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

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

Seehttps://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationload

Parameters
NameDescription
source_urisUnion[str, Sequence[str]]

URIs of data files to be loaded; in formatgs://<bucket_name>/<object_name_or_glob>.

destinationUnion[ google.cloud.bigquery.table.Table, google.cloud.bigquery.table.TableReference, str, ] :keyword job_id: Name of the job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The user-provided prefix for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword job_config: Extra configuration options for the job. :kwtype job_config: Optional[google.cloud.bigquery.job.LoadJobConfig] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float]

Table into which data is to be loaded. If a string is passed in, this method attempts to create a table reference from a string usingfrom_string.

Exceptions
TypeDescription
TypeErrorIf ``job_config`` is not an instance ofLoadJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.LoadJobA new load job.

query

query(query,job_config=None,job_id=None,job_id_prefix=None,location=None,project=None,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameter
NameDescription
querystr :keyword job_config: Extra configuration options for the job. To override any options that were previously set in the ``default_query_job_config`` given to the ``Client`` constructor, manually set those options to ``None``, or whatever value is preferred. :kwtype job_config: Optional[google.cloud.bigquery.job.QueryJobConfig] :keyword job_id: ID to use for the query job. :kwtype job_id: Optional[str] :keyword job_id_prefix: The prefix to use for a randomly generated job ID. This parameter will be ignored if a ``job_id`` is also given. :kwtype job_id_prefix: Optional[str] :keyword location: Location where to run the job. Must match the location of the any table used in the query as well as the destination table. :kwtype location: Optional[str] :keyword project: Project ID of the project of where to run the job. Defaults to the client's project. :kwtype project: Optional[str] :keyword retry: How to retry the RPC. :kwtype retry: Optional[google.api_core.retry.Retry] :keyword timeout: The number of seconds to wait for the underlying HTTP transport before using ``retry``. :kwtype timeout: Optional[float]

SQL query to be executed. Defaults to the standard SQL dialect. Use thejob_config parameter to change dialects.

Exceptions
TypeDescription
TypeErrorIf ``job_config`` is not an instance ofQueryJobConfig class.
Returns
TypeDescription
google.cloud.bigquery.job.QueryJobA new query job instance.

schema_from_json

schema_from_json(file_or_path)

Takes a file object or file path that contains json that describesa table schema.

schema_to_json

schema_to_json(schema_list,destination)

Takes a list of schema field objects.

Serializes the list of schema field objects as json to a file.

Destination is a file path or a file object.

update_dataset

update_dataset(dataset,fields,retry=<google.api_core.retry.Retryobject>,timeout=None)

Change some fields of a dataset.

Usefields to specify which fields to update. At least one fieldmust be provided. If a field is listed infields and isNone indataset, it will be deleted.

Ifdataset.etag is notNone, the update will onlysucceed if the dataset on the server has the same ETag. Thusreading a dataset withget_dataset, changing its fields,and then passing it toupdate_dataset will ensure that the changeswill only be saved if no modifications to the dataset occurredsince the read.

Parameters
NameDescription
datasetgoogle.cloud.bigquery.dataset.Dataset

The dataset to update.

fieldsSequence[str]

The properties ofdataset to change (e.g. "friendly_name").

retryOptional[google.api_core.retry.Retry]

How to retry the RPC.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.dataset.DatasetThe modified ``Dataset`` instance.

update_model

update_model(model,fields,retry=<google.api_core.retry.Retryobject>,timeout=None)

[Beta] Change some fields of a model.

Usefields to specify which fields to update. At least one fieldmust be provided. If a field is listed infields and isNoneinmodel, the field value will be deleted.

Ifmodel.etag is notNone, the update will only succeed ifthe model on the server has the same ETag. Thus reading a model withget_model, changing its fields, and then passing it toupdate_model will ensure that the changes will only be saved ifno modifications to the model occurred since the read.

Parameters
NameDescription
modelgoogle.cloud.bigquery.model.Model

The model to update.

fieldsSequence[str]

The fields ofmodel to change, spelled as the Model properties (e.g. "friendly_name").

retryOptional[google.api_core.retry.Retry]

A description of how to retry the API call.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.model.ModelThe model resource returned from the API call.

update_routine

update_routine(routine,fields,retry=<google.api_core.retry.Retryobject>,timeout=None)
Parameters
NameDescription
routinegoogle.cloud.bigquery.routine.Routine

The routine to update.

fieldsSequence[str]

The fields ofroutine to change, spelled as theRoutine properties (e.g.type_).

retryOptional[google.api_core.retry.Retry]

A description of how to retry the API call.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.routine.RoutineThe routine resource returned from the API call.

update_table

update_table(table,fields,retry=<google.api_core.retry.Retryobject>,timeout=None)

Change some fields of a table.

Usefields to specify which fields to update. At least one fieldmust be provided. If a field is listed infields and isNoneintable, the field value will be deleted.

Iftable.etag is notNone, the update will only succeed ifthe table on the server has the same ETag. Thus reading a table withget_table, changing its fields, and then passing it toupdate_table will ensure that the changes will only be saved ifno modifications to the table occurred since the read.

Parameters
NameDescription
tablegoogle.cloud.bigquery.table.Table

The table to update.

fieldsSequence[str]

The fields oftable to change, spelled as the Table properties (e.g. "friendly_name").

retryOptional[google.api_core.retry.Retry]

A description of how to retry the API call.

timeoutOptional[float]

The number of seconds to wait for the underlying HTTP transport before usingretry.

Returns
TypeDescription
google.cloud.bigquery.table.TableThe table resource returned from the API call.

__init__

__init__(project=None,credentials=None,_http=None,location=None,default_query_job_config=None,client_info=None,client_options=None,)

Initialize self. See help(type(self)) for accurate signature.

get_iam_policy

get_iam_policy(table,requested_policy_version=1,retry=<google.api_core.retry.Retryobject>,timeout=None)

API documentation forbigquery.client.Client.get_iam_policy method.

set_iam_policy

set_iam_policy(table,policy,updateMask=None,retry=<google.api_core.retry.Retryobject>,timeout=None)

API documentation forbigquery.client.Client.set_iam_policy method.

test_iam_permissions

test_iam_permissions(table,permissions,retry=<google.api_core.retry.Retryobject>,timeout=None)

API documentation forbigquery.client.Client.test_iam_permissions method.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-16 UTC.