Google Cloud Platform
BigQuery

BigQuery API Quickstart

This page provides a short exercise in building a simple command-line application (in Java, Python, C#, PHP, or Ruby) with the Google BigQuery API. This simple application will run a query on one of the available Sample Datasets and display the result.

  1. Prerequisites
  2. Create an Authorized BigQuery Service Object
  3. Running Queries
  4. Next Steps
  5. Complete Source Code

Prerequisites

  1. An understanding of basic BigQuery concepts and terminology

    See what is BigQuery for a list of basic terms and concepts to become familiar with, such as jobs and projects.

  2. Ability to write and run a simple application in Java, Python, C#, PHP, or Ruby.

    The BigQuery service provides a REST-based API that can be programmatically accessed using Java, Python, C#, PHP, or Ruby. In addition to a basic understand of how to develop Java, Python, C#, PHP, or Ruby applications, you should also be able to download and install additional libraries before attempting this tutorial.

  3. A Google Cloud Platform Console project with the BigQuery API enabled

    Applications that use BigQuery must be associated with a Google Cloud Platform Console project with the BigQuery API enabled. This project provides authentication credentials you use in your application to identify it to Google and authorize its use of the BigQuery API.

    Follow these instructions to create a project, enable the BigQuery API for it, and setup your development environment with authentication credentials. Note down the project's ID, which you'll provide to the application later on.

  4. Installed Google API Client Libraries

    Our samples use the Google APIs Client libraries to make calls to the BigQuery API. Download and install the appropriate library from the client libraries page.

    If you are developing with Java, Maven is a useful way to manage and organize dependencies. The Google APIs Client Libraries for Java are available in the central Maven repository.

Create an Authorized BigQuery Service Object

In order to make authenticated requests to Google Cloud Apis using the Google APIs Client libraries, you must:

  • Fetch the credential to use for requests.
  • Create a service object that uses that credential.

You can then make API calls by calling methods on the service object.

For this example, you'll fetch Application Default Credentials from the environment, and pass it as an argument to create the service object. For information about other types of credentials you can use, see Authenticating requests to the Google BigQuery API

Java

This sample uses the Google APIs Client Library for Java.

Python

This sample uses the Google APIs Client Library for Python.

C#

This sample uses the Google APIs Client Library for .NET.

PHP

This sample uses the Google APIs Client Library for PHP.

Ruby

This sample uses the Google APIs Client Library for Ruby.

Running Queries

BigQuery provides two API methods for running queries. The synchronous query method involves a single API call, and will wait to provide a response until the query is complete (unless provided with an optional timeout value). The asynchronous query method will "insert" a query job, and immediately return an ID for that job. You then use this job ID to poll for the status of the query, and retrieve the query result if complete. This example uses the synchronous query method. For more information about different ways to query using BigQuery, see querying data.

Running the Query

To run a synchronous query, the application makes an API call that passes the query itself (as a string), along with the project number that the query will be run under for billing and quota purposes. The query in the example below finds the 10 of Shakespeare's works with the greatest number of distinct words. BigQuery uses a SQL-like syntax, which is described in our query reference guide.

Java

This sample uses the Google APIs Client Library for Java.

Python

This sample uses the Google APIs Client Library for Python.

C#

This sample uses the Google APIs Client Library for .NET.

PHP

This sample uses the Google APIs Client Library for PHP.

Ruby

This sample uses the Google APIs Client Library for Ruby.

Displaying the query result

Once the query has completed, the API returns the result set as a JSON object, which the SDK exposes as a native object. In addition to the actual query results, the JSON response contains metadata about the query job, including a unique job ID and the schema of the result set. The application parses the query response and displays the resulting values.

Java

This sample uses the Google APIs Client Library for Java.

Python

This sample uses the Google APIs Client Library for Python.

C#

This sample uses the Google APIs Client Library for .NET.

PHP

This sample uses the Google APIs Client Library for PHP.

Ruby

This sample uses the Google APIs Client Library for Ruby.

Next Steps

This tutorial covers only the most basic steps necessary to make calls to the BigQuery API from a command-line application. The BigQuery API also provides methods for running asynchronous queries, creating tables and datasets, listing projects, and more.

Complete Source Code

Here is the complete source code for the examples in this quick start guide.

Java

This sample uses the Google APIs Client Library for Java.

Python

This sample uses the Google APIs Client Library for Python.

C#

This sample uses the Google APIs Client Library for .NET.

PHP

This sample uses the Google APIs Client Library for PHP.

Ruby

This sample uses the Google APIs Client Library for Ruby.