探索 bq 指令列工具

bq 指令列工具是 BigQuery 專用的 Python 指令列工具。本頁提供關於使用 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 指令列工具執行查詢

如要將在 Google Cloud 主控台中開發的查詢，透過 bq 指令列工具執行，請執行下列操作：

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 標記。