Create a job

Run a BigQuery job (query, load, extract, or copy) in a specified location with additional configuration.

Explore further

For detailed documentation that includes this code sample, see the following:

Code sample

C#

Before trying this sample, follow the C# setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery C# API reference documentation.

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


using Google.Cloud.BigQuery.V2;
using System;
using System.Collections.Generic;

public class BigQueryCreateJob
{
    public BigQueryJob CreateJob(string projectId = "your-project-id")
    {
        string query = @"
            SELECT country_name from `bigquery-public-data.utility_us.country_code_iso";

        // Initialize client that will be used to send requests.
        BigQueryClient client = BigQueryClient.Create(projectId);

        QueryOptions queryOptions = new QueryOptions
        {
            JobLocation = "us",
            JobIdPrefix = "code_sample_",
            Labels = new Dictionary<string, string>
            {
                ["example-label"] = "example-value"
            },
            MaximumBytesBilled = 1000000
        };

        BigQueryJob queryJob = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: queryOptions);

        Console.WriteLine($"Started job: {queryJob.Reference.JobId}");
        return queryJob;
    }
}

Go

Before trying this sample, follow the Go setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Go API reference documentation.

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

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"

	"github.com/google/uuid"
)

// createJob demonstrates running an arbitrary SQL statement as a query job.
func createJob(projectID, sql string) error {
	// sql := "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`:"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	// Demonstrate adding a label to the job.
	q := client.Query(sql)
	q.Labels = map[string]string{"example-label": "example-value"}

	// The library will create job IDs for you automatically, but this can be overridden by
	// setting the Job ID explicitly.  Job IDs are unique within a project and cannot be
	// reused.
	q.JobID = fmt.Sprintf("my_job_prefix_%s", uuid.New().String())

	// Start job execution.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

Java

Before trying this sample, follow the Java setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Java API reference documentation.

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.common.collect.ImmutableMap;
import java.util.UUID;

// Sample to create a job
public class CreateJob {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String query = "SELECT country_name from `bigquery-public-data.utility_us.country_code_iso`";
    createJob(query);
  }

  public static void createJob(String query) {
    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.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Specify a job configuration to set optional job resource properties.
      QueryJobConfiguration queryConfig =
          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.
      String jobName = "jobId_" + UUID.randomUUID().toString();
      JobId jobId = JobId.newBuilder().setLocation("us").setJob(jobName).build();

      // Create a job with job ID
      bigquery.create(JobInfo.of(jobId, queryConfig));

      // Get a job that was just created
      Job job = 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 (BigQueryException e) {
      System.out.print("Job was not created. \n" + e.toString());
    }
  }
}

Node.js

Before trying this sample, follow the Node.js setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Node.js API reference documentation.

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function createJob() {
  // Run a BigQuery query job.

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/Job
  const options = {
    // Specify a job configuration to set optional job resource properties.
    configuration: {
      query: {
        query: `SELECT country_name 
              FROM \`bigquery-public-data.utility_us.country_code_iso\` 
              LIMIT 10`,
        useLegacySql: false,
      },
      labels: {'example-label': 'example-value'},
    },
  };

  // Make API request.
  const response = await bigquery.createJob(options);
  const job = response[0];

  // Wait for the query to finish
  const [rows] = await job.getQueryResults(job);

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Python

Before trying this sample, follow the Python setup instructions in the BigQuery quickstart using client libraries. For more information, see the BigQuery Python API reference documentation.

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

query_job = client.create_job(
    # Specify a job configuration, providing a query
    # and/or optional job resource properties, as needed.
    # The job instance can be a LoadJob, CopyJob, ExtractJob, QueryJob
    # Here, we demonstrate a "query" job.
    # References:
    #     https://googleapis.dev/python/bigquery/latest/generated/google.cloud.bigquery.client.Client.html#google.cloud.bigquery.client.Client.create_job
    #     https://cloud.google.com/bigquery/docs/reference/rest/v2/Job
    #
    # Example use cases for .create_job() include:
    #    * to retry failed jobs
    #    * to generate jobs with an experimental API property that hasn't
    #      been added to one of the manually written job configuration
    #      classes yet
    #
    # NOTE: unless it is necessary to create a job in this way, the
    # preferred approach is to use one of the dedicated API calls:
    #   client.query()
    #   client.extract_table()
    #   client.copy_table()
    #   client.load_table_file(), client.load_table_from_dataframe(), etc
    job_config={
        "query": {
            "query": """
                     SELECT country_name
                     FROM `bigquery-public-data.utility_us.country_code_iso`
                     LIMIT 5
                     """,
        },
        "labels": {"example-label": "example-value"},
        "maximum_bytes_billed": 10000000,
    }
)  # Make an API request.

print(f"Started job: {query_job.job_id}")

What's next

To search and filter code samples for other Google Cloud products, see the Google Cloud sample browser.