jobs

Creates, updates, deletes, gets or lists a jobs resource.

Overview

Name	jobs
Type	Resource
Id	google.bigquery.jobs

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
id	string	Output only. Opaque ID field of the job.
configuration	object	Required. Describes the job configuration. (id: JobConfiguration)
etag	string	Output only. A hash of this resource.
jobCreationReason	object	Output only. The reason why a Job was created. (id: JobCreationReason)
jobReference	object	Optional. Reference describing the unique-per-user name of the job. (id: JobReference)
kind	string	Output only. The type of the resource. (default: bigquery#job)
principal_subject	string	Output only. [Full-projection-only] String representation of identity of requesting party. Populated for both first- and third-party identities. Only present for APIs that support third-party identities.
selfLink	string	Output only. A URL that can be used to access the resource again.
statistics	object	Output only. Information about the job, including starting time and ending time of the job. (id: JobStatistics)
status	object	Output only. The status of this job. Examine this value when polling an asynchronous job to see if the job is complete. (id: JobStatus)
user_email	string	Output only. Email address of the user who ran the job.

list

Successful response

Name	Datatype	Description
id	string	Unique opaque ID of the job.
configuration	object	Required. Describes the job configuration. (id: JobConfiguration)
errorResult	object	Error details. (id: ErrorProto)
jobReference	object	Unique opaque ID of the job. (id: JobReference)
kind	string	The resource type.
principal_subject	string	[Full-projection-only] String representation of identity of requesting party. Populated for both first- and third-party identities. Only present for APIs that support third-party identities.
state	string	Running state of the job. When the state is DONE, errorResult can be checked to determine whether the job succeeded or failed.
statistics	object	Output only. Information about the job, including starting time and ending time of the job. (id: JobStatistics)
status	object	[Full-projection-only] Describes the status of this job. (id: JobStatus)
user_email	string	[Full-projection-only] Email address of the user who ran the job.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectId, +jobId	location	Returns information about a specific job. Job information is available for a six month period after creation. Requires that you're the person who ran the job, or have the Is Owner project role.
list	select	projectId	allUsers, maxCreationTime, maxResults, minCreationTime, pageToken, parentJobId, projection, stateFilter	Lists all jobs that you started in the specified project. Job information is available for a six month period after creation. The job list is sorted in reverse chronological order, by job creation time. Requires the Can View project role, or the Is Owner project role if you set the allUsers property.
insert	insert	projectId		Starts a new asynchronous job. This API has two different kinds of endpoint URIs, as this method supports a variety of use cases. * The Metadata URI is used for most interactions, as it accepts the job configuration directly. * The Upload URI is ONLY for the case when you're sending both a load job configuration and a data stream together. In this case, the Upload URI accepts the job configuration and the data as two distinct multipart MIME parts.
delete	delete	projectId, +jobId	location	Requests the deletion of the metadata of a job. This call returns when the job's metadata is deleted.
cancel	exec	projectId, +jobId	location	Requests that a job be cancelled. This call will return immediately, and the client will need to poll for the job status to see if the cancel completed successfully. Cancelled jobs may still incur costs.
query	exec	projectId		Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
+jobId	string
projectId	string
allUsers	boolean
location	string
maxCreationTime	string (uint64)
maxResults	integer (uint32)
minCreationTime	string (uint64)
pageToken	string
parentJobId	string
projection	string
stateFilter	string

SELECT examples

get

Returns information about a specific job. Job information is available for a six month period after creation. Requires that you're the person who ran the job, or have the Is Owner project role.

SELECT
id,
configuration,
etag,
jobCreationReason,
jobReference,
kind,
principal_subject,
selfLink,
statistics,
status,
user_email
FROM google.bigquery.jobs
WHERE projectId = '{{ projectId }}' -- required
AND +jobId = '{{ +jobId }}' -- required
AND location = '{{ location }}';

list

Lists all jobs that you started in the specified project. Job information is available for a six month period after creation. The job list is sorted in reverse chronological order, by job creation time. Requires the Can View project role, or the Is Owner project role if you set the allUsers property.

SELECT
id,
configuration,
errorResult,
jobReference,
kind,
principal_subject,
state,
statistics,
status,
user_email
FROM google.bigquery.jobs
WHERE projectId = '{{ projectId }}' -- required
AND allUsers = '{{ allUsers }}'
AND maxCreationTime = '{{ maxCreationTime }}'
AND maxResults = '{{ maxResults }}'
AND minCreationTime = '{{ minCreationTime }}'
AND pageToken = '{{ pageToken }}'
AND parentJobId = '{{ parentJobId }}'
AND projection = '{{ projection }}'
AND stateFilter = '{{ stateFilter }}';

INSERT examples

insert

Starts a new asynchronous job. This API has two different kinds of endpoint URIs, as this method supports a variety of use cases. * The Metadata URI is used for most interactions, as it accepts the job configuration directly. * The Upload URI is ONLY for the case when you're sending both a load job configuration and a data stream together. In this case, the Upload URI accepts the job configuration and the data as two distinct multipart MIME parts.

INSERT INTO google.bigquery.jobs (
data__configuration,
data__jobReference,
projectId
)
SELECT 
'{{ configuration }}',
'{{ jobReference }}',
'{{ projectId }}'
RETURNING
id,
configuration,
etag,
jobCreationReason,
jobReference,
kind,
principal_subject,
selfLink,
statistics,
status,
user_email
;

Manifest

# Description fields are for documentation purposes
- name: jobs
  props:
    - name: projectId
      value: string
      description: Required parameter for the jobs resource.
    - name: configuration
      value: object
      description: >
        Required. Describes the job configuration.
        
    - name: jobReference
      value: object
      description: >
        Optional. Reference describing the unique-per-user name of the job.
        

DELETE examples

delete

Requests the deletion of the metadata of a job. This call returns when the job's metadata is deleted.

DELETE FROM google.bigquery.jobs
WHERE projectId = '{{ projectId }}' --required
AND +jobId = '{{ +jobId }}' --required
AND location = '{{ location }}';

Lifecycle Methods

cancel

Requests that a job be cancelled. This call will return immediately, and the client will need to poll for the job status to see if the cancel completed successfully. Cancelled jobs may still incur costs.

EXEC google.bigquery.jobs.cancel 
@projectId='{{ projectId }}' --required, 
@+jobId='{{ +jobId }}' --required, 
@location='{{ location }}';

query

Runs a BigQuery SQL query synchronously and returns query results if the query completes within a specified timeout.

EXEC google.bigquery.jobs.query 
@projectId='{{ projectId }}' --required 
@@json=
'{
"connectionProperties": "{{ connectionProperties }}", 
"continuous": {{ continuous }}, 
"createSession": {{ createSession }}, 
"defaultDataset": "{{ defaultDataset }}", 
"destinationEncryptionConfiguration": "{{ destinationEncryptionConfiguration }}", 
"dryRun": {{ dryRun }}, 
"formatOptions": "{{ formatOptions }}", 
"jobCreationMode": "{{ jobCreationMode }}", 
"jobTimeoutMs": "{{ jobTimeoutMs }}", 
"kind": "{{ kind }}", 
"labels": "{{ labels }}", 
"location": "{{ location }}", 
"maxResults": {{ maxResults }}, 
"maximumBytesBilled": "{{ maximumBytesBilled }}", 
"parameterMode": "{{ parameterMode }}", 
"preserveNulls": {{ preserveNulls }}, 
"query": "{{ query }}", 
"queryParameters": "{{ queryParameters }}", 
"requestId": "{{ requestId }}", 
"reservation": "{{ reservation }}", 
"timeoutMs": {{ timeoutMs }}, 
"useLegacySql": {{ useLegacySql }}, 
"useQueryCache": {{ useQueryCache }}, 
"writeIncrementalResults": {{ writeIncrementalResults }}
}';