Version 3.1.0

• 3.25.0 (latest)
• 3.24.0
• 3.23.1
• 3.22.0
• 3.21.0
• 3.20.1
• 3.19.0
• 3.18.0
• 3.17.2
• 3.16.0
• 3.15.0
• 3.14.1
• 3.13.0
• 3.12.0
• 3.11.4
• 3.4.0
• 3.3.6
• 3.2.0
• 3.1.0
• 3.0.1
• 2.34.4
• 2.33.0
• 2.32.0
• 2.31.0
• 2.30.1
• 2.29.0
• 2.28.1
• 2.27.1
• 2.26.0
• 2.25.2
• 2.24.1
• 2.23.3
• 2.22.1
• 2.21.0
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.0
• 2.16.1
• 2.15.0
• 2.14.0
• 2.13.1
• 2.12.0
• 2.11.0
• 2.10.0
• 2.9.0
• 2.8.0
• 2.7.0
• 2.6.2
• 2.5.0
• 2.4.0
• 2.3.1
• 2.2.0
• 2.1.0
• 2.0.0
• 1.28.2
• 1.27.2
• 1.26.1
• 1.25.0
• 1.24.0
• 1.23.1
• 1.22.0
• 1.21.0
• 1.20.0
• 1.19.0
• 1.18.0
• 1.17.0
• 1.16.0

Common Job Resource Classes

Base classes and helpers for job classes.

class google.cloud.bigquery.job.base.ReservationUsage(name, slot_ms)

Job resource usage for a reservation.

Create new instance of ReservationUsage(name, slot_ms)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

name()

Reservation name or “unreserved” for on-demand resources usage.

slot_ms()

Total slot milliseconds used by the reservation for a particular job.

class google.cloud.bigquery.job.base.ScriptStackFrame(resource)

Stack frame showing the line/column/procedure name where the current evaluation happened.

• Parameters

  resource (Map[str, **Any]) – JSON representation of object.

property end_column()

One-based end column.

• Type

  int

property end_line()

One-based end line.

• Type

  int

property procedure_id()

Name of the active procedure.

Omitted if in a top-level script.

• Type

  Optional[str]

property start_column()

One-based start column.

• Type

  int

property start_line()

One-based start line.

• Type

  int

property text()

Text of the current statement/expression.

• Type

  str

class google.cloud.bigquery.job.base.ScriptStatistics(resource)

Statistics for a child job of a script.

• Parameters

  resource (Map[str, **Any]) – JSON representation of object.

property evaluation_kind(: Optional[str )

Indicates the type of child job.

Possible values include STATEMENT and EXPRESSION.

• Type

  str

property stack_frames(: Sequence[google.cloud.bigquery.job.base.ScriptStackFrame )

Stack trace where the current evaluation happened.

Shows line/column/procedure name of each frame on the stack at the point where the current evaluation happened.

The leaf frame is first, the primary script is last.

class google.cloud.bigquery.job.base.SessionInfo(resource)

[Preview] Information of the session if this job is part of one.

Versionadded: New in version 2.29.0.

• Parameters

  resource (Map[str, **Any]) – JSON representation of object.

property session_id(: Optional[str )

The ID of the session.

class google.cloud.bigquery.job.base.TransactionInfo(transaction_id: str)

[Alpha] Information of a multi-statement transaction.

https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#TransactionInfo

Versionadded: New in version 2.24.0.

Create new instance of TransactionInfo(transaction_id,)

count(value, /)

Return number of occurrences of value.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

transaction_id(: [str](https://python.readthedocs.io/en/latest/library/stdtypes.html#str )

Output only. ID of the transaction.

class google.cloud.bigquery.job.base.UnknownJob(job_id, client)

A job whose type cannot be determined.

add_done_callback(fn)

Add a callback to be executed when the operation is complete.

If the operation is not already complete, this will start a helper thread to poll for the status of the operation in the background.

• Parameters

  fn (Callable[Future]) – The callback to execute when the operation is complete.

cancel(client=None, retry: retries.Retry = <google.api_core.retry.Retry object>, timeout: float = None)

API call: cancel job via a POST request

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

• Parameters

  • client (Optional[google.cloud.bigquery.client.Client]) – the client to use. If not passed, falls back to the client stored on the current dataset.

  • retry (Optional[google.api_core.retry.Retry]) – How to retry the RPC.

  • timeout (Optional[float]) – The number of seconds to wait for the underlying HTTP transport before using retry

• Returns

  Boolean indicating that the cancel request was sent.

• Return type

  bool

cancelled()

Check if the job has been cancelled.

This always returns False. It’s not possible to check if a job was cancelled in the API. This method is here to satisfy the interface for google.api_core.future.Future.

• Returns

  False

• Return type

  bool

property created()

Datetime at which the job was created.

• Returns

  the creation time (None until set from the server).

• Return type

  Optional[datetime.datetime]

done(retry: retries.Retry = <google.api_core.retry.Retry object>, timeout: float = None, reload: bool = True)

Checks if the job is complete.

• Parameters

  • retry (Optional[google.api_core.retry.Retry]) – How to retry the RPC. If the job state is DONE, retrying is aborted early, as the job will not change anymore.

  • timeout (Optional[float]) – The number of seconds to wait for the underlying HTTP transport before using retry.

  • reload (Optional[bool]) – If True, make an API call to refresh the job state of unfinished jobs before checking. Default True.

• Returns

  True if the job is complete, False otherwise.

• Return type

  bool

property ended()

Datetime at which the job finished.

• Returns

  the end time (None until set from the server).

• Return type

  Optional[datetime.datetime]

property error_result()

Error information about the job as a whole.

• Returns

  the error information (None until set from the server).

• Return type

  Optional[Mapping]

property errors()

Information about individual errors generated by the job.

• Returns

  the error information (None until set from the server).

• Return type

  Optional[List[Mapping]]

property etag()

ETag for the job resource.

• Returns

  the ETag (None until set from the server).

• Return type

  Optional[str]

exception(timeout=None)

Get the exception from the operation, blocking if necessary.

• Parameters

  timeout (int) – How long to wait for the operation to complete. If None, wait indefinitely.

• Returns

  The operation’s

    error.
  

• Return type

  Optional[google.api_core.GoogleAPICallError]

exists(client=None, retry: retries.Retry = <google.api_core.retry.Retry object>, timeout: float = None)

API call: test for the existence of the job via a GET request

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

• Parameters

  • client (Optional[google.cloud.bigquery.client.Client]) – the client to use. If not passed, falls back to the client stored on the current dataset.

  • retry (Optional[google.api_core.retry.Retry]) – How to retry the RPC.

  • timeout (Optional[float]) – The number of seconds to wait for the underlying HTTP transport before using retry.

• Returns

  Boolean indicating existence of the job.

• Return type

  bool

classmethod from_api_repr(resource: dict, client)

Construct an UnknownJob from the JSON representation.

• Parameters

  • resource (Dict) – JSON representation of a job.

  • client (google.cloud.bigquery.client.Client) – Client connected to BigQuery API.

• Returns

  Job corresponding to the resource.

• Return type

  UnknownJob

property job_id()

ID of the job.

• Type

  str

property job_type()

Type of job.

• Returns

  one of ‘load’, ‘copy’, ‘extract’, ‘query’.

• Return type

  str

property labels()

Labels for the job.

• Type

  Dict[str, str]

property location()

Location where the job runs.

• Type

  str

property num_child_jobs()

The number of child jobs executed.

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobStatistics.FIELDS.num_child_jobs

• Returns

  int

property parent_job_id()

Return the ID of the parent job.

See: https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobStatistics.FIELDS.parent_job_id

• Returns

  parent job id.

• Return type

  Optional[str]

property path()

URL path for the job’s APIs.

• Returns

  the path based on project and job ID.

• Return type

  str

property project()

Project bound to the job.

• Returns

  the project (derived from the client).

• Return type

  str

reload(client=None, retry: retries.Retry = <google.api_core.retry.Retry object>, timeout: float = None)

API call: refresh job properties via a GET request.

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

• Parameters

  • client (Optional[google.cloud.bigquery.client.Client]) – the client to use. If not passed, falls back to the client stored on the current dataset.

  • retry (Optional[google.api_core.retry.Retry]) – How to retry the RPC.

  • timeout (Optional[float]) – The number of seconds to wait for the underlying HTTP transport before using retry.

property reservation_usage()

Job resource usage breakdown by reservation.

• Returns

  Reservation usage stats. Can be empty if not set from the server.

• Return type

  List[google.cloud.bigquery.job.ReservationUsage]

result(retry: retries.Retry = <google.api_core.retry.Retry object>, timeout: float = None)

Start the job and wait for it to complete and get the result.

• Parameters

  • retry (Optional[google.api_core.retry.Retry]) – How to retry the RPC. If the job state is DONE, retrying is aborted early, as the job will not change anymore.

  • timeout (Optional[float]) – The number of seconds to wait for the underlying HTTP transport before using retry. If multiple requests are made under the hood, timeout applies to each individual request.

• Returns

  This instance.

• Return type

  _AsyncJob

• Raises

  • google.cloud.exceptions.GoogleAPICallError – if the job failed.

  • concurrent.futures.TimeoutError – if the job did not complete in the given timeout.

running()

True if the operation is currently running.

property script_statistics(: Optional[google.cloud.bigquery.job.base.ScriptStatistics )

Statistics for a child job of a script.

property self_link()

URL for the job resource.

• Returns

  the URL (None until set from the server).

• Return type

  Optional[str]

property session_info(: Optional[google.cloud.bigquery.job.base.SessionInfo )

[Preview] Information of the session if this job is part of one.

Versionadded: New in version 2.29.0.

set_exception(exception)

Set the Future’s exception.

set_result(result)

Set the Future’s result.

property started()

Datetime at which the job was started.

• Returns

  the start time (None until set from the server).

• Return type

  Optional[datetime.datetime]

property state()

Status of the job.

• Returns

  the state (None until set from the server).

• Return type

  Optional[str]

to_api_repr()

Generate a resource for the job.

property transaction_info(: Optional[google.cloud.bigquery.job.base.TransactionInfo )

Information of the multi-statement transaction if this job is part of one.

Since a scripting query job can execute multiple transactions, this property is only expected on child jobs. Use the google.cloud.bigquery.client.Client.list_jobs() method with the parent_job parameter to iterate over child jobs.

Versionadded: New in version 2.24.0.

property user_email()

E-mail address of user who submitted the job.

• Returns

  the URL (None until set from the server).

• Return type

  Optional[str]