探索 bq 指令列工具
bq 指令列工具是以 Python 編寫的 BigQuery 指令列工具。本頁提供關於 bq 指令列工具的一般使用資訊。
如需所有 bq
指令和標記的完整參考資料,請參閱 bq 指令列工具參考資料。
事前準備
您必須先使用 Google Cloud 主控台建立或選取專案,才能使用 bq 指令列工具。
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- 新專案會自動啟用 BigQuery。
如要在現有專案中啟用 BigQuery,請前往
Enable the BigQuery API.
- 選用: 啟用專案的計費功能。如果您不想啟用帳單或提供信用卡,仍可按照本文中的步驟操作。BigQuery 提供沙箱,方便您執行這些步驟。詳情請參閱「啟用 BigQuery 沙箱」一文。
如要從 Google Cloud 控制台使用 bq 指令列工具,請啟動 Cloud Shell:
如要透過 gcloud CLI 使用 bq 指令列工具,請安裝及設定 gcloud CLI。
- 通用旗標適用於所有指令。
- 指令專屬旗標適用於特定的指令。
--FLAG ARGUMENT
(如先前範例所示)--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"
FLAG
:通用或指令專屬旗標ARGUMENT
:旗標的引數在
bq query
指令中加入查詢,如下所示:bq query --use_legacy_sql=false 'QUERY'
。將QUERY
取代為查詢。設定查詢字串格式。
如要在查詢中使用其他字串常值,請務必遵守所用殼層的引號規則,例如 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 version
。 - 如需完整的指令清單,請輸入
bq help
。 - 如需通用旗標清單,請輸入
bq --help
。 - 如需特定指令的相關說明,請輸入
bq help COMMAND
。 - 如需特定指令的相關說明以及通用旗標清單,請輸入
bq COMMAND --help
。 - 在沒有標頭的檔案頂端加入通用旗標。
- 如要加入指令專屬旗標,請 (用中括弧) 輸入指令名稱,然後在指令名稱後方逐一加入指令專屬旗標 (每行一個)。
- 將全域旗標
--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
。- 設定 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 遷移資料
查看送出及收到的要求。加入
--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
標記。
在 Cloud Shell 中輸入 bq
指令
您可以在 Cloud Shell 中輸入 bq 指令列工具指令,方法是透過 Google Cloud 控制台或 Google Cloud CLI。
定位旗標和引數
bq 指令列工具支援兩種類型的旗標:
如需可用的通用標記和指令專屬標記清單,請參閱 bq 指令列工具參考資料。
將所有通用旗標放在 bq
指令之前,然後加入指令專屬旗標。您可以加入多個通用或指令專屬旗標。例如:
bq --location=us mk --reservation --project_id=project reservation_name
您可以使用下列方法指定指令引數:
更改下列內容:
在某些指令中,必須為引數加上單引號或雙引號。當引數包含空格、逗號或其他特殊字元時,通常都必須使用引號。例如:
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 控制台中開發的查詢,請按照下列步驟操作:
詳情請參閱「執行互動式和批次查詢工作」。
取得說明
如需 bq 指令列工具的相關說明,您可以輸入下列指令:
將 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
上述範例會為下列旗標設定預設值:
在互動式殼層中執行 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 指令列工具載入資料,請參閱下列說明:
查詢資料
如要瞭解如何使用 bq 指令列工具查詢資料,請參閱下列說明:
使用外部資料來源
如要瞭解如何使用 bq 指令列工具查詢外部資料來源中的資料,請參閱以下說明:
正在匯出資料
如要瞭解如何使用 bq 指令列工具匯出資料,請參閱下列文章:
使用 BigQuery 資料移轉服務
如要瞭解如何透過 BigQuery 資料移轉服務使用 bq 指令列工具,請參閱下列文章:
排解 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 指令列工具進行偵錯,您可以輸入下列指令: