執行查詢

BigQuery 可讓您根據用途，立即 (互動式)、批次或持續執行查詢。如要驗證 SQL 語法，並估算查詢處理的資料量，以便進一步控管成本，您可以執行模擬測試。

查詢作業的類型

您可以使用下列其中一種查詢工作類型查詢 BigQuery 資料：

  • 互動式查詢工作。根據預設，BigQuery 會以互動式查詢工作的形式執行查詢，並盡快開始執行。

  • 批次查詢工作。批次查詢的優先順序低於互動式查詢。如果專案或預留項目已用盡所有可用的運算資源，批次查詢就更有可能排入佇列，並留在佇列中。批次查詢開始執行後，執行方式與互動式查詢相同。詳情請參閱「查詢佇列」。

  • 持續查詢工作。這類工作會持續執行查詢，即時分析傳入 BigQuery 的資料，然後將結果寫入 BigQuery 資料表，或匯出至 Bigtable 或 Pub/Sub。您可以使用這項功能執行具時效性的工作，例如建立深入分析並立即採取行動、套用即時機器學習 (ML) 推論，以及建構事件導向的資料管道。

您可以透過下列方法執行查詢工作：

BigQuery 會將查詢結果儲存至臨時資料表 (預設) 或永久資料表。將永久資料表指定為結果的目的地資料表時，您可以選擇要附加或覆寫現有資料表，或建立名稱不重複的新資料表。

必要的角色

如要取得執行查詢工作所需的權限，請要求管理員授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備執行查詢工作所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

必須具備下列權限，才能執行查詢工作：

  • 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 控管存取權」。

執行互動式查詢

如要執行互動式查詢，請選取下列其中一個選項：

控制台

  1. 前往「BigQuery」頁面。

    前往「BigQuery」

  2. 按一下「 SQL 查詢」。

  3. 在查詢編輯器中，輸入有效的 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;

    或者，您也可以使用「Reference」(參考資料) 面板建構新查詢。

  4. 選用：如要在輸入查詢時自動顯示程式碼建議，請依序點選「Tools」(工具) >「Parser-based auto-completion」(剖析器型自動補全)。如果不需要自動完成建議，請取消選取「Parser-based auto-completion」。這也會關閉專案名稱自動填入建議。

  5. 選用：如要選取其他查詢設定，請依序點選「Edit」(編輯) >「Query settings」(查詢設定)。

  6. 按一下「 執行」。

    如未指定目的地資料表，查詢工作會將輸出內容寫入暫存 (快取) 資料表。

    現在，您可以在「Query results」(查詢結果) 窗格的「Results」(結果) 分頁中，探索查詢結果。

  7. 選用步驟：如要按照資料欄排序查詢結果，請點選資料名稱欄旁的 「Open sort menu」(開啟排序選單)，然後選取排列順序。如果排序作業的預估處理位元組數大於 0，選單頂端就會顯示位元組數。

  8. 選用：如要查看查詢結果的圖表，請前往「Visualization」(圖表) 分頁。您可以放大或縮小圖表、將圖表下載為 PNG 檔案，或切換圖例顯示設定。

    在「Visualization configuration」(圖表設定) 窗格中，您可以變更圖表類型，並設定圖表的測量指標和維度。這個窗格中的欄位會預先填入初始設定，這些設定是根據查詢的目的地資料表結構定義推論而來。在同一個查詢編輯器中，後續執行查詢時會保留這項設定。

    如果是「折線圖」、「長條圖」或「散布圖」圖表，支援的維度為 INT64、FLOAT64、NUMERIC、BIGNUMERIC、TIMESTAMP、DATE、DATETIME、TIME 和 STRING 資料類型，支援的測量指標則為 INT64、FLOAT64、NUMERIC 和 BIGNUMERIC 資料類型。

    如果查詢結果包含 GEOGRAPHY 類型，則預設圖表類型為「地圖」，可讓您在互動式地圖上以圖表呈現結果。

  9. 選用：在「JSON」分頁中，您可以查看 JSON 格式的查詢結果，其中鍵是資料欄名稱，值則是該資料欄的結果。

bq

  1. 在 Google Cloud 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

  2. 使用 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 資料集儲存在美國多區域位置。如果您為這項查詢指定目的地資料表，則包含目的地資料表的資料集也必須位於美國多區域。您無法在某個位置查詢資料集，並將結果寫入其他位置的資料表。

      您可以使用 .bigqueryrc 檔案設定位置的預設值。

    • TABLE：目的地資料表的名稱，例如 myDataset.myTable

      如果目的地資料表是新資料表，BigQuery 會在您執行查詢時建立資料表。不過，您必須指定現有的資料集。

      如果資料表不在目前的專案中，請使用 PROJECT_ID:DATASET.TABLE 格式新增Google Cloud 專案 ID，例如 myProject:myDataset.myTable。如未指定 --destination_table，系統會產生查詢工作，將輸出內容寫入臨時資料表。

Terraform

使用 google_bigquery_job 資源。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

以下範例會執行查詢。您可以查看工作詳細資料，擷取查詢結果：


# Generate a unique job ID.
resource "random_string" "job_id" {
  lower   = true
  length  = 16
  special = false

  keepers = {
    uuid = uuid()
  }
}

# Create a query using the generated job ID.
resource "google_bigquery_job" "my_query_job" {
  job_id = random_string.job_id.id

  query {
    query = "SELECT name, SUM(number) AS total FROM `bigquery-public-data.usa_names.usa_1910_2013` GROUP BY name ORDER BY total DESC LIMIT 100;"
  }
}

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

  1. 啟動 Cloud Shell。

  2. 設定要套用 Terraform 設定的預設 Google Cloud 專案。

    每個專案只需執行這個指令一次，而且可以在任何目錄中執行。

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    如果您在 Terraform 設定檔中設定明確的值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

  1. 在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱必須有 .tf 副檔名，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. 如果您正在進行教學課程，可以複製每個章節或步驟中的程式碼範例。

    將程式碼範例複製到新建立的 main.tf。

    您也可以從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您採用這種做法。

  3. 請查看並修改範例參數，以便套用至您的環境。
  4. 儲存變更。
  5. 初始化 Terraform。每個目錄只需執行一次這項操作。 
    terraform init

    如要使用最新版 Google 供應商，請視需要加入 -upgrade 選項：

    terraform init -upgrade

套用變更

  1. 查看設定，確認 Terraform 要建立或更新的資源符合預期：
    terraform plan

    視需要修正設定。

  2. 執行下列指令，並在提示中輸入 yes，套用 Terraform 設定：
    terraform apply

    等待 Terraform 顯示「Apply complete!」訊息。

  3. 開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台的使用者介面中，前往資源頁面，確認 Terraform 已建立或更新資源。

API

如要使用 API 執行查詢，請插入新工作並填入 query 工作設定屬性。您也可以在工作資源的 jobReference 區段中，透過 location 屬性指定位置。

呼叫 getQueryResults 來輪詢結果。持續輪詢，直到 jobComplete 等於 true 為止。檢查 errors 清單中的錯誤與警告。

C#

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 C# 設定操作說明進行操作。詳情請參閱 BigQuery C# API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


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 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。


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 main(String[] args) {
    // TODO(developer): Replace this query before running the sample.
    String 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 100;";
    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(
              row -> {
                System.out.print("name:" + row.get("name").getStringValue());
                System.out.print(", count:" + row.get("total_people").getLongValue());
                System.out.println();
              });

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

如要使用 Proxy 執行查詢，請參閱「設定 Proxy」。

Node.js

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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 模擬測試會提供下列資訊：

模擬測試不會使用查詢運算單元，也不會產生費用。您可以使用模擬測試傳回的預估值，在Pricing Calculator中計算查詢費用。

執行模擬測試

如要執行模擬測試，請按照下列步驟操作：

控制台

  1. 前往 BigQuery 頁面。

    前往「BigQuery」

  2. 在查詢編輯器中輸入查詢。

    如果查詢有效，系統會自動顯示勾號和查詢將處理的資料量。如果查詢無效，則會顯示驚嘆號和錯誤訊息。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Go 設定操作說明進行操作。詳情請參閱 BigQuery Go API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 PHP 設定操作說明進行操作。詳情請參閱 BigQuery PHP API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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。

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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))

排解查詢相關問題

如要瞭解如何解決執行查詢時發生的問題，請參閱「排解查詢問題」。

執行批次查詢

如要執行批次查詢，請選取下列其中一個選項：

控制台

  1. 前往「BigQuery」頁面。

    前往「BigQuery」

  2. 按一下「 SQL 查詢」。

  3. 在查詢編輯器中，輸入有效的 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;

  4. 依序點選「編輯」>「查詢設定」。

  5. 在「資源管理」部分，選取「Batch」。

  6. 選用：調整查詢設定。

  7. 按一下 [儲存]。

  8. 按一下「 執行」。

    如未指定目的地資料表，查詢工作會將輸出內容寫入暫存 (快取) 資料表。

bq

  1. 在 Google Cloud 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

  2. 使用 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 資料集儲存在美國多區域位置。如果您為這項查詢指定目的地資料表，則包含目的地資料表的資料集也必須位於美國多區域。您無法在某個位置查詢資料集，並將結果寫入其他位置的資料表。

      您可以使用 .bigqueryrc 檔案設定位置的預設值。

    • TABLE：目的地資料表的名稱，例如 myDataset.myTable

      如果目的地資料表是新資料表，BigQuery 會在您執行查詢時建立資料表。不過，您必須指定現有的資料集。

      如果資料表不在目前的專案中，請使用 PROJECT_ID:DATASET.TABLE 格式新增Google Cloud 專案 ID，例如 myProject:myDataset.myTable。如未指定 --destination_table，系統會產生查詢工作，將輸出內容寫入臨時資料表。

API

如要使用 API 執行查詢，請插入新工作並填入 query 工作設定屬性。您也可以在工作資源的 jobReference 區段中，透過 location 屬性指定位置。

填入查詢工作屬性時，請加入 configuration.query.priority 屬性，並將值設為 BATCH。

呼叫 getQueryResults 來輪詢結果。持續輪詢，直到 jobComplete 等於 true 為止。檢查 errors 清單中的錯誤與警告。

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Go 設定操作說明進行操作。詳情請參閱 BigQuery Go API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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.Priority.BATCH (當建立 QueryJobConfiguration 時)。

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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))

執行持續查詢

如要執行持續查詢工作，必須進行額外設定。詳情請參閱「建立持續查詢」。

使用「Reference」面板

在查詢編輯器中，「參考資料」面板會動態顯示資料表、快照、檢視表和 materialized view 的情境感知資訊。您可以在面板中預覽這些資源的結構定義詳細資料，或在新分頁中開啟。您也可以使用「Reference」(參考資料) 面板，插入查詢程式碼片段或欄位名稱，建構新查詢或編輯現有查詢。

如要使用「Reference」(參考資料) 面板建構新查詢，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「BigQuery」頁面。

    前往「BigQuery」

  2. 按一下「 SQL 查詢」。

  3. 按一下「quick_reference_all」quick_reference_all「參考資料」。

  4. 按一下最近使用或已加星號的資料表或檢視表。您也可以使用搜尋列 尋找資料表和檢視表

  5. 按一下 「View actions」(查看動作)，然後點選「Insert query snippet」(插入查詢程式碼片段)。

    查詢編輯器中的參考資料面板

  6. 選用：您可以預覽資料表或檢視表的結構定義詳細資料，或在新分頁中開啟。

  7. 現在，您可以手動編輯查詢，或直接在查詢中插入欄位名稱。如要插入欄位名稱，請在查詢編輯器中指向並點選要插入欄位名稱的位置，然後在「Reference」(參考資料) 面板中點選欄位名稱。

查詢設定

執行查詢時，您可以指定下列設定：

「選擇性建立工作」模式

「選擇性建立工作」模式可改善執行時間較短的查詢 (例如來自資訊主頁或資料探索工作負載的查詢) 的整體延遲時間。這個模式會執行查詢，並傳回 SELECT 陳述式的內嵌結果，不必使用 jobs.getQueryResults 擷取結果。執行查詢時，如果使用「選擇性建立工作」模式，除非 BigQuery 判定必須建立工作才能完成查詢，否則不會建立工作。

如要啟用選擇性建立工作模式，請在 jobs.query 要求主體中，將 QueryRequest 執行個體的 jobCreationMode 欄位設為 JOB_CREATION_OPTIONAL。

如果這個欄位的值設為 JOB_CREATION_OPTIONAL，BigQuery 會判斷查詢是否可以使用選用的工作建立模式。如果是，BigQuery 會執行查詢，並在回應的 rows 欄位中傳回所有結果。由於系統不會為這項查詢建立工作，因此 BigQuery 不會在回應主體中傳回 jobReference。而是傳回 queryId 欄位，您可以使用 INFORMATION_SCHEMA.JOBS 檢視表，取得查詢的深入分析資料。由於未建立工作，因此無法將 jobReference 傳遞至 jobs.get 和 jobs.getQueryResults API 來查詢這些查詢。

如果 BigQuery 判定需要工作才能完成查詢，則會傳回 jobReference。您可以檢查 INFORMATION_SCHEMA.JOBS 檢視表中的 job_creation_reason 欄位，判斷系統為查詢建立工作的原因。在這種情況下，您應使用 jobs.getQueryResults 在查詢完成時擷取結果。

使用 JOB_CREATION_OPTIONAL 值時，回應中可能不會顯示 jobReference 欄位。存取欄位前，請先確認欄位是否存在。

如果為多陳述式查詢 (指令碼) 指定 JOB_CREATION_OPTIONAL，BigQuery 可能會最佳化執行程序。在最佳化過程中，BigQuery 可能會判定，建立的工作資源數量少於個別陳述式數量，即可完成指令碼，甚至可能完全不建立任何工作，就執行整個指令碼。這項最佳化作業取決於 BigQuery 對指令碼的評估，不一定適用於所有情況。最佳化作業完全由系統自動執行。使用者不需進行任何控制或操作。

如要使用「選擇性建立工作」模式執行查詢，請選取下列其中一個選項：

控制台

  1. 前往「BigQuery」頁面。

    前往「BigQuery」

  2. 按一下「 SQL 查詢」。

  3. 在查詢編輯器中，輸入有效的 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;

  4. 依序點選「編輯」>「查詢模式」>「選用工作建立」。如要確認這項選擇，請按一下「Confirm」(確認)。

  5. 按一下「 執行」。

bq

  1. 在 Google Cloud 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

  2. 使用 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;'

    查詢工作會在回應中傳回內嵌輸出內容。

API

如要使用 API 在「選擇性建立工作」模式中執行查詢，請同步執行查詢並填入 QueryRequest 屬性。加入 jobCreationMode 屬性，並將值設為 JOB_CREATION_OPTIONAL。

查看回覆。如果 jobComplete 等於 true，且 jobReference 為空白，請讀取 rows 欄位的結果。您也可以從回應中取得 queryId。

如果 jobReference 存在，您可以查看 jobCreationReason，瞭解 BigQuery 建立工作的原因。呼叫 getQueryResults 輪詢結果。輪詢，直到 jobComplete 等於 true 為止。查看 errors 清單中的錯誤和警告。

Java

適用版本：2.51.0 以上

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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());
    }
  }
}

如要使用 Proxy 執行查詢，請參閱「設定 Proxy」。

Python

適用版本：3.34.0 以上

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

# 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"]))

節點

適用版本：8.1.0 以上

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

// 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 以上

在試用這個範例之前，請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Go 設定操作說明進行操作。詳情請參閱 BigQuery Go API 參考文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

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 1.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

全域查詢

查詢會在參照資料所在的位置執行。不過，如果查詢參照的資料儲存在多個位置，系統就會執行全域查詢。執行全域查詢時，BigQuery 能夠從不同位置收集所有必要資料，並集中到一處，然後執行查詢並傳回結果。全域查詢需要在不同位置之間移轉資料，因此需要額外權限，且可能產生額外費用。

如要進一步瞭解全域查詢，請參閱「全域查詢」。

配額

如要瞭解互動式和批次查詢的相關配額，請參閱「查詢工作」。

如要排解與查詢相關的配額錯誤，請參閱 BigQuery 疑難排解頁面。下列配額錯誤和疑難排解資訊與查詢直接相關：

監控查詢

您可以使用工作探索工具或查詢 INFORMATION_SCHEMA.JOBS_BY_PROJECT 檢視畫面，取得執行中查詢的相關資訊。

進階執行階段

BigQuery 進階執行階段是一組效能強化功能，可自動加速分析工作負載，使用者不需採取任何行動或變更程式碼。只要有強化向量化或短查詢最佳化功能，查詢就會自動利用進階執行階段最佳化功能。

強化向量化

向量化執行是一種查詢處理模型，會以符合 CPU 快取大小的區塊，對資料欄執行作業，並使用單指令多資料 (SIMD) 指令。強化向量化功能可將 BigQuery 的向量化查詢執行作業，擴充至下列查詢處理層面：

  • 只要在 Capacitor 儲存格式中運用專門的資料編碼，就能對編碼資料執行篩選評估作業。
  • 特殊編碼會透過查詢計畫傳播，因此可在資料仍編碼時處理更多資料。
  • BigQuery 實作運算式摺疊功能，評估確定性函式和常數運算式，將複雜的述詞簡化為常數值。

短查詢最佳化

BigQuery 通常會使用重組中繼層，在分散式環境中執行查詢。短查詢最佳化功能會動態找出可做為單一階段執行的查詢，減少延遲時間和運算單元用量。在單一階段執行查詢時，可以更有效地使用特殊編碼。這些最佳化措施與「選擇性建立工作」模式搭配使用時最有效，可盡量縮短工作啟動、維護和結果擷取延遲時間。

短查詢最佳化功能的適用資格會動態調整，並受下列因素影響：

  • 預測的資料掃描大小。
  • 需要移動的資料量。
  • 查詢篩選器的選擇性。
  • 儲存空間中資料的類型和實體版面配置。
  • 整體查詢結構。
  • 過去查詢執行作業的歷來統計資料。

預估進階執行階段的影響

如要預估進階執行階段的影響，您可以使用下列 SQL 查詢，找出預估執行時間改善幅度最大的專案查詢：

WITH
  jobs AS (
    SELECT
      *,
      query_info.query_hashes.normalized_literals AS query_hash,
      TIMESTAMP_DIFF(end_time, start_time, MILLISECOND) AS elapsed_ms,
      EXISTS(
        SELECT 1
        FROM UNNEST(JSON_QUERY_ARRAY(query_info.optimization_details.optimizations)) AS o
        WHERE JSON_VALUE(o, '$.enhanced_vectorization') = 'applied'
      ) AS has_advanced_runtime
    FROM region-LOCATION.INFORMATION_SCHEMA.JOBS_BY_PROJECT
    WHERE EXTRACT(DATE FROM creation_time) > DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY)
  ),
  most_recent_jobs_without_advanced_runtime AS (
    SELECT *
    FROM jobs
    WHERE NOT has_advanced_runtime
    QUALIFY ROW_NUMBER() OVER (PARTITION BY query_hash ORDER BY end_time DESC) = 1
  )
SELECT
  job.job_id,
  100 * SAFE_DIVIDE(
    original_job.elapsed_ms - job.elapsed_ms,
    original_job.elapsed_ms) AS percent_execution_time_saved,
  job.elapsed_ms AS new_elapsed_ms,
  original_job.elapsed_ms AS original_elapsed_ms,
FROM jobs AS job
INNER JOIN most_recent_jobs_without_advanced_runtime AS original_job
  USING (query_hash)
WHERE
  job.has_advanced_runtime
  AND original_job.end_time < job.start_time
ORDER BY percent_execution_time_saved DESC
LIMIT 10;

更改下列內容：

  • LOCATION：應評估工作效能的位置

如果套用進階執行階段，這項查詢的結果可能如下所示：

/*--------------+----------------------------+----------------+---------------------*
 |    job_id    | percent_elapsed_time_saved | new_elapsed_ms | original_elapsed_ms |
 +--------------+----------------------------+----------------+---------------------+
 | sample_job1  |         45.38834951456311  |            225 |                 412 |
 | sample_job2  |         45.19480519480519  |            211 |                 385 |
 | sample_job3  |         33.246753246753244 |            257 |                 385 |
 | sample_job4  |         29.28802588996764  |           1311 |                1854 |
 | sample_job5  |         28.18181818181818  |           1027 |                1430 |
 | sample_job6  |         25.804195804195807 |           1061 |                1430 |
 | sample_job7  |         25.734265734265733 |           1062 |                1430 |
 | sample_job8  |         25.454545454545453 |           1066 |                1430 |
 | sample_job9  |         25.384615384615383 |           1067 |                1430 |
 | sample_job10 |         25.034965034965033 |           1072 |                1430 |
 *--------------+----------------------------+----------------+---------------------*/

這項查詢的結果只是預估值，反映進階執行階段的影響。 許多因素都會影響查詢效能，包括但不限於運算單元可用性、資料隨時間變化、檢視表或 UDF 定義，以及查詢參數值的差異。

如果這項查詢沒有傳回任何結果，表示沒有任何工作使用進階執行階段，或所有工作都在 30 天前完成最佳化。

這項查詢可套用至其他查詢成效指標，例如 total_slot_ms 和 total_bytes_billed。詳情請參閱 INFORMATION_SCHEMA.JOBS_BY_PROJECT 的結構定義。

後續步驟