Running jobs programmatically

To run a BigQuery job programmatically using the REST API orclient libraries, you:

  1. Call thejobs.insertmethod.
  2. Periodically request the job resource and examine the status property tolearn when the job is complete.
  3. Check to see whether the job finished successfully.

Before you begin

Grant Identity and Access Management (IAM) roles that give users the necessary permissions to perform each task in this document.

Required permissions

To run a BigQuery job, you need thebigquery.jobs.create IAM permission.

Each of the following predefined IAM roles includes the permissions that you need in order to run a job:

  • roles/bigquery.user
  • roles/bigquery.jobUser
  • roles/bigquery.admin

Additionally, when you create a job, you are automatically granted the following permissions for that job:

  • bigquery.jobs.get
  • bigquery.jobs.update

For more information on IAM roles and permissions inBigQuery, seePredefined roles and permissions.

Running jobs

To run a job programmatically:

  1. Start the job by calling thejobs.insert method. When you call thejobs.insert method, include ajob resourcerepresentation.

  2. In theconfigurationsection of the job resource, include a child property that specifies the jobtype —load,query,extract, orcopy.

  3. After calling thejobs.insert method, check the job status by callingjobs.get with the job ID and location, and check thestatus.statevalue to learn the job status. Whenstatus.state isDONE, the job hasstopped running; however, aDONE status does not mean that the jobcompleted successfully, only that it is no longer running.

    Note: There are some wrapper functions that manage job status requests foryou. For example, runningjobs.query creates a job and periodically pollsforDONE status for a specified period of time.

  4. Check for job success. If the job has anerrorResult property, the job hasfailed. Thestatus.errorResult property holds information describing what wentwrong in a failed job. Ifstatus.errorResult is absent, the job finishedsuccessfully, although there might have been some nonfatal errors, such asproblems importing a few rows in a load job. Nonfatal errors are returned inthe job'sstatus.errors list.

Running jobs using client libraries

To create and run a job using the Cloud Client Libraries forBigQuery:

C#

Before trying this sample, follow theC# setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryC# API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

usingGoogle.Cloud.BigQuery.V2;usingSystem;usingSystem.Collections.Generic;publicclassBigQueryCreateJob{publicBigQueryJobCreateJob(stringprojectId="your-project-id"){stringquery=@"            SELECT country_name from `bigquery-public-data.utility_us.country_code_iso";// Initialize client that will be used to send requests.BigQueryClientclient=BigQueryClient.Create(projectId);QueryOptionsqueryOptions=newQueryOptions{JobLocation="us",JobIdPrefix="code_sample_",Labels=newDictionary<string,string>{["example-label"]="example-value"},MaximumBytesBilled=1000000};BigQueryJobqueryJob=client.CreateQueryJob(sql:query,parameters:null,options:queryOptions);Console.WriteLine($"Started job: {queryJob.Reference.JobId}");returnqueryJob;}}

Java

Before trying this sample, follow theJava setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryJava API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

importcom.google.cloud.bigquery.BigQuery;importcom.google.cloud.bigquery.BigQueryException;importcom.google.cloud.bigquery.BigQueryOptions;importcom.google.cloud.bigquery.Job;importcom.google.cloud.bigquery.JobId;importcom.google.cloud.bigquery.JobInfo;importcom.google.cloud.bigquery.QueryJobConfiguration;importcom.google.common.collect.ImmutableMap;importjava.util.UUID;// Sample to create a jobpublicclassCreateJob{publicstaticvoidmain(String[]args){// TODO(developer): Replace these variables before running the sample.Stringquery="SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`";createJob(query);}publicstaticvoidcreateJob(Stringquery){try{// Initialize client that will be used to send requests. This client only needs to be created// once, and can be reused for multiple requests.BigQuerybigquery=BigQueryOptions.getDefaultInstance().getService();// Specify a job configuration to set optional job resource properties.QueryJobConfigurationqueryConfig=QueryJobConfiguration.newBuilder(query).setLabels(ImmutableMap.of("example-label","example-value")).build();// The location and job name are optional,// if both are not specified then client will auto-create.StringjobName="jobId_"+UUID.randomUUID().toString();JobIdjobId=JobId.newBuilder().setLocation("us").setJob(jobName).build();// Create a job with job IDbigquery.create(JobInfo.of(jobId,queryConfig));// Get a job that was just createdJobjob=bigquery.getJob(jobId);if(job.getJobId().getJob().equals(jobId.getJob())){System.out.print("Job created successfully."+job.getJobId().getJob());}else{System.out.print("Job was not created");}}catch(BigQueryExceptione){System.out.print("Job was not created. \n"+e.toString());}}}

Python

Before trying this sample, follow thePython setup instructions in theBigQuery quickstart using client libraries. For more information, see theBigQueryPython API reference documentation.

To authenticate to BigQuery, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

fromgoogle.cloudimportbigquery# Construct a BigQuery client object.client=bigquery.Client()query_job=client.query("SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`",# Explicitly force job execution to be routed to a specific processing# location.location="US",# Specify a job configuration to set optional job resource properties.job_config=bigquery.QueryJobConfig(labels={"example-label":"example-value"},maximum_bytes_billed=1000000),# The client libraries automatically generate a job ID. Override the# generated ID with either the job_id_prefix or job_id parameters.job_id_prefix="code_sample_",)# Make an API request.print("Started job:{}".format(query_job.job_id))

Adding job labels

Labels can be added to query jobs through the command line by using thebq command-line tool's--label flag. The bq tool supports addinglabels only to query jobs.

You can also add a label to a job when it's submitted through the API by specifyingthelabels property in the job configuration when you call thejobs.insert method. The APIcan be used to add labels to any job type.

You cannot add labels to or update labels on pending, running, or completedjobs.

When you add a label to a job, the label is included in your billing data.

For more information, seeAdding job labels.

What's next

  • SeeRunning queries for acode example that starts and polls a query job.
  • For more information on creating a job resource representation, see theJobs overview page in the APIreference.

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 2026-02-18 UTC.