BigQuery API - Class Google::Cloud::Bigquery::Job (v1.42.0)

Reference documentation and code samples for the BigQuery API class Google::Cloud::Bigquery::Job.

Job

Represents a generic Job that may be performed on a Table.

The subclasses of Job represent the specific BigQuery job types: CopyJob, ExtractJob, LoadJob, and QueryJob.

A job instance is created when you call Project#query_job, Dataset#query_job, Table#copy_job, Table#extract_job, Table#load_job.

Inherits

Object

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

job = bigquery.query_job "SELECT COUNT(word) as count FROM " \
                         "`bigquery-public-data.samples.shakespeare`"

job.wait_until_done!

if job.failed?
  puts job.error
else
  puts job.data.first
end

Methods

#cancel

def cancel()

Cancels the job.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

query = "SELECT COUNT(word) as count FROM " \
        "`bigquery-public-data.samples.shakespeare`"

job = bigquery.query_job query

job.cancel

#config

def config()

Alias Of: #configuration

The configuration for the job. Returns a hash.

#configuration

def configuration()

Aliases

#config

The configuration for the job. Returns a hash.

#created_at

def created_at() -> Time, nil

The time when the job was created.

Returns

(Time, nil) — The creation time from the job statistics.

#delete

def delete() -> Boolean

Requests that a job is deleted. This call will return when the job is deleted.

Returns

(Boolean) — Returns true if the job was deleted.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

job = bigquery.job "my_job"

job.delete

#done?

def done?() -> Boolean

Checks if the job's state is DONE. When true, the job has stopped running. However, a DONE state does not mean that the job completed successfully. Use #failed? to detect if an error occurred or if the job was successful.

Returns

(Boolean) — true when DONE, false otherwise.

#ended_at

def ended_at() -> Time, nil

The time when the job ended. This field is present when the job's state is DONE.

Returns

(Time, nil) — The end time from the job statistics.

#error

def error() -> Hash, nil

The last error for the job, if any errors have occurred. Returns a hash.

Returns

(Hash, nil) — Returns a hash containing reason and message keys:

{ "reason"=>"notFound", "message"=>"Not found: Table bigquery-public-data:samples.BAD_ID" }

#errors

def errors() -> Array<Hash>, nil

The errors for the job, if any errors have occurred. Returns an array of hash objects. See #error.

Returns

(Array<Hash>, nil) — Returns an array of hashes containing reason and message keys:

{ "reason"=>"notFound", "message"=>"Not found: Table bigquery-public-data:samples.BAD_ID" }

#failed?

def failed?() -> Boolean

Checks if an error is present. Use #error to access the error object.

Returns

(Boolean) — true when there is an error, false otherwise.

#job_id

def job_id() -> String

The ID of the job.

Returns

(String) — The ID must contain only letters ([A-Za-z]), numbers ([0-9]), underscores (_), or dashes (-). The maximum length is 1,024 characters.

#labels

def labels() -> Hash

A hash of user-provided labels associated with this job. Labels can be provided when the job is created, and used to organize and group jobs.

The returned hash is frozen and changes are not allowed. Use CopyJob::Updater#labels= or ExtractJob::Updater#labels= or LoadJob::Updater#labels= or QueryJob::Updater#labels= to replace the entire hash.

Returns

(Hash) — The job labels.

#location

def location() -> String

The geographic location where the job runs.

Returns

(String) — A geographic location, such as "US", "EU" or "asia-northeast1".

#num_child_jobs

def num_child_jobs() -> Integer

The number of child jobs executed.

Returns

(Integer) — The number of child jobs executed.

#parent_job_id

def parent_job_id() -> String, nil

If this is a child job, the id of the parent.

Returns

(String, nil) — The ID of the parent job, or nil if not a child job.

#pending?

def pending?() -> Boolean

Checks if the job's state is PENDING.

Returns

(Boolean) — true when PENDING, false otherwise.

#project_id

def project_id() -> String

The ID of the project containing the job.

Returns

(String) — The project ID.

#refresh!

def refresh!()

Alias Of: #reload!

Reloads the job with current data from the BigQuery service.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

query = "SELECT COUNT(word) as count FROM " \
        "`bigquery-public-data.samples.shakespeare`"

job = bigquery.query_job query

job.done?
job.reload!
job.done? #=> true

#reload!

def reload!()

Aliases

#refresh!

Reloads the job with current data from the BigQuery service.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

query = "SELECT COUNT(word) as count FROM " \
        "`bigquery-public-data.samples.shakespeare`"

job = bigquery.query_job query

job.done?
job.reload!
job.done? #=> true

#rerun!

def rerun!()

Created a new job with the current configuration.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

query = "SELECT COUNT(word) as count FROM " \
        "`bigquery-public-data.samples.shakespeare`"

job = bigquery.query_job query

job.wait_until_done!
job.rerun!

#reservation_usage

def reservation_usage() -> Array<Google::Cloud::Bigquery::Job::ReservationUsage>, nil

An array containing the job resource usage breakdown by reservation, if present. Reservation usage statistics are only reported for jobs that are executed within reservations. On-demand jobs do not report this data.

Returns

(Array<Google::Cloud::Bigquery::Job::ReservationUsage>, nil) — The reservation usage, if present.

#running?

def running?() -> Boolean

Checks if the job's state is RUNNING.

Returns

(Boolean) — true when RUNNING, false otherwise.

#script_statistics

def script_statistics() -> Google::Cloud::Bigquery::Job::ScriptStatistics, nil

The statistics including stack frames for a child job of a script.

Returns

(Google::Cloud::Bigquery::Job::ScriptStatistics, nil) — The script statistics, or nil if the job is not a child job.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new

multi_statement_sql = <<~SQL
  -- Declare a variable to hold names as an array.
  DECLARE top_names ARRAY<STRING>;
  -- Build an array of the top 100 names from the year 2017.
  SET top_names = (
  SELECT ARRAY_AGG(name ORDER BY number DESC LIMIT 100)
  FROM `bigquery-public-data.usa_names.usa_1910_current`
  WHERE year = 2017
  );
  -- Which names appear as words in Shakespeare's plays?
  SELECT
  name AS shakespeare_name
  FROM UNNEST(top_names) AS name
  WHERE name IN (
  SELECT word
  FROM `bigquery-public-data.samples.shakespeare`
  );
SQL

job = bigquery.query_job multi_statement_sql

job.wait_until_done!

child_jobs = bigquery.jobs parent_job: job

child_jobs.each do |child_job|
  script_statistics = child_job.script_statistics
  puts script_statistics.evaluation_kind
  script_statistics.stack_frames.each do |stack_frame|
    puts stack_frame.text
  end
end

#session_id

def session_id() -> String, nil

The ID of the session if this job is part of one. See the create_session param in Project#query_job and Dataset#query_job.

Returns

(String, nil) — The session ID, or nil if not associated with a session.

#started_at

def started_at() -> Time, nil

The time when the job was started. This field is present after the job's state changes from PENDING to either RUNNING or DONE.

Returns

(Time, nil) — The start time from the job statistics.

#state

def state() -> String

The current state of the job. A DONE state does not mean that the job completed successfully. Use #failed? to discover if an error occurred or if the job was successful.

Returns

(String) — The state code. The possible values are PENDING, RUNNING, and DONE.

#statistics

def statistics() -> Hash

Aliases

#stats

The statistics for the job. Returns a hash.

Returns

(Hash) — The job statistics.

#stats

def stats() -> Hash

Alias Of: #statistics

The statistics for the job. Returns a hash.

Returns

(Hash) — The job statistics.

#status

def status() -> Hash

The job's status. Returns a hash. The values contained in the hash are also exposed by #state, #error, and #errors.

Returns

(Hash) — The job status.

#transaction_id

def transaction_id() -> String, nil

The ID of a multi-statement transaction.

Returns

(String, nil) — The transaction ID, or nil if not associated with a transaction.

#user_email

def user_email() -> String

The email address of the user who ran the job.

Returns

(String) — The email address.

#wait_until_done!

def wait_until_done!()

Refreshes the job until the job is DONE. The delay between refreshes starts at 5 seconds and increases exponentially to a maximum of 60 seconds.

Example

require "google/cloud/bigquery"

bigquery = Google::Cloud::Bigquery.new
dataset = bigquery.dataset "my_dataset"
table = dataset.table "my_table"

extract_job = table.extract_job "gs://my-bucket/file-name.json",
                                format: "json"
extract_job.wait_until_done!
extract_job.done? #=> true