使用 bq 指令列工具

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

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

事前準備

您必須使用 Google Cloud Platform 主控台建立或選取專案,並啟用計費功能,才能使用 BigQuery 指令列工具。您也需要安裝 Cloud SDK。

  1. 登入您的 Google 帳戶。

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

  2. 選取或建立 Google Cloud Platform 專案。

    前往「Manage resources」(管理資源) 頁面

  3. 請確認您已啟用 Google Cloud Platform 專案的計費功能。

    瞭解如何啟用計費功能

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

    啟用 API

您可以在 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 前置字串。如要啟動互動模式,請輸入 bq shell。啟動殼層後,提示會變更為您預設專案的 ID。如要結束互動模式,請輸入 exit

範例

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

建立資源

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

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

取得資源相關資訊

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

列出資源

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

更新資源

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

載入資料

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

查詢資料

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

使用外部資料來源

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

匯出資料

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

使用 BigQuery 資料移轉服務

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

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

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

這個網頁