探索 bq 指令列工具

bq 指令列工具是以 Python 編寫的 BigQuery 指令列工具。本頁提供關於 bq 指令列工具的一般使用資訊。

如需所有 bq 指令和標記的完整參考資料，請參閱 bq 指令列工具參考資料。

事前準備

您必須先使用 Google Cloud 主控台建立或選取專案，才能使用 bq 指令列工具。

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

4. 新專案會自動啟用 BigQuery。 如要在現有專案中啟用 BigQuery，請前往

   Enable the BigQuery API.

   Enable the API

5. 選用： 啟用專案的計費功能。如果您不想啟用帳單或提供信用卡，仍可按照本文中的步驟操作。BigQuery 提供沙箱，方便您執行這些步驟。詳情請參閱「啟用 BigQuery 沙箱」一文。

在 Cloud Shell 中輸入 bq 指令

您可以在 Cloud Shell 中輸入 bq 指令列工具指令，方法是透過 Google Cloud 控制台或 Google Cloud CLI。

• 如要從 Google Cloud 控制台使用 bq 指令列工具，請啟動 Cloud Shell：

  啟用 Cloud Shell

• 如要透過 gcloud CLI 使用 bq 指令列工具，請安裝及設定 gcloud CLI。

定位旗標和引數

bq 指令列工具支援兩種類型的旗標：

• 通用旗標適用於所有指令。
• 指令專屬旗標適用於特定的指令。

如需可用的通用標記和指令專屬標記清單，請參閱 bq 指令列工具參考資料。

將所有通用旗標放在 bq 指令之前，然後加入指令專屬旗標。您可以加入多個通用或指令專屬旗標。例如：

bq --location=us mk --reservation --project_id=project reservation_name

您可以使用下列方法指定指令引數：

• --FLAG ARGUMENT (如先前範例所示)
• --FLAG=ARGUMENT
• --FLAG='ARGUMENT'
• --FLAG="ARGUMENT"
• --FLAG 'ARGUMENT'
• --FLAG "ARGUMENT"

更改下列內容：

• FLAG：通用或指令專屬旗標
• ARGUMENT：旗標的引數

在某些指令中，必須為引數加上單引號或雙引號。當引數包含空格、逗號或其他特殊字元時，通常都必須使用引號。例如：

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

指定含布林值的標記時，可不用引數。如果指定 true 或 false，就必須使用 FLAG=ARGUMENT 格式。

舉例來說，以下指令在布林值旗標 --use_legacy_sql 前加上 no 藉此指定 false：

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

如要將 false 指定為該旗標的引數，則可輸入以下指令：

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

透過 bq 指令列工具執行查詢

如要使用 bq 指令列工具執行您在 Google Cloud 控制台中開發的查詢，請按照下列步驟操作：

1. 在 bq query 指令中加入查詢，如下所示： bq query --use_legacy_sql=false 'QUERY'。將 QUERY 取代為查詢。

2. 設定查詢字串格式。

   如要在查詢中使用其他字串常值，請務必遵守所用殼層的引號規則，例如 Bash 或 PowerShell。

   以下範例顯示 Bash 中的一般做法，也就是使用雙引號表示查詢中的字串常值，然後將查詢本身括在單引號中：

   'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
   

   如果從其他位置複製查詢，也必須移除查詢中的所有註解。

   舉例來說，轉換下列 Google Cloud 控制台查詢：

   -- count Shakespeare's use of the string "raisin"
   SELECT
     word,
     SUM(word_count) AS count
   FROM
     `bigquery-public-data`.samples.shakespeare
   WHERE
     word LIKE '%raisin%'
   GROUP BY
     word
   

   ，然後在 bq 指令列工具查詢中輸入下列內容：

   bq query --use_legacy_sql=false \
   'SELECT
     word,
     SUM(word_count) AS count
   FROM
     `bigquery-public-data`.samples.shakespeare
   WHERE
     word LIKE "%raisin%"
   GROUP BY
     word'
   

詳情請參閱「執行互動式和批次查詢工作」。

取得說明

如需 bq 指令列工具的相關說明，您可以輸入下列指令：

• 如要查看已安裝的 bq 指令列工具版本，請輸入 bq version。
• 如需完整的指令清單，請輸入 bq help。
• 如需通用旗標清單，請輸入 bq --help。
• 如需特定指令的相關說明，請輸入 bq help COMMAND。
• 如需特定指令的相關說明以及通用旗標清單，請輸入 bq COMMAND --help。

將 COMMAND 替換為需要協助的指令。

設定指令列標記的預設值

如要設定指令列旗標的預設值，您可以在 bq 指令列工具的設定檔 .bigqueryrc 中加入旗標預設值。設定預設選項前，您必須先建立 .bigqueryrc 檔案。您可以使用自己偏好的文字編輯器建立該檔案。建立 .bigqueryrc 檔案後，您可以使用 --bigqueryrc 通用旗標指定該檔案的路徑。

如果未指定 --bigqueryrc 旗標，系統會使用 BIGQUERYRC 環境變數。如果未指定該變數，則會使用 ~/.bigqueryrc 路徑。預設路徑為 $HOME/.bigqueryrc。

將旗標加入 .bigqueryrc

如何將指令列旗標的預設值加入 .bigqueryrc：

• 在沒有標頭的檔案頂端加入通用旗標。
• 如要加入指令專屬旗標，請 (用中括弧) 輸入指令名稱，然後在指令名稱後方逐一加入指令專屬旗標 (每行一個)。

例如：

--apilog=stdout
--format=prettyjson
--location=US

[query]
--use_legacy_sql=false
--max_rows=100
--maximum_bytes_billed=10000000

[load]
--destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey

上述範例會為下列旗標設定預設值：

• 將全域旗標 --apilog 設為 stdout，在Google Cloud 主控台中列印偵錯輸出內容。
• 將全域旗標 --format 設為 prettyjson，以使用者可理解的 JSON 格式顯示指令輸出內容。
• 全域標記 --location 設為 US 多地區位置。

• query 指令專屬旗標 --use_legacy_sql 設為 false，以 GoogleSQL 做為預設查詢語法。

• 將 query 指令專屬旗標 --max_rows 設為 100，控制查詢輸出的資料列數。

• query 指令專屬標記 --maximum_bytes_billed 設為 10,000,000 個位元組 (10 MB)，讓讀取資料量超過 10 MB 的查詢失敗。

• load 指令專屬旗標 --destination_kms_key 會設為 projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey。

在互動式殼層中執行 bq 指令列工具

在互動殼層中執行 bq 指令列工具時，不必為指令加上 bq 前置字串。如要啟動互動模式，請輸入 bq shell。啟動殼層後，提示會變更為您預設專案的 ID。如要結束互動模式，請輸入 exit。

在指令碼中執行 bq 指令列工具

您可以在指令碼中執行 bq 指令列工具，就像執行 Google Cloud CLI 指令一樣。以下是 Bash 指令碼中 gcloud 和 bq 指令的範例：

#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
   word,
   SUM(word_count) AS count
 FROM
   `bigquery-public-data`.samples.shakespeare
 WHERE
   word LIKE "%raisin%"
 GROUP BY
   word'

透過服務帳戶執行 bq 指令

您可以使用服務帳戶執行已授權的 API 呼叫，或代表您執行查詢作業。如要在 bq 指令列工具中使用服務帳戶，請授權服務帳戶存取 Google Cloud 。詳情請參閱 gcloud auth activate-service-account。

如要開始使用bq指令，並模擬服務帳戶，請執行下列指令：

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

將 SERVICE_ACCOUNT_NAME 替換為服務帳戶名稱。

現在執行的 bq 指令會使用服務帳戶憑證。

如要停止從服務帳戶執行 bq 指令，請執行下列指令：

gcloud config unset auth/impersonate_service_account

範例

如需指令列範例，請參閱 BigQuery 說明文件的使用指南一節。本節列出常見指令列工作的連結，例如建立、取得、列出、刪除及修改 BigQuery 資源。

建立資源

如要瞭解如何使用 bq 指令列工具建立資源，請參閱下列說明：

• 建立資料集
• 使用結構定義建立空白資料表
• 從查詢結果建立資料表
• 建立擷取時間分區資料表
• 建立視圖

如需使用資料檔案建立資料表的範例，請參閱載入資料一節。

取得資源相關資訊

如要瞭解如何使用 bq 指令列工具取得資源相關資訊，請參閱下列說明：

• 取得資料集相關資訊
• 取得資料表相關資訊
• 取得檢視表相關資訊

列出資源

如要瞭解如何使用 bq 指令列工具列出資源，請參閱下列說明：

• 列出資料集
• 列出資料表
• 列出視圖

列出工作

如要瞭解如何使用 bq 指令列工具列出工作，請參閱下列說明：

• 列出工作

更新資源

如要瞭解如何使用 bq 指令列工具更新資源，請參閱下列說明：

• 更新資料集屬性
• 更新資料表屬性
• 更新視圖屬性

正在載入資料

如要瞭解如何使用 bq 指令列工具載入資料，請參閱下列說明：

• 從 Cloud Storage 載入 Avro 資料
• 從 Cloud Storage 載入 JSON 資料
• 從 Cloud Storage 載入 CSV 資料
• 從本機檔案載入資料

查詢資料

如要瞭解如何使用 bq 指令列工具查詢資料，請參閱下列說明：

• 執行查詢
• 寫入查詢結果
• 執行參數化查詢

使用外部資料來源

如要瞭解如何使用 bq 指令列工具查詢外部資料來源中的資料，請參閱以下說明：

• 使用 JSON 結構定義檔建立資料表定義
• 查詢 Bigtable 資料
• 查詢 Cloud Storage 資料
• 查詢 Google 雲端硬碟資料

正在匯出資料

如要瞭解如何使用 bq 指令列工具匯出資料，請參閱下列文章：

• 匯出儲存在 BigQuery 的資料

使用 BigQuery 資料移轉服務

如要瞭解如何透過 BigQuery 資料移轉服務使用 bq 指令列工具，請參閱下列文章：

• 設定 Amazon S3 轉移作業
• 設定 Campaign Manager 轉移作業
• 設定 Cloud Storage 移轉作業
• 設定 Google Ad Manager 移轉作業
• 設定 Google Ads 轉移作業
• 設定 Google Merchant Center 轉移作業 (Beta 版)
• 設定 Google Play 移轉作業
• 設定 Search Ads 360 轉移作業 (Beta 版)
• 設定 YouTube 頻道轉移作業
• 設定 YouTube 內容擁有者轉移作業
• 從 Amazon Redshift 遷移資料
• 從 Teradata 遷移資料
• 管理轉移作業

排解 bq 指令列工具問題

本節說明如何解決 bq 指令列工具的問題。

確保 gcloud CLI 為最新版本

如果您使用 Google Cloud CLI 的 bq 指令列工具，請務必更新 gcloud CLI 安裝項目，確保 bq 指令列工具具備最新功能和修正內容。如要確認您是否執行最新版的 gcloud CLI，請在 Cloud Shell 中輸入下列指令：

gcloud components list

輸出內容的前兩行會顯示目前 gcloud CLI 安裝版本的版本號碼，以及最新 gcloud CLI 的版本號碼。如果發現版本過舊，請在 Cloud Shell 中輸入下列指令，將 gcloud CLI 安裝版本更新至最新版本：

gcloud components update

偵錯

如要對 bq 指令列工具進行偵錯，您可以輸入下列指令：

• 查看送出及收到的要求。加入 --apilog=PATH_TO_FILE 旗標可將執行紀錄儲存至本機檔案。將 PATH_TO_FILE 替換為您要儲存記錄的路徑。bq 指令列工具的運作方式為執行符合 REST 樣式的標準 API 呼叫，以方便您查看。當您回報問題時，附上這份記錄也會有所幫助。使用 - 或 stdout 取代路徑時，系統會在 Google Cloud 控制台中列印記錄。將 --apilog 設為 stderr 則可輸出標準錯誤檔案。如要記錄更多要求，請使用 --httplib2_debuglevel=LOG_LEVEL 旗標。LOG_LEVEL 記錄檔會記錄更多有關 HTTP 要求的資訊。

• 排解錯誤。要取得工作狀態或查看像是資料表和資料集等資源的詳細資訊時，請加入 --format=prettyjson 旗標。使用這個旗標會輸出 JSON 格式的回應，包括 reason 屬性。您可以使用 reason 屬性來查詢疑難排解步驟。如要進一步瞭解執行期間發生的任何錯誤，請使用 --debug_mode 標記。