使用 bq 指令列工具

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

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

事前準備

在使用 BigQuery 指令列工具之前,請先使用 Google Cloud Console 主控台建立或選取專案,並安裝 Cloud SDK。

  1. 登入您的 Google 帳戶。

    如果您沒有帳戶,請申請新帳戶

  2. 在 GCP Console 的專案選擇器頁面中,選取或建立 GCP 專案。

    前往專案選取器頁面

  3. 安裝並初始化 Cloud SDK
  4. 新專案會自動啟用 BigQuery。如要在現有專案中啟用 BigQuery,請前往 啟用BigQuery必要的 。

    啟用 API

  5. 如果您不想為專案提供信用卡或啟用計費功能,BigQuery 也提供沙箱機制。無論您的專案是否已啟用計費功能,本主題中所述的步驟都適用於您的專案。如想啟用計費功能,請參閱瞭解如何啟用計費功能的相關說明。

您可以在 Google Cloud Shell 中使用預先安裝的 Cloud SDK 版本,不須下載和安裝 Cloud SDK。

一般使用說明

旗標位置

bq 支援兩種類型的旗標 — 通用旗標和指令旗標。使用順序如下所示:

bq --global_flag argument bq_command --command-specific_flag argument
  • 通用旗標 (或一般旗標) 適用於所有指令。
  • 指令專屬旗標適用於特定的指令。

請使用空格分隔多個通用旗標或指令專屬旗標。例如:

bq \
--global_flag argument \
--global_flag argument \
bq_command \
--command-specific_flag argument \
--command-specific_flag argument

您可以使用下列其中一種方法指定指令引數:

  • --flag=argument
  • --flag='argument'
  • --flag="argument"
  • --flag argument
  • --flag 'argument'
  • --flag "argument"

以上這些方法都會在 BigQuery 說明文件中用到。

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

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

指定含布林值的旗標時,可不用引數。如果指定 truefalse,就必須指定 =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 指令列工具的相關說明,您可以輸入下列指令:

  • 如需 bq 的安裝版本,請輸入 bq version
  • 如需完整的指令清單,請輸入 bq help
  • 如需通用旗標清單,請輸入 bq --help
  • 如需特定指令的相關說明,請輸入 bq help command
  • 如需特定指令的相關說明以及通用旗標清單,請輸入 bq command --help

偵錯

如要對 bq 進行偵錯,您可以輸入下列指令:

  • 如何查看送出及收到的要求
    加入 --apilog=path_to_file 旗標可將執行紀錄儲存至本機檔案。bq 的運作方式為執行符合 REST 標準的 API 呼叫,以方便您查看。當您在回報問題時,附上這份記錄也會有所幫助。使用 -stdout 取代檔案路徑時,系統會在控制台中列印記錄。將 --apilog 設為 stderr 則可輸出標準錯誤檔案。
  • 如何協助排解錯誤
    要取得工作狀態或查看像是資料表和資料集等資源的詳細資訊時,請加入 --format=prettyjson 旗標。使用這個旗標會輸出 JSON 格式的回應,包括 reason 屬性。您可以使用 reason 屬性來查詢疑難排解步驟

設定指令列旗標的預設值

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

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

將旗標加入 .bigqueryrc

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

  • 在沒有標頭的檔案頂端加入通用旗標
  • 如要加入指令專屬旗標,請 (用中括弧) 輸入指令名稱,然後在下方逐一加入指令專屬旗標 (每行一個),格式如下:
command
--command-specific_flag=argument
--command-specific_flag=argument

.bigqueryrc 中輸入指令列旗標時,您必須以 =argument 格式指定旗標的引數。

每次執行 bq 時都會讀取 .bigqueryrc,因此變更會立即更新。以互動模式 (bq shell) 執行 bq 時,您必須重新啟動殼層,變更才會生效。

範例

本範例將為下列通用旗標設定預設值:

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

本範例將為下列 query 指令專屬旗標設定預設值:

  • --use_legacy_sql 設為 false,以標準 SQL 做為預設查詢語法。

  • --max_rows 設為 100,控制查詢輸出的資料列數。

  • --maximum_bytes_billed 設為 10,000,000 個位元組 (10 MB),讓讀取資料量超過 10 MB 的查詢失敗。

本範例會設定下列 load 指令專用旗標的預設值:

  • --destination_kms_key 設為 projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
credential_file = path_to_credential_file
--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

如要確認您的設定,請輸入下列指令:

cat ~/.bigqueryrc

在互動殼層中執行 bq

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

範例

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

建立資源

如要瞭解如何使用指令列工具建立資源,請參閱以下說明:

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

取得資源相關資訊

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

列出資源

如要瞭解如何使用指令列工具列出資源,請參閱以下說明:

更新資源

如要瞭解如何使用指令列工具更新資源,請參閱以下說明:

載入資料

如要瞭解如何使用指令列工具載入資料,請參閱以下說明:

查詢資料

如要瞭解如何使用指令列工具查詢資料,請參閱以下說明:

使用外部資料來源

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

匯出資料

如要瞭解如何使用指令列工具匯出資料,請參閱以下說明:

使用 BigQuery 資料移轉服務

要瞭解如何在 BigQuery 資料移轉服務使用指令列工具,請參閱以下說明:

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
需要協助嗎?請前往我們的支援網頁