このページの一部またはすべての情報は、S3NS の Trusted Cloud に適用されない場合があります。

クエリの実行

このドキュメントでは、BigQuery でクエリを実行する方法と、ドライランを実行して、クエリの実行前に処理されるデータの量を把握する方法について説明します。

クエリの種類

次のいずれかの種類のクエリジョブを使用して、BigQuery データをクエリできます。

インタラクティブクエリジョブ。デフォルトでは、BigQuery はクエリをインタラクティブクエリジョブとして実行します。このジョブは、できるだけ早く実行を開始することを目的としています。
バッチクエリジョブ。バッチクエリは、インタラクティブクエリよりも優先度が低くなります。プロジェクトまたは予約で利用可能なコンピューティングリソースがすべて使用されている場合、バッチクエリはキューに追加され、キュー内に残る可能性が高くなります。実行の開始後は、バッチクエリとインタラクティブクエリの動作に違いはありません。詳細については、クエリキューをご覧ください。
継続的クエリジョブ。これらのジョブでは、クエリが継続的に実行されるため、BigQuery で受信データをリアルタイムで分析し、結果を BigQuery テーブルに書き込むか、Bigtable または Pub/Sub にエクスポートできます。この機能を使用すると、分析情報の作成と即時対応、リアルタイムの ML 推論の適用、イベントドリブンデータパイプラインの構築など、時間的制約があるタスクを実行できます。

クエリジョブは、次の方法で実行できます。

Trusted Cloud コンソールでクエリを作成して実行します。
bq コマンドラインツールで bq query コマンドを実行します。
プログラマティックな方法で BigQuery REST API の jobs.query または jobs.insert メソッドを呼び出します。
BigQuery クライアントライブラリを使用します。

BigQuery は、クエリ結果を一時テーブル（デフォルト）または永続テーブルに保存します。結果の宛先テーブルとして永続テーブルを指定する場合は、既存のテーブルを追加または上書きするか、一意の名前で新しいテーブルを作成するかを選択できます。

必要なロール

クエリジョブを実行するために必要な権限を取得するには、管理者に次の IAM ロールを付与するよう依頼してください。

プロジェクトに対する BigQuery ジョブユーザー（roles/bigquery.jobUser）。
クエリが参照するすべてのテーブルとビューに対する BigQuery データ閲覧者（roles/bigquery.dataViewer）。ビューにクエリを実行するには、基になるすべてのテーブルとビューに対するこのロールも必要です。承認済みビューまたは承認済みデータセットを使用している場合は、基になるソースデータにアクセスする必要はありません。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

これらの事前定義ロールには、クエリジョブの実行に必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

クエリジョブを実行するには、次の権限が必要です。

クエリを実行するプロジェクトに対する bigquery.jobs.create。データの保存場所は関係ありません。
クエリが参照するすべてのテーブルとビューに対する bigquery.tables.getData。ビューにクエリを実行するには、基になるすべてのテーブルとビューに対するこの権限も必要です。承認済みビューまたは承認済みデータセットを使用している場合は、基になるソースデータにアクセスする必要はありません。

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

トラブルシューティング

Access Denied: Project [project_id]: User does not have bigquery.jobs.create
permission in project [project_id].

このエラーは、プロジェクトでクエリジョブを作成する権限がプリンシパルにない場合に発生します。

解決策: 管理者が、クエリを実行するプロジェクトに対する bigquery.jobs.create 権限を付与する必要があります。クエリされたデータへのアクセスに必要な権限に加えて、この権限が必要になります。

BigQuery の権限の詳細については、IAM でのアクセス制御をご覧ください。

インタラクティブクエリを実行する

インタラクティブクエリを実行するには、次のいずれかのオプションを選択します。

コンソール

[BigQuery] ページに移動します。

[BigQuery] に移動
[ SQL クエリ] をクリックします。
クエリエディタで、有効な GoogleSQL のクエリを入力します。

たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
SELECT
  name, gender,
  SUM(number) AS total
FROM
  `bigquery-public-data.usa_names.usa_1910_2013`
GROUP BY
  name, gender
ORDER BY
  total DESC
LIMIT
  10;
```
省略可: クエリを入力するときにコード候補を自動的に表示するには、 [その他] をクリックして、[SQL 予測入力] を選択します。予測入力の候補が必要ない場合は、[SQL 予測入力] の選択を解除します。これにより、プロジェクト名の自動入力候補もオフになります。
省略可: その他のクエリの設定を選択するには、 [その他]、[クエリの設定] の順にクリックします。
[ 実行] をクリックします。

宛先テーブルを指定しない場合、クエリジョブは出力を一時（キャッシュ）テーブルに書き込みます。

これで、[クエリ結果] ペインの [結果] タブでクエリ結果を確認できるようになりました。
省略可: クエリ結果を列で並べ替えるには、列名の横にある [並べ替えメニューを開く] をクリックし、並べ替え順を選択します。並べ替えた内容の推定バイト数が 0 より大きい場合は、メニューの一番上にバイト数が表示されます。
省略可: クエリ結果を可視化するには、[グラフ] タブに移動します。グラフの拡大や縮小、PNG ファイルとしてグラフのダウンロード、凡例の表示の切り替えができます。

[グラフの構成] ペインでは、グラフの種類（折れ線グラフ、棒グラフ、散布図）を変更することや、グラフの measure とディメンションを構成することが可能です。このペインのフィールドには、クエリの宛先テーブルスキーマから推定された初期構成が事前に入力されています。構成は、同じクエリエディタでの次のクエリ実行間で保持されます。ディメンションは INT64、FLOAT64、NUMERIC、BIGNUMERIC、TIMESTAMP、DATE、DATETIME、TIME、STRING データタイプをサポートし、measure は INT64、FLOAT64、NUMERIC、BIGNUMERIC データタイプをサポートします。
省略可: [JSON] タブで、JSON 形式のクエリ結果を確認できます。ここで、キーは列名、値は列の結果です。

bq

In the Trusted Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
bq query コマンドを使用します。次の例では、--use_legacy_sql=false フラグにより GoogleSQL の構文を使用できます。
```
bq query \
    --use_legacy_sql=false \
    'QUERY'
```
QUERY は、有効な GoogleSQL クエリに置き換えます。たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
bq query \
    --use_legacy_sql=false \
    'SELECT
      name, gender,
      SUM(number) AS total
    FROM
      `bigquery-public-data.usa_names.usa_1910_2013`
    GROUP BY
      name, gender
    ORDER BY
      total DESC
    LIMIT
      10;'
```
クエリジョブは、出力を一時（キャッシュ）テーブルに書き込みます。

必要に応じて、クエリ結果の宛先テーブルとロケーションを指定できます。結果を既存のテーブルに書き込むには、テーブルを追加（--append_table=true）または上書き（--replace=true）する適切なフラグを指定します。
```
bq query \
    --location=LOCATION \
    --destination_table=TABLE \
    --use_legacy_sql=false \
    'QUERY'
```
次のように置き換えます。
- LOCATION: 宛先テーブルのリージョンまたはマルチリージョン（例: US）
  
  この例では、usa_names データセットは米国のマルチリージョンロケーションに保存されています。このクエリの宛先テーブルを指定する場合は、宛先テーブルを含むデータセットも US マルチリージョンに存在する必要があります。あるロケーションのデータセットに対するクエリを実行して、結果を別のロケーションにあるテーブルに書き込むことはできません。
  
  .bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
- TABLE: 宛先テーブルの名前（例: myDataset.myTable）
  
  宛先テーブルが新しいテーブルの場合、クエリを実行すると BigQuery によってテーブルが作成されます。ただし、既存のデータセットを指定する必要があります。
  
  テーブルが現在のプロジェクトにない場合は、PROJECT_ID:DATASET.TABLE の形式でTrusted Cloud プロジェクト ID を追加します（例: myProject:myDataset.myTable）。--destination_table を指定しない場合、出力を一時テーブルに書き込むクエリジョブが生成されます。

API

API を使用してクエリを実行するには、新しいジョブを挿入して query ジョブ構成プロパティに値を設定します。必要に応じて、ジョブリソースの jobReference セクションにある location プロパティでロケーションを指定します。

getQueryResults を呼び出して結果をポーリングします。jobComplete が true と等しくなるまで取得を続けます。エラーと警告は、errors リストで確認してください。

C#

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある C# の設定手順を完了してください。詳細については、BigQuery C# API のリファレンスドキュメントをご覧ください。

BigQuery に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、クライアントライブラリの認証情報を設定するをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。


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

public class BigQueryQuery
{
    public void Query(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        string query = @"
            SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013`
            WHERE state = 'TX'
            LIMIT 100";
        BigQueryJob job = client.CreateQueryJob(
            sql: query,
            parameters: null,
            options: new QueryOptions { UseQueryCache = false });
        // Wait for the job to complete.
        job = job.PollUntilCompleted().ThrowOnAnyError();
        // Display the results
        foreach (BigQueryRow row in client.GetQueryResults(job.Reference))
        {
            Console.WriteLine($"{row["name"]}");
        }
    }
}

Go

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Go の設定手順を完了してください。詳細については、BigQuery Go API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryBasic demonstrates issuing a query and reading results.
func queryBasic(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(
		"SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " +
			"WHERE state = \"TX\" " +
			"LIMIT 100")
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"
	// Run the query and print results when the query job is completed.
	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
	}
	it, err := job.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

Java

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Java の設定手順を完了してください。詳細については、BigQuery Java API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

public class SimpleQuery {

  public static void runSimpleQuery() {
    // TODO(developer): Replace this query before running the sample.
    String query = "SELECT corpus FROM `bigquery-public-data.samples.shakespeare` GROUP BY corpus;";
    simpleQuery(query);
  }

  public static void simpleQuery(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();

      // Create the query job.
      QueryJobConfiguration queryConfig = QueryJobConfiguration.newBuilder(query).build();

      // Execute the query.
      TableResult result = bigquery.query(queryConfig);

      // Print the results.
      result.iterateAll().forEach(rows -> rows.forEach(row -> System.out.println(row.getValue())));

      System.out.println("Query ran successfully");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query did not run \n" + e.toString());
    }
  }
}

プロキシを使用してクエリを実行するには、プロキシの構成をご覧ください。

Node.js

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Node.js の設定手順を完了してください。詳細については、BigQuery Node.js API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

// Import the Google Cloud client library using default credentials
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();
async function query() {
  // Queries the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

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

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

PHP

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある PHP の設定手順を完了してください。詳細については、BigQuery PHP API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$jobConfig = $bigQuery->query($query);
$job = $bigQuery->startQuery($jobConfig);

$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
$queryResults = $job->queryResults();

$i = 0;
foreach ($queryResults as $row) {
    printf('--- Row %s ---' . PHP_EOL, ++$i);
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, json_encode($value));
    }
}
printf('Found %s row(s)' . PHP_EOL, $i);

Python

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Python の設定手順を完了してください。詳細については、BigQuery Python API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

from google.cloud import bigquery

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

query = """
    SELECT name, SUM(number) as total_people
    FROM `bigquery-public-data.usa_names.usa_1910_2013`
    WHERE state = 'TX'
    GROUP BY name, state
    ORDER BY total_people DESC
    LIMIT 20
"""
rows = client.query_and_wait(query)  # Make an API request.

print("The query data:")
for row in rows:
    # Row values can be accessed by field name or index.
    print("name={}, count={}".format(row[0], row["total_people"]))

Ruby

このサンプルを試す前に、クライアントライブラリを使用した BigQuery クイックスタートにある Ruby の設定手順を完了してください。詳細については、BigQuery Ruby API のリファレンスドキュメントをご覧ください。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

require "google/cloud/bigquery"

def query
  bigquery = Google::Cloud::Bigquery.new
  sql = "SELECT name FROM `bigquery-public-data.usa_names.usa_1910_2013` " \
        "WHERE state = 'TX' " \
        "LIMIT 100"

  # Location must match that of the dataset(s) referenced in the query.
  results = bigquery.query sql do |config|
    config.location = "US"
  end

  results.each do |row|
    puts row.inspect
  end
end

バッチクエリを実行する

バッチクエリを実行するには、次のいずれかのオプションを選択します。

コンソール

[BigQuery] ページに移動します。

[BigQuery] に移動
[ SQL クエリ] をクリックします。
クエリエディタで、有効な GoogleSQL のクエリを入力します。

たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
SELECT
  name, gender,
  SUM(number) AS total
FROM
  `bigquery-public-data.usa_names.usa_1910_2013`
GROUP BY
  name, gender
ORDER BY
  total DESC
LIMIT
  10;
```
[ 展開] をクリックして、[クエリの設定] をクリックします。
[リソース管理] セクションで、[バッチ] を選択します。
省略可: クエリ設定を調整します。
[保存] をクリックします。
[ 実行] をクリックします。

宛先テーブルを指定しない場合、クエリジョブは出力を一時（キャッシュ）テーブルに書き込みます。

bq

In the Trusted Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
bq query コマンドを使用して、--batch フラグを指定します。次の例では、--use_legacy_sql=false フラグにより GoogleSQL の構文を使用できます。
```
bq query \
    --batch \
    --use_legacy_sql=false \
    'QUERY'
```
QUERY は、有効な GoogleSQL クエリに置き換えます。たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
bq query \
    --batch \
    --use_legacy_sql=false \
    'SELECT
      name, gender,
      SUM(number) AS total
    FROM
      `bigquery-public-data.usa_names.usa_1910_2013`
    GROUP BY
      name, gender
    ORDER BY
      total DESC
    LIMIT
      10;'
```
クエリジョブは、出力を一時（キャッシュ）テーブルに書き込みます。

必要に応じて、クエリ結果の宛先テーブルとロケーションを指定できます。結果を既存のテーブルに書き込むには、テーブルを追加（--append_table=true）または上書き（--replace=true）する適切なフラグを指定します。
```
bq query \
    --batch \
    --location=LOCATION \
    --destination_table=TABLE \
    --use_legacy_sql=false \
    'QUERY'
```
次のように置き換えます。
- LOCATION: 宛先テーブルのリージョンまたはマルチリージョン（例: US）
  
  この例では、usa_names データセットは米国のマルチリージョンロケーションに保存されています。このクエリの宛先テーブルを指定する場合は、宛先テーブルを含むデータセットも US マルチリージョンに存在する必要があります。あるロケーションのデータセットに対するクエリを実行して、結果を別のロケーションにあるテーブルに書き込むことはできません。
  
  .bigqueryrc ファイルを使用してロケーションのデフォルト値を設定できます。
- TABLE: 宛先テーブルの名前（例: myDataset.myTable）
  
  宛先テーブルが新しいテーブルの場合、クエリを実行すると BigQuery によってテーブルが作成されます。ただし、既存のデータセットを指定する必要があります。
  
  テーブルが現在のプロジェクトにない場合は、PROJECT_ID:DATASET.TABLE の形式でTrusted Cloud プロジェクト ID を追加します（例: myProject:myDataset.myTable）。--destination_table を指定しない場合、出力を一時テーブルに書き込むクエリジョブが生成されます。

API

クエリジョブのプロパティにデータを入力する場合、configuration.query.priority プロパティを含めて、値を BATCH に設定します。

Go

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/bigquery"
)

// queryBatch demonstrates issuing a query job using batch priority.
func queryBatch(w io.Writer, projectID, dstDatasetID, dstTableID string) error {
	// projectID := "my-project-id"
	// dstDatasetID := "mydataset"
	// dstTableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	// Build an aggregate table.
	q := client.Query(`
		SELECT
  			corpus,
  			SUM(word_count) as total_words,
  			COUNT(1) as unique_words
		FROM ` + "`bigquery-public-data.samples.shakespeare`" + `
		GROUP BY corpus;`)
	q.Priority = bigquery.BatchPriority
	q.QueryConfig.Dst = client.Dataset(dstDatasetID).Table(dstTableID)

	// Start the job.
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Job is started and will progress without interaction.
	// To simulate other work being done, sleep a few seconds.
	time.Sleep(5 * time.Second)
	status, err := job.Status(ctx)
	if err != nil {
		return err
	}

	state := "Unknown"
	switch status.State {
	case bigquery.Pending:
		state = "Pending"
	case bigquery.Running:
		state = "Running"
	case bigquery.Done:
		state = "Done"
	}
	// You can continue to monitor job progress until it reaches
	// the Done state by polling periodically.  In this example,
	// we print the latest status.
	fmt.Fprintf(w, "Job %s in Location %s currently in state: %s\n", job.ID(), job.Location(), state)

	return nil

}

Java

バッチクエリを実行するには、QueryJobConfiguration の作成時に、クエリの優先度の設定を QueryJobConfiguration.Priority.BATCH にします。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableResult;

// Sample to query batch in a table
public class QueryBatch {

  public static void runQueryBatch() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String query =
        "SELECT corpus"
            + " FROM `"
            + projectId
            + "."
            + datasetName
            + "."
            + tableName
            + " GROUP BY corpus;";
    queryBatch(query);
  }

  public static void queryBatch(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();

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Run at batch priority, which won't count toward concurrent rate limit.
              .setPriority(QueryJobConfiguration.Priority.BATCH)
              .build();

      TableResult results = bigquery.query(queryConfig);

      results
          .iterateAll()
          .forEach(row -> row.forEach(val -> System.out.printf("%s,", val.toString())));

      System.out.println("Query batch performed successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query batch not performed \n" + e.toString());
    }
  }
}

Node.js

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

async function queryBatch() {
  // Runs a query at batch priority.

  // Create query job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfigurationquery
  const queryJobConfig = {
    query: `SELECT corpus
            FROM \`bigquery-public-data.samples.shakespeare\` 
            LIMIT 10`,
    useLegacySql: false,
    priority: 'BATCH',
  };

  // Create job configuration. For all options, see
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#jobconfiguration
  const jobConfig = {
    // Specify a job configuration to set optional job resource properties.
    configuration: {
      query: queryJobConfig,
    },
  };

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

  const jobId = job.metadata.id;
  const state = job.metadata.status.state;
  console.log(`Job ${jobId} is currently in state ${state}`);
}

Python

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(
    # Run at batch priority, which won't count toward concurrent rate limit.
    priority=bigquery.QueryPriority.BATCH
)

sql = """
    SELECT corpus
    FROM `bigquery-public-data.samples.shakespeare`
    GROUP BY corpus;
"""

# Start the query, passing in the extra configuration.
query_job = client.query(sql, job_config=job_config)  # Make an API request.

# Check on the progress by getting the job's updated state. Once the state
# is `DONE`, the results are ready.
query_job = client.get_job(
    query_job.job_id, location=query_job.location
)  # Make an API request.

print("Job {} is currently in state {}".format(query_job.job_id, query_job.state))

継続的クエリを実行する

連継続的クエリジョブを実行するには、追加の構成が必要です。詳細については、継続的クエリを作成するをご覧ください。

クエリの設定

クエリを実行するときに、次の設定を指定できます。

クエリ結果の宛先テーブル。
ジョブの優先度。
キャッシュに保存されたクエリ結果を使用するかどうか。
ジョブのタイムアウト（ミリ秒）。
セッションモードを使用するかどうか。
使用する暗号化のタイプ。
クエリに対して課金される最大バイト数。
使用する SQL 言語。
クエリを実行するロケーション。クエリは、クエリで参照されるテーブルと同じロケーションで実行する必要があります。
クエリを実行する予約（プレビュー）。

オプションジョブ作成モード

オプションジョブ作成モードを使用すると、ダッシュボードやデータ探索ワークロードなどの実行時間の短いクエリの全体的なレイテンシを改善できます。このモードでは、クエリを実行して SELECT ステートメントの結果をインラインで返します。結果を取得するために jobs.getQueryResults を使用する必要はありません。オプションジョブ作成モードを使用するクエリは、BigQuery がクエリを完了するためにジョブの作成が必要と判断しない限り、実行時にジョブを作成しません。

オプションジョブ作成モードを有効にするには、jobs.query リクエスト本文で QueryRequest インスタンスの jobCreationMode フィールドを JOB_CREATION_OPTIONAL に設定します。

このフィールドの値が JOB_CREATION_OPTIONAL に設定されている場合、BigQuery はクエリでオプションジョブ作成モードを使用できるかどうかを判断します。使用できる場合、BigQuery はクエリを実行し、レスポンスの rows フィールドにすべての結果を返します。このクエリ用にジョブが作成されていないため、BigQuery はレスポンス本文に jobReference を返しません。代わりに、queryId フィールドが返されます。このフィールドでは、INFORMATION_SCHEMA.JOBS ビューを使用してクエリに関する分析情報を取得できます。ジョブは作成されないため、これらのクエリを検索するために jobs.get API と jobs.getQueryResults API に渡す jobReference はありません。

BigQuery がクエリを完了するためにジョブが必要であると判断した場合は、jobReference が返されます。INFORMATION_SCHEMA.JOBS ビューの job_creation_reason フィールドを調べると、クエリに対してジョブが作成された理由を確認できます。この場合は、クエリが完了したときに jobs.getQueryResults を使用して結果を取得する必要があります。

JOB_CREATION_OPTIONAL 値を使用する場合、jobReference フィールドがレスポンスに存在しないことがあります。フィールドにアクセスする前に、フィールドが存在するかどうかを確認してください。

複数ステートメントクエリ（スクリプト）に JOB_CREATION_OPTIONAL が指定されている場合、BigQuery は実行プロセスを最適化することがあります。この最適化の一環として、BigQuery は、個々のステートメントの数よりも少ない数のジョブリソースを作成してスクリプトを完了できると判断するか、ジョブを作成せずにスクリプト全体を実行する場合があります。この最適化は、BigQuery によるスクリプトの評価に依存し、すべてのケースで適用されるとは限りません。最適化はシステムによって完全に自動化されています。ユーザーによる制御やアクションは必要ありません。

オプションジョブ作成モードを使用してクエリを実行するには、次のいずれかのオプションを選択します。

コンソール

[BigQuery] ページに移動します。

[BigQuery] に移動
[ SQL クエリ] をクリックします。
クエリエディタで、有効な GoogleSQL のクエリを入力します。

たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
SELECT
  name, gender,
  SUM(number) AS total
FROM
  `bigquery-public-data.usa_names.usa_1910_2013`
GROUP BY
  name, gender
ORDER BY
  total DESC
LIMIT
  10;
```
[ その他] をクリックし、[オプションジョブ作成] クエリモードを選択します。[確認] をクリックして選択内容を確定します。
[ 実行] をクリックします。

bq

In the Trusted Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Trusted Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
bq query コマンドを使用して、--job_creation_mode=JOB_CREATION_OPTIONAL フラグを指定します。次の例では、--use_legacy_sql=false フラグにより GoogleSQL の構文を使用できます。
```
bq query \
    --rpc=true \
    --use_legacy_sql=false \
    --job_creation_mode=JOB_CREATION_OPTIONAL \
    --location=LOCATION \
    'QUERY'
```
QUERY は有効な GoogleSQL クエリに置き換え、LOCATION はデータセットが配置されている有効なリージョンに置き換えます。たとえば、BigQuery 一般公開データセット usa_names に対してクエリを実行し、1910 年から 2013 年の間に米国で最も多くつけられた名前を特定します。
```
bq query \
    --rpc=true \
    --use_legacy_sql=false \
    --job_creation_mode=JOB_CREATION_OPTIONAL \
    --location=us \
    'SELECT
      name, gender,
      SUM(number) AS total
    FROM
      `bigquery-public-data.usa_names.usa_1910_2013`
    GROUP BY
      name, gender
    ORDER BY
      total DESC
    LIMIT
      10;'
```
クエリジョブは、レスポンスで出力をインラインで返します。

注: 必要に応じて、--apilog=stdout を使用して API リクエストとレスポンスをロギングし、queryId を抽出できます。

API

API を使用してオプションジョブ作成モードでクエリを実行するには、クエリを同期的に実行し、QueryRequest プロパティに値を設定します。jobCreationMode プロパティを指定して、値を JOB_CREATION_OPTIONAL に設定します。

レスポンスを確認します。jobComplete が true と等しく、jobReference が空の場合は、rows フィールドから結果を読み取ります。レスポンスから queryId を取得することもできます。

jobReference が存在する場合は、jobCreationReason で BigQuery によってジョブが作成された理由を確認できます。getQueryResults を呼び出して結果をポーリングします。jobComplete が true と等しくなるまで取得を続けます。エラーと警告は、errors リストで確認してください。

Java

利用可能なバージョン: 2.51.0 以降

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.JobId;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.QueryJobConfiguration.JobCreationMode;
import com.google.cloud.bigquery.TableResult;

// Sample demonstrating short mode query execution.
//
// This feature is controlled by setting the defaultJobCreationMode
// field in the BigQueryOptions used for the client. JOB_CREATION_OPTIONAL
// allows for the execution of queries without creating a job.
public class QueryJobOptional {

  public static void main(String[] args) {
    String query =
        "SELECT name, gender, SUM(number) AS total FROM "
            + "bigquery-public-data.usa_names.usa_1910_2013 GROUP BY "
            + "name, gender ORDER BY total DESC LIMIT 10";
    queryJobOptional(query);
  }

  public static void queryJobOptional(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.
      BigQueryOptions options = BigQueryOptions.getDefaultInstance();
      options.setDefaultJobCreationMode(JobCreationMode.JOB_CREATION_OPTIONAL);
      BigQuery bigquery = options.getService();

      // Execute the query. The returned TableResult provides access information
      // about the query execution as well as query results.
      TableResult results = bigquery.query(QueryJobConfiguration.of(query));

      JobId jobId = results.getJobId();
      if (jobId != null) {
        System.out.println("Query was run with job state.  Job ID: " + jobId.toString());
      } else {
        System.out.println("Query was run in short mode.  Query ID: " + results.getQueryId());
      }

      // Print the results.
      results
          .iterateAll()
          .forEach(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", gender: " + row.get("gender").getStringValue());
                System.out.print(", total: " + row.get("total").getLongValue());
                System.out.println();
              });

    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

プロキシを使用してクエリを実行するには、プロキシの構成をご覧ください。

Python

利用可能なバージョン: 3.34.0 以降

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

# This example demonstrates executing a query without requiring an associated
# job.
from google.cloud import bigquery
from google.cloud.bigquery.enums import JobCreationMode

# Construct a BigQuery client object, specifying that the library should
# avoid creating jobs when possible.
client = bigquery.Client(
    default_job_creation_mode=JobCreationMode.JOB_CREATION_OPTIONAL
)

query = """
    SELECT
        name,
        gender,
        SUM(number) AS total
    FROM
        bigquery-public-data.usa_names.usa_1910_2013
    GROUP BY
        name, gender
    ORDER BY
        total DESC
    LIMIT 10
"""
# Run the query.  The returned `rows` iterator can return information about
# how the query was executed as well as the result data.
rows = client.query_and_wait(query)

if rows.job_id is not None:
    print("Query was run with job state.  Job ID: {}".format(rows.job_id))
else:
    print(
        "Query was run without creating a job.  Query ID: {}".format(rows.query_id)
    )

print("The query data:")
for row in rows:
    # Row values can be accessed by field name or index.
    print("name={}, gender={}, total={}".format(row[0], row[1], row["total"]))

Node.js

利用可能なバージョン: 8.1.0 以降

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

// Demonstrates issuing a query that may be run in short query mode.

// Import the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery({
  // default behavior is to create jobs when using the jobs.query API
  defaultJobCreationMode: 'JOB_CREATION_REQUIRED',
});

async function queryJobOptional() {
  // SQL query to run.

  const sqlQuery = `
    SELECT name, gender, SUM(number) AS total
    FROM bigquery-public-data.usa_names.usa_1910_2013
    GROUP BY name, gender
    ORDER BY total DESC
    LIMIT 10`;

  // Run the query
  const [rows, , res] = await bigquery.query({
    query: sqlQuery,
    // Skip job creation to enable short mode.
    jobCreationMode: 'JOB_CREATION_OPTIONAL',
  });

  if (!res.jobReference) {
    console.log(`Query was run in short mode. Query ID: ${res.queryId}`);
  } else {
    const jobRef = res.jobReference;
    const qualifiedId = `${jobRef.projectId}.${jobRef.location}.${jobRef.jobId}`;
    console.log(
      `Query was run with job state. Job ID: ${qualifiedId}, Query ID: ${res.queryId}`,
    );
  }
  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Go

利用可能なバージョン: 1.69.0 以降

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// queryJobOptional demonstrates issuing a query that doesn't require a
// corresponding job.
func queryJobOptional(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID,
		bigquery.WithDefaultJobCreationMode(bigquery.JobCreationModeOptional),
	)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	q := client.Query(`
		SELECT
  			name, gender,
  			SUM(number) AS total
		FROM
			bigquery-public-data.usa_names.usa_1910_2013
		GROUP BY 
			name, gender
		ORDER BY
			total DESC
		LIMIT 10
		`)
	// Run the query and process the returned row iterator.
	it, err := q.Read(ctx)
	if err != nil {
		return fmt.Errorf("query.Read(): %w", err)
	}

	// The iterator provides information about the query execution.
	// Queries that were run in short query mode will not have the source job
	// populated.
	if it.SourceJob() == nil {
		fmt.Fprintf(w, "Query was run in optional job mode.  Query ID: %q\n", it.QueryID())
	} else {
		j := it.SourceJob()
		qualifiedJobID := fmt.Sprintf("%s:%s.%s", j.ProjectID(), j.Location(), j.ID())
		fmt.Fprintf(w, "Query was run with job state.  Job ID: %q, Query ID: %q\n",
			qualifiedJobID, it.QueryID())
	}

	// Print row data.
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

JDBC ドライバ

利用可能なバージョン: JDBC v1.6.1 以降

接続文字列に JobCreationMode=2 を設定する必要があります。

    jdbc:bigquery://https://www.googleapis.com/bigquery/v2:443;JobCreationMode=2;Location=US;

ODBC ドライバ

利用可能なバージョン: ODBC v3.0.7.1016 以降

.ini ファイルに JobCreationMode=2 を設定する必要があります。

    [ODBC Data Sources]
    Sample DSN=Simba Google BigQuery ODBC Connector 64-bit
    [Sample DSN]
    JobCreationMode=2

割り当て

インタラクティブクエリとバッチクエリの割り当てについては、クエリジョブをご覧ください。

クエリのモニタリング

実行中のクエリに関する情報は、ジョブエクスプローラを使用するか、INFORMATION_SCHEMA.JOBS_BY_PROJECT ビューをクエリすることで取得できます。

ドライラン

BigQuery のドライランでは、次の情報が提供されます。

オンデマンドモードでの料金の見積もり
クエリの検証
キャパシティモードでクエリによって処理されたおおよそのバイト数

ドライランはクエリスロットを使用しないため、ドライランの実行に対しては課金されません。ドライランによって返された見積もりを料金計算ツールで使用すると、クエリの費用を計算できます。

ドライランの実行

ドライランを実行するには、次の操作を行います。

コンソール

BigQuery ページに移動します。

[BigQuery] に移動
クエリエディタにクエリを入力します。

クエリが有効な場合、クエリで処理されるデータの量とともにチェックマークが自動的に表示されます。クエリが無効な場合は、感嘆符がエラーメッセージとともに表示されます。

bq

--dry_run フラグを使用して次のようなクエリを入力します。

bq query \
--use_legacy_sql=false \
--dry_run \
'SELECT
   COUNTRY,
   AIRPORT,
   IATA
 FROM
   `project_id`.dataset.airports
 LIMIT
   1000'

有効なクエリの場合、このコマンドによって次のレスポンスが生成されます。

Query successfully validated. Assuming the tables are not modified,
running this query will process 10918 bytes of data.

API

API を使用してドライランを実行するには、JobConfiguration タイプで dryRun を true に設定してクエリジョブを送信します。

Go

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
)

// queryDryRun demonstrates issuing a dry run query to validate query structure and
// provide an estimate of the bytes scanned.
func queryDryRun(w io.Writer, projectID string) error {
	// projectID := "my-project-id"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	q := client.Query(`
	SELECT
		name,
		COUNT(*) as name_count
	FROM ` + "`bigquery-public-data.usa_names.usa_1910_2013`" + `
	WHERE state = 'WA'
	GROUP BY name`)
	q.DryRun = true
	// Location must match that of the dataset(s) referenced in the query.
	q.Location = "US"

	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	// Dry run is not asynchronous, so get the latest status and statistics.
	status := job.LastStatus()
	if err := status.Err(); err != nil {
		return err
	}
	fmt.Fprintf(w, "This query will process %d bytes\n", status.Statistics.TotalBytesProcessed)
	return nil
}

Java

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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.JobInfo;
import com.google.cloud.bigquery.JobStatistics;
import com.google.cloud.bigquery.QueryJobConfiguration;

// Sample to run dry query on the table
public class QueryDryRun {

  public static void runQueryDryRun() {
    String query =
        "SELECT name, COUNT(*) as name_count "
            + "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
            + "WHERE state = 'WA' "
            + "GROUP BY name";
    queryDryRun(query);
  }

  public static void queryDryRun(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();

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query).setDryRun(true).setUseQueryCache(false).build();

      Job job = bigquery.create(JobInfo.of(queryConfig));
      JobStatistics.QueryStatistics statistics = job.getStatistics();

      System.out.println(
          "Query dry run performed successfully." + statistics.getTotalBytesProcessed());
    } catch (BigQueryException e) {
      System.out.println("Query not performed \n" + e.toString());
    }
  }
}

Node.js

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

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

async function queryDryRun() {
  // Runs a dry query of the U.S. given names dataset for the state of Texas.

  const query = `SELECT name
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 100`;

  // For all options, see https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query
  const options = {
    query: query,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
    dryRun: true,
  };

  // Run the query as a job
  const [job] = await bigquery.createQueryJob(options);

  // Print the status and statistics
  console.log('Status:');
  console.log(job.metadata.status);
  console.log('\nJob Statistics:');
  console.log(job.metadata.statistics);
}

PHP

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $query = 'SELECT id, view_count FROM `bigquery-public-data.stackoverflow.posts_questions`';

// Construct a BigQuery client object.
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);

// Set job configs
$jobConfig = $bigQuery->query($query);
$jobConfig->useQueryCache(false);
$jobConfig->dryRun(true);

// Extract query results
$queryJob = $bigQuery->startJob($jobConfig);
$info = $queryJob->info();

printf('This query will process %s bytes' . PHP_EOL, $info['statistics']['totalBytesProcessed']);

Python

QueryJobConfig.dry_run プロパティを True に設定します。ドライランのクエリ構成が渡されると、Client.query() は常に完了した QueryJob を返します。

コードサンプルを実行する前に、GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境変数を s3nsapis.fr に設定します。

from google.cloud import bigquery

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

job_config = bigquery.QueryJobConfig(dry_run=True, use_query_cache=False)

# Start the query, passing in the extra configuration.
query_job = client.query(
    (
        "SELECT name, COUNT(*) as name_count "
        "FROM `bigquery-public-data.usa_names.usa_1910_2013` "
        "WHERE state = 'WA' "
        "GROUP BY name"
    ),
    job_config=job_config,
)  # Make an API request.

# A dry run query completes immediately.
print("This query will process {} bytes.".format(query_job.total_bytes_processed))

次のステップ

クエリジョブを管理する方法を学習する。
クエリ履歴を表示する方法を学習する。
クエリの保存と共有の方法を学習する。
クエリキューについて学習する。
クエリ結果を書き込む方法を学習する。

クエリの実行

クエリの種類

必要なロール

必要な権限

トラブルシューティング

インタラクティブ クエリを実行する

コンソール

bq

API

C#

Go

Java

Node.js

PHP

Python

Ruby

バッチクエリを実行する

コンソール

bq

API

Go

Java

Node.js

Python

継続的クエリを実行する

クエリの設定

オプション ジョブ作成モード

コンソール

bq

API

Java

Python

Node.js

Go

JDBC ドライバ

ODBC ドライバ

割り当て

クエリのモニタリング

ドライラン

ドライランの実行

コンソール

bq

API

Go

Java

Node.js

PHP

Python

次のステップ

インタラクティブクエリを実行する

オプションジョブ作成モード