本頁面由 Cloud Translation API 翻譯而成。

bq 指令列工具參考資料

本文說明 bq 的語法、指令、標記和引數。bq 是 BigQuery 專用的 Python 式指令列工具。

如需使用 bq 指令列工具的教學課程，請參閱「使用 bq 工具載入及查詢資料」。

使用 bq 指令列工具的方法

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

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

啟用 Cloud Shell
如要在本機使用 bq 指令列工具，請安裝及設定 gcloud CLI。如要讓安裝保持在最新狀態，請參閱 gcloud CLI 說明文件中的「管理安裝作業」。

指令格式

bq 指令列工具使用下列格式：

bq COMMAND [FLAGS] [ARGUMENTS]

部分標記可搭配多個 bq 指令列工具指令使用，這些標記說明請參閱「通用標記」一節。

其他標記則是指令專屬，只能搭配特定的 bq 指令列工具指令使用。指令專屬標記說明請參閱指令章節。

指定旗標的值

指定旗標的值時，等號 (=) 為選用。舉例來說，下列兩個指令的作用相同：

bq ls --format prettyjson myDataset
bq ls --format=prettyjson myDataset

為求清楚明瞭，本文使用等號。

部分 bq 指令列工具旗標為布林值，您可以將旗標值設為 true 或 false。bq 指令列工具接受下列格式，用於設定布林值標記。

值	格式	範例
`true`	`--FLAGNAME=true`	`--debug_mode=true`
`true`	`--FLAGNAME`	`--debug_mode`
`false`	`--FLAGNAME=false`	`--debug_mode=false`
`false`	`--noFLAGNAME`	`--nodebug_mode`

這份文件使用 --FLAGNAME=VALUE 格式表示布林值標記。

所有布林值旗標皆為選用，如果沒有布林值旗標，BigQuery 會使用旗標的預設值。

在引數中指定 BigQuery 資源

指定資源的格式取決於環境；在某些情況下，專案和資料集之間的分隔符號是半形冒號 (:)，在某些情況下則是半形句號 (.)。下表說明如何在不同環境中指定 BigQuery 資料表。

背景資訊	格式	範例
bq 指令列工具	`PROJECT:DATASET.TABLE`	`myProject:myDataset.myTable`
GoogleSQL 查詢	`PROJECT.DATASET.TABLE`	`myProject.myDataset.myTable`
舊版 SQL 查詢	`PROJECT:DATASET.TABLE`	`myProject:myDataset.myTable`

如果未指定專案，BigQuery 會使用目前的專案。舉例來說，如果目前的專案是 myProject，BigQuery 會將 myDataset.myTable 解讀為 myProject:myDataset.myTable (或 myProject.myDataset.myTable)。

部分資源 ID 必須使用反引號 (`) 加上引號。如果資源 ID 開頭為英文字母或底線字元，且只包含英文字母、數字和底線，則不需要加上引號。不過，如果資源 ID 包含其他類型的字元或保留的關鍵字，您必須以反引號括住 ID (或 ID 中含有特殊字元或保留關鍵字的部分)。詳情請參閱「ID」。

如何執行指令

將所有通用旗標放在 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：旗標的引數

部分指令需要在引數周圍加上引號。如果需要引號，單引號或雙引號都可以。需要引號的引數通常是包含空格、逗號或其他特殊字元的值。如果引數包含 BigQuery 資源，請務必遵循在指令中指定資源名稱的規則。

。

這個範例說明如何透過指令列執行 GoogleSQL 查詢：

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 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'

使用服務帳戶

您可以使用服務帳戶代表您執行已授權的 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

設定指令列旗標的預設值

如要設定指令列旗標的預設值，您可以在 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 做為預設查詢語法。
附註：您不能在 .bigqueryrc 中使用 --nouse_legacy_sql。
將 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。

CLI 說明

如需 bq 指令列工具的相關說明，請執行下列指令：

說明	help 指令格式	範例
已安裝的版本	`bq version`	`bq version`
所有指令的清單和範例	`bq help`	`bq help`
通用旗標說明	`bq --help`	`bq --help`
特定指令的說明	`bq help COMMAND`	`bq help mk`

排解 CLI 指令問題

如要記錄傳送及接收的要求，請按照下列步驟操作：: 加入 --apilog=PATH_TO_FILE 旗標可將執行紀錄儲存至本機檔案。將 PATH_TO_FILE 替換為要儲存記錄檔的位置。bq 指令列工具的運作方式為執行符合 REST 樣式的標準 API 呼叫，以方便您在進行疑難排解時查看。向 Cloud 客戶服務回報問題時，附上這份記錄也會有所幫助。; 使用 - 或 stdout 取代路徑時，系統會在 Google Cloud 控制台中列印記錄。將 --apilog 設為 stderr 則可輸出標準錯誤檔案。如要記錄更多要求，請使用 --httplib2_debuglevel=LOG_LEVEL 旗標。LOG_LEVEL 記錄的 HTTP 要求資訊越多。
如要排解錯誤，請按照下列步驟操作：: 要取得工作狀態或查看像是資料表和資料集等資源的詳細資訊時，請加入 --format=prettyjson 旗標。使用這個旗標會輸出 JSON 格式的回應，包括 reason 屬性。您可以使用 reason 屬性來尋找錯誤訊息。; 如要進一步瞭解執行指令時發生的錯誤，請使用 --debug_mode 旗標。

通用標記

您可以在任何 bq 指令中使用下列旗標 (如適用)：

--api=ENDPOINT

指定要呼叫的 API 端點。預設值為 https://www.googleapis.com。

--api_version=VERSION

指定要使用的 API 版本。預設值為 v2。

--apilog=FILE

將所有 API 要求和回應記錄於 FILE 所指定的檔案。可能的值如下：

檔案路徑 - 將記錄檔寫入指定檔案
stdout - 將記錄輸出至標準輸出內容
stderr - 將記錄檔記錄到標準錯誤
false - 不會記錄 API 要求和回應 (預設)

--use_google_auth={true|false}

如果設為 true，則會啟用使用 Google Auth 程式庫的驗證機制。預設值為 true。

--bigqueryrc=PATH

指定 bq 指令列工具設定檔的路徑。如果未指定 --bigqueryrc 標記，指令會使用 BIGQUERYRC 環境變數。如未設定環境變數，系統會使用 $HOME/.bigqueryrc。如果該檔案不存在，則會使用 ~/.bigqueryrc。詳情請參閱設定指令列旗標的預設值。

--ca_certificates_file=PATH

指定憑證授權單位服務 (CA) 檔案的位置。

--dataset_id=DATASET_ID

指定要搭配指令使用的預設資料集。如果不適用的話，系統會忽略這個標記。您可以使用 PROJECT:DATASET 或 DATASET 格式指定 DATASET_ID 引數。如果缺少 PROJECT 部分，系統會使用預設專案。如要覆寫預設專案設定，請指定 --project_id 標記。

--debug_mode={true|false}

如果設為 true，則會針對 Python 例外狀況顯示回溯資料。預設值為 false。

--disable_ssl_validation={true|false}

如果設為 true，則會啟用 HTTPS 憑證驗證。預設值為 false。

--discovery_file=PATH

指定探索時要讀取的 JSON 檔案。

--enable_gdrive={true|false}

如果設為 false，則會要求不含 Google 雲端硬碟範圍的新 OAuth 憑證。預設值為 true，會要求具有雲端硬碟範圍的新 OAuth 權杖。如要將這個旗標設為 false，並使用使用者帳戶進行驗證，請將 --use_google_auth 旗標設為 false。

--fingerprint_job_id={true|false}

如要使用來自工作設定指紋的工作 ID，請設為 true。此設定可避免系統意外多次執行相同工作。預設值為 false。

--format=FORMAT

指定指令輸出內容的格式，請使用下列其中一個值：

pretty：格式化的資料表輸出內容
sparse：簡化的資料表輸出內容
prettyjson：容易理解的 JSON 格式
json：盡可能壓縮到最小的 JSON
csv：包含標頭的 csv 格式

pretty、sparse 和 prettyjson 是使用者能理解的格式。json 和 csv 適合用來傳送至其他程式。如果指定 none，指令就不會產生任何輸出內容。如果缺少 --format 旗標，系統就會根據指令選擇適當的輸出格式。

--headless={true|false}

如要在沒有使用者互動的情況下執行 bq 工作階段，請設為 true。舉例來說，debug_mode 不會觸發偵錯工具，列印資訊的頻率也會降低。預設值為 false。

--httplib2_debuglevel=DEBUG_LEVEL

指定是否要顯示 HTTP 偵錯資訊。如果 DEBUG_LEVEL 大於 0，除了錯誤訊息外，指令還會將 HTTP 伺服器要求和回應記錄到 stderr。如果 DEBUG_LEVEL 不大於 0，或未使用 --httplib2_debuglevel 旗標，則只會提供錯誤訊息。

例如：

--httplib2_debuglevel=1

--job_id=JOB_ID

指定新職缺的職缺 ID。這個旗標僅適用於建立工作的指令：cp、extract、load 和 query。如果沒有使用 --job_id 標記，指令會產生專屬的工作 ID。詳情請參閱透過程式執行工作。

--job_property=KEY:VALUE

要在工作設定的屬性欄位中加入的鍵/值組合。重複使用這個旗標即可指定其他屬性。

--location=LOCATION

對應於區域或多區域位置的字串。當您使用 --jobs 旗標顯示工作相關資訊時，bq cancel 和 bq show 指令都需要位置旗標。對於下列指令，位置標記是選用的：

query
cp
load
extract
partition
update
wait
使用 --dataset、--reservation、--capacity_commitment 或 --reservation_assignment 旗標時，mk
使用 --reservation、--capacity_commitment 或 --reservation_assignment 旗標時，請使用 ls

所有其他指令都會忽略 --location 旗標。

--max_rows_per_request=MAX_ROWS

一個整數，用來指定每次讀取所傳回的資料列數量上限。

--project_id=PROJECT

指定要用於指令的專案。

--proxy_address=PROXY

指定用來連線至 Google Cloud的 Proxy 主機名稱或 IP 位址。

--proxy_password=PASSWORD

指定透過 Proxy 主機進行驗證時使用的密碼。

--proxy_port=PORT

指定用來連線至 Proxy 主機的通訊埠編號。

--proxy_username=USERNAME

指定透過 Proxy 主機進行驗證時使用的使用者名稱。

--quiet={true|false} 或 -q={true|false}

如要在工作執行期間停止更新狀態，請設為 true。預設值為 false。

--synchronous_mode={true|false} 或 -sync={true|false}

如要建立工作並立即傳回，且以成功完成的狀態做為錯誤代碼，請設為 false。如果設為 true，指令就會等候工作完成再傳回結果，並傳回工作完成狀態做為錯誤代碼。預設值為 true。

--trace=token:TOKEN

指定要納入 API 要求的追蹤權杖。

--use_regional_endpoints={true|false}

預先發布版。如要連線至區域端點，請將 --use_regional_endpoints 標記設為 true，並將 --location 標記設為要連線的區域。預設值為 false。

已淘汰的通用旗標

下列通用標記用於從檔案指定 bq 指令列工具標記，但已淘汰。如要從檔案指定標記，請使用 --bigqueryrc 標記。

--flagfile=PATH

如有指定此旗標時，則會在 bq 指令列工具中插入所提供檔案的旗標定義。預設值為 ''。詳情請參閱「設定指令列旗標的預設值」。

指令

以下各節說明 bq 指令列工具的指令，以及指令專屬的標記和引數。

`bq add-iam-policy-binding`

使用 bq add-iam-policy-binding 指令擷取資料表或檢視區塊的身分與存取權管理 (IAM) 政策，並在政策中新增繫結，一次完成。

這個指令可取代下列三步驟程序：

使用 bq get-iam-policy 指令擷取政策檔案 (JSON 格式)。
編輯政策檔案。
使用 bq set-iam-policy 指令，以新的繫結更新政策。

劇情概要

bq add-iam-policy-binding [FLAGS] --member=MEMBER_TYPE:MEMBER --role=ROLE
  [--table] RESOURCE

範例

bq add-iam-policy-binding --member=user:myAccount@gmail.com \
  --role=roles/bigquery.dataViewer myDataset.myTable

旗標和引數

bq add-iam-policy-binding 指令可使用下列旗標和引數：

--member=MEMBER_TYPE:MEMBER

這是必要旗標，使用 --member 旗標指定身分與存取權管理政策繫結的成員。--member 旗標必須搭配 --role 旗標。一組 --member 和 --role 旗標等於一個繫結。

MEMBER_TYPE 值會指定身分與存取權管理政策繫結中的成員類型。請使用下列其中一個值：

user
serviceAccount
group
domain

MEMBER 值會指定 IAM 政策繫結中成員的電子郵件地址或網域。

--role=ROLE

這是必要旗標，指定 IAM 政策繫結的角色部分。--role 旗標必須搭配 --member 旗標。一組 --member 和 --role 標記等於一個繫結。

--table={true|false}

如果 RESOURCE 引數不是資料表或檢視區塊 ID，請將 --table 旗標設為 true，系統就會傳回錯誤。預設值為 false。為確保與其他指令一致，這個標記也適用於這個指令。

RESOURCE

要新增政策的表格或檢視區塊。

詳情請參閱 IAM 政策參考資料。

`bq cancel`

使用 bq cancel 指令取消 BigQuery 工作。

劇情概要

bq [--synchronous_mode=false] cancel JOB_ID

範例

bq cancel bqjob_12345

bq --synchronous_mode=false cancel bqjob_12345

旗標和引數

bq cancel 指令會使用下列旗標和引數：

--synchronous_mode=false: 如果不想等待 bq cancel 指令完成，請將全域 --synchronous_mode 標記設為 false。預設值為 true。
JOB_ID: 要取消的工作。

如要進一步瞭解如何使用 bq cancel 指令，請參閱管理工作一文。

`bq cp`

使用 bq cp 指令執行下列工作：

建立資料表、資料表副本或資料表快照。
建立資料表副本。
建立資料表快照。

劇情概要

bq cp [FLAGS] SOURCE_TABLE DESTINATION_TABLE

範例

bq cp myDataset.myTable myDataset.myTableCopy

旗標和引數

bq cp 指令會使用下列旗標和引數：

--append_table={true|false} 或 -a={true|false}

如要將資料表附加到現有資料表，請設為 true。預設值為 false。

您無法同時使用 --append_table=true 和 --clone=true 旗標設定。

--clone={true|false}

如要建立資料表副本，請設為 true。基礎資料表可以是標準資料表、資料表副本或資料表快照。目的地資料表是資料表副本。預設值為 false；如果未指定 --clone=true 或 --snapshot=true，則目的地資料表與基本資料表類型相同。需要 --no_clobber 旗標。

您無法同時使用 --append_table=true 和 --clone=true 旗標設定。

--destination_kms_key=KEY

指定用來加密目的地資料表資料的 Cloud KMS 金鑰資源 ID。

例如：

--destination_kms_key=projects/myProject/locations/global/keyRings/myKeyRing/cryptoKeys/myKey

--expiration=SECONDS

資料表快照失效前的秒數。如果未納入，資料表快照到期時間會設為包含新資料表快照的資料集預設到期時間。搭配 --snapshot 旗標使用。

--force={true|false} 或 -f={true|false}

如要覆寫現有的目的地資料表，請將 true 設為預設值為 false；如果目標資料表已存在，指令會先提示確認，再覆寫資料表。

--no_clobber={true|false} 或 -n={true|false}

如要禁止覆寫現有的目的地資料表，請設為 true。預設值為 false；如果目的地資料表已存在，系統會覆寫該資料表。

--restore={true|false}

這個標記即將淘汰。如要從資料表快照建立可寫入的資料表，請使用 bq cp 指令或 bq cp --clone 指令。

--snapshot={true|false}

如要為 SOURCE_TABLE 引數中指定的資料表建立資料表快照，請將 true 設為 true。基礎資料表可以是標準資料表、資料表副本或其他資料表快照。預設值為 false；如果未指定 --clone=true 或 --snapshot=true，則目的地資料表會與基本資料表類型相同。需要 --no_clobber 旗標。

SOURCE_TABLE

要複製的表格。

DESTINATION_TABLE

要複製到的資料表。

如要進一步瞭解如何使用 cp 指令，請參閱下列文章：

`bq extract`

使用 bq extract 指令將資料表資料匯出至 Cloud Storage。

劇情概要

bq extract [FLAGS] RESOURCE DESTINATION

範例

bq extract --compression=GZIP --destination_format=CSV --field_delimiter=tab \
    --print_header=false myDataset.myTable gs://my-bucket/myFile.csv.gzip

bq extract --destination_format=CSV --field_delimiter='|' myDataset.myTable \
  gs://myBucket/myFile.csv

旗標和引數

bq extract 指令會使用下列旗標和引數：

--compression=COMPRESSION_TYPE

指定匯出檔案所採用的壓縮類型。可能的值如下：

GZIP
DEFLATE
SNAPPY
NONE

預設值為 NONE。

如要瞭解各壓縮類型支援的格式，請參閱「匯出格式與壓縮類型」。

--destination_format=FORMAT

指定匯出資料的格式。可能的值如下：

CSV
NEWLINE_DELIMITED_JSON
AVRO
PARQUET

預設值為 CSV。

--field_delimiter=DELIMITER

針對 CSV 匯出內容，指定輸出檔案中用來標示資料欄間界線的字元。分隔符可以是任何 ISO-8859-1 半形字元。您可以使用 \t 或 tab 指定分頁符。

--print_header={true|false}

如要禁止系統列印格式有標頭的標頭列，請設為 false。預設值為 true，且會納入標頭列。

RESOURCE

您要匯出的資料表。

DESTINATION

接收匯出資料的儲存位置。

如要進一步瞭解如何使用 bq extract 指令，請參閱匯出資料表資料一文。

`bq get-iam-policy`

使用 bq get-iam-policy 指令擷取資源的 IAM 政策，並列印至 stdout。資源可以是資料表、檢視區塊或時段預訂。政策採用 JSON 格式。

劇情概要

bq get-iam-policy [FLAGS] RESOURCE

範例

bq get-iam-policy myDataset.myTable

bq get-iam-policy --reservation myReservation

旗標和引數

bq get-iam-policy 指令會使用下列旗標和引數：

--table={true|false} 或 --t={true|false}: 如要讓系統在 RESOURCE 不是資料表或檢視區塊 ID 時傳回錯誤，請將 --table 旗標設為 true。預設值為 false。為確保與其他指令一致，這個標記也適用於這個指令。
--reservation={true|false}: 如要取得預訂的身分與存取權管理政策，請設為 true (預覽)。預設值為 false。使用這個旗標時，RESOURCE 會視為預訂 ID。預留項目可選擇性加上專案和位置前置字元：myProject:myLocation.myReservation。
RESOURCE: ：要取得政策的資料表或檢視區塊。

如要進一步瞭解 bq get-iam-policy 指令，請參閱「使用 IAM 控管資源存取權」。

`bq head`

使用 bq head 指令顯示資料表的指定資料列和資料欄。根據預設，系統會顯示前 100 列的所有資料欄。

劇情概要

bq head [FLAGS] [TABLE]

範例

bq head --max_rows=10 --start_row=50 --selected_fields=field1,field3 \
  myDataset.myTable

旗標和引數

bq head 指令會使用下列旗標和引數：

--job=JOB or -j=JOB: 如要讀取查詢工作的結果，請使用有效工作 ID 指定這個旗標。
--max_rows=MAX or -n=MAX: 一個整數，用來指定顯示資料表資料時要列印的資料列數量上限。預設值為 100。
--selected_fields=COLUMN_NAMES or -c=COLUMN_NAMES: 以逗號分隔的清單，用來指定顯示資料表資料時要傳回的欄位 (包括巢狀和重複欄位) 子集。如未指定此旗標，系統會傳回所有資料欄。
--start_row=START_ROW or -s=START_ROW: 一個整數，用來指定顯示資料表資料前要略過的資料列數量。預設值為 0，資料表資料會從第一列開始。
--table={true|false} 或 -t={true|false}: 如果指令引數不是表格或檢視區塊，請設為 true，傳回錯誤。預設值為 false。為確保與其他指令一致，這個標記也適用於這個指令。
TABLE: 要擷取資料的資料表。

如要進一步瞭解如何使用 bq head 指令，請參閱管理資料表資料一文。

`bq help`

使用 bq help 指令在工具中顯示 bq 指令列工具說明文件。

劇情概要

bq help [COMMAND]

旗標和引數

bq help 指令會使用下列旗標和引數：

COMMAND: 指定要取得線上說明的特定 bq 指令列工具指令。

`bq insert`

使用 bq insert 指令，透過串流插入作業，將檔案中以換行符號分隔的 JSON 格式資料列插入資料表。資料類型會轉換成符合目標資料表資料欄類型。這項指令僅供測試。如要將資料以串流方式傳入 BigQuery，請使用 insertAll API 方法。

劇情概要

bq insert [FLAGS] TABLE FILE

範例

bq insert --ignore_unknown_values --template_suffix=_insert myDataset.myTable /tmp/myData.json

echo '{"a":1, "b":2}' | bq insert myDataset.myTable

旗標和引數

bq insert 指令會使用下列旗標和引數：

--ignore_unknown_values={true|false} 或 -i={true|false}: 如果設為 true，BigQuery 會忽略任何與資料表結構定義不符的鍵/值配對，並插入與結構定義相符的資料列。如果設為 false，系統不會插入資料與表格結構定義不符的資料列。預設值為 false。
--skip_invalid_rows={true|false} 或 -s={true|false}: 如果設為 true，BigQuery 會嘗試插入任何有效的資料列 (即使有無效的資料列也一樣)。如果設為 false，只要有任何無效的資料列，指令就會失敗。預設值為 false。
--template_suffix=SUFFIX or -x=SUFFIX: 如果有指定此旗標，系統會將目的地資料表 TABLE 當做基礎範本，並在名為 {destination}{templateSuffix} 的執行個體資料表中插入資料列。BigQuery 會使用基礎範本的結構定義建立執行個體資料表。
TABLE: 您要插入資料的資料表。
FILE: 內含要插入資料的檔案。

如要進一步瞭解如何使用 bq insert 指令，請參閱以串流方式將資料傳入 BigQuery。

`bq load`

使用 bq load 指令將資料載入資料表。

劇情概要

bq load [FLAGS] DESTINATION_TABLE SOURCE_DATA [SCHEMA]

範例

bq load myDataset.newTable gs://mybucket/info.csv ./info_schema.json

旗標和引數

bq load 指令會使用下列旗標和引數：

--allow_jagged_rows={true|false}

如要允許 CSV 資料缺少結尾自選欄，請設為 true。

--preserve_ascii_control_characters={true|false}

如要在 CSV 資料中允許內嵌 ASCII 控制字元，請設為 true。

--allow_quoted_newlines={true|false}

如要在 CSV 資料中使用加上引號的換行符號，請設為 true。

--autodetect={true|false}

如要針對 CSV 和 JSON 資料啟用結構定義自動偵測功能，請設為 true。預設值為 false。如果 --autodetect 為 false，且未使用 --schema 旗標指定結構定義，且目的地資料表存在，則會使用目的地資料表的結構定義。

--clustering_fields=COLUMNS

以半形逗號分隔的清單，最多包含四個資料欄名稱，用於指定資料表分群要使用的欄位。

--column_name_character_map=SCOPE

定義資料欄名稱字元的範圍和處理方式，並可選擇啟用彈性資料欄名稱。CSV 檔案必須有 --autodetect 選項。如需可能值的清單，請參閱 load_option_list。

--destination_kms_key=KEY

指定用來加密目的地資料表資料的 Cloud KMS 金鑰資源 ID。

--encoding=ENCODING_TYPE or -E=ENCODING_TYPE

資料中使用的字元編碼。請使用下列其中一個值：

ISO-8859-1 (又稱為 Latin-1)
UTF-8

--field_delimiter=DELIMITER or -F=DELIMITER

指定用來標示資料中資料欄間界線的字元。分隔符號可以是任何 ISO-8859-1 半形字元。您可以使用 \t 或 tab 指定定位點分隔符號。

--ignore_unknown_values={true|false}

如果為 CSV 和 JSON 檔案設定 true，系統會載入含有額外資料欄值的資料列 (與表格結構定義不符)，但會忽略額外資料欄。如果針對 Avro、Parquet 和 ORC 檔案設為 true，系統會忽略檔案結構定義中不存在於資料表結構定義的欄位，且不會載入這些欄位。

--json_extension=JSON_TYPE

指定要載入的 JSON 檔案類型。僅適用於 JSON 檔案。可能的值如下：

GEOJSON - 以換行符號分隔的 GeoJSON 檔案

如要使用這個旗標，--source_format 旗標必須設為 NEWLINE_DELIMITED_JSON。

詳情請參閱載入以換行符號分隔的 GeoJSON 檔案。

--max_bad_records=MAX

一個整數，用來指定整個工作失敗前可允許的錯誤記錄數量上限。預設值為 0。無論 --max_bad_records 的值為何，系統最多只會傳回五個任何類型的錯誤。這個標記僅適用於載入 CSV、JSON 和 Google 試算表資料。

--null_marker=STRING

選用的自訂字串，代表 CSV 資料中的 NULL 值。

--projection_fields=PROPERTY_NAMES

如果將 --source_format 設為 DATASTORE_BACKUP，這個標記就會指出要從 Datastore 匯出內容載入的實體屬性。以半形逗號分隔的清單指定屬性名稱。屬性名稱有大小寫之分，且必須參照頂層屬性。您也可以將此標記與 Firestore 匯出內容搭配使用。

--quote=CHARACTER

指定用來括住 CSV 資料中欄位的引用字元。CHARACTER 引數可以是任何單一位元組字元。預設值為雙引號 (")。如要指定沒有引號字元，請使用空白字串 ""。

--replace={true|false}

如要在載入新資料時清除所有現有資料和結構定義，請設為 true。除非您指定 --destination_kms_key 旗標，否則系統也會移除所有 Cloud KMS 金鑰。預設值為 false。

等同於 JobConfigurationLoad.writeDisposition 的 WRITE_TRUNCATE 值。

--schema={SCHEMA_FILE|SCHEMA}

指定本機 JSON 結構定義檔路徑，或以逗號分隔的資料欄定義清單 (格式為 FIELD:DATA_TYPE, FIELD:DATA_TYPE)。如果使用結構定義檔案，請勿在檔案名稱中加入副檔名。

例如：

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

如果未指定結構定義，且 --autodetect 為 false，且目的地資料表存在，則會使用目的地資料表的結構定義。

--schema_update_option=OPTION

附加資料至資料表 (在載入工作或查詢工作中) 或覆寫資料表分區時，指定目標資料表結構定義的更新方式。請使用下列其中一個值：

ALLOW_FIELD_ADDITION：允許新增欄位
ALLOW_FIELD_RELAXATION：允許將 REQUIRED 欄位放寬為 NULLABLE

重複這個標記即可指定多個結構定義更新選項。

--skip_leading_rows=NUMBER_OF_ROWS

一個整數，用來指定要在來源檔案開頭略過的資料列數量。預設為 0。

--file_set_spec_type=FILE_SET_SPEC_TYPE

指定如何解讀來源 URI。

FILE_SYSTEM_MATCH：列出物件商店中的檔案，藉此擴充來源 URI。如果未設定 FileSetSpecType，系統會預設採用此行為。
NEW_LINE_DELIMITED_MANIFEST：表示提供的 URI 是以換行符分隔的資訊清單檔案，每行一個 URI。資訊清單檔案不支援萬用字元 URI，且所有參照的資料檔案都必須與資訊清單位於同一個值區。

舉例來說，如果來源 URI 為 "gs://bucket/path/file"，且 file_set_spec_type 為 FILE_SYSTEM_MATCH，則該檔案會直接做為資料檔案。如果 file_set_spec_type 為 NEW_LINE_DELIMITED_MANIFEST，系統會將檔案中的每一行解讀為指向資料檔案的 URI。

--source_format=FORMAT

來源資料的格式，請使用下列其中一個值：

CSV
NEWLINE_DELIMITED_JSON
AVRO
DATASTORE_BACKUP (將這個值用於 Filestore)
PARQUET
ORC

--time_partitioning_expiration=SECONDS

一個整數，用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加此整數值。負數表示不會到期。

--time_partitioning_field=COLUMN_NAME

指定用來決定時間分區建立方式的欄位。如果啟用時間分區時沒有這個值，系統就會根據載入時間對資料表進行分區。

--time_partitioning_type=INTERVAL

針對資料表啟用時間分區並設定分區類型。請使用下列其中一個值：

DAY
HOUR
MONTH
YEAR

時間分區的預設分區類型為 DAY。

--use_avro_logical_types={true|false}

如果 --source_format 旗標設為 AVRO，請將此旗標設為 true，將邏輯類型轉換為對應類型 (例如 TIMESTAMP)，而非僅使用原始類型 (例如 INTEGER)。

--decimal_target_types=DECIMAL_TYPE

決定如何轉換 Decimal 邏輯型別。等同於 JobConfigurationLoad.decimalTargetTypes。重複這個標記即可指定多個目標類型。

--parquet_enum_as_string={true|false}

如果 --source_format 旗標設為 PARQUET，且您希望 BigQuery 將 Parquet ENUM 邏輯型別推斷為 STRING 值，請將此旗標設為 true。預設值為 false。

--parquet_enable_list_inference={true|false}

如果 --source_format 旗標設為 PARQUET，這個旗標會指出是否要對 Parquet LIST 邏輯型別使用結構定義推論。

--reference_file_schema_uri=URI

指定參照檔案的路徑，該檔案包含建立外部資料表時的預期資料表結構。等同於 ExternalDataConfiguration.referenceFileSchemaUri。這項標記適用於 Avro、ORC 和 PARQUET 格式。

DESTINATION_TABLE

要載入資料的資料表。

SOURCE_DATA

內含要載入資料的檔案的 Cloud Storage URI。

SCHEMA

目的地資料表的結構定義。

如要進一步瞭解如何使用 bq load 指令從 Cloud Storage 載入資料，請參閱下列文章：

如要進一步瞭解如何使用 bq load 指令載入本機來源中的資料，請參閱下列文章：

從本機檔案載入資料。

`bq ls`

使用 bq ls 指令列出集合中的物件。

劇情概要

bq ls [FLAGS] [RESOURCE]

範例

bq ls myDataset

旗標和引數

bq ls 指令會使用下列旗標和引數：

--all={true|false} 或 -a={true|false}

如要顯示所有結果，請設為 true。顯示所有使用者或所有資料集 (包括隱藏的資料集) 的工作。如果要列出移轉設定或移轉執行記錄，就不需要使用這個標記。預設值為 false。

--capacity_commitment={true|false}

如要列出容量承諾，請設為 true，並使用 --location 標記指定位置。詳情請參閱「查看已購買的承諾使用合約」。

例如：bq ls --capacity_commitment=true --location='us'

--datasets={true|false} 或 -d={true|false}

如要列出資料集，請設為 true。預設值為 false。

--filter="FILTER"

篩選所列資源，使其符合 FILTER 引數。

如果是資料集，FILTER 包含一或多個以空格分隔的三元組，格式為 labels.KEY:VALUE。如果提供多個三元組，指令只會傳回符合「所有」三元組的資料集 (也就是說，指令會使用 AND 邏輯運算子，而非 OR)。如要指定多個三元組，請用引號括住 FILTER 值。

如要根據資料集標籤篩選，請使用您套用至資料集的鍵和值。

例如：

 --filter "labels.department:marketing labels.team:sales"

如為轉移設定，請使用 dataSourceIds 做為鍵，並使用下列其中一個資料來源做為值：

amazon_s3 - Amazon S3 資料移轉
azure_blob_storage - Azure Blob 儲存體資料移轉
dcm_dt - Campaign Manager 資料移轉
google_cloud_storage - Cloud Storage 資料轉移
cross_region_copy - 資料集副本
dfp_dt- Google Ad Manager 資料轉移
displayvideo- Display & Video 360 資料轉移
google_ads - Google Ads 資料轉移
merchant_center - Google Merchant Center 資料轉移
mysql - MySQL 資料轉移
play - Google Play 資料轉移
scheduled_query - 已排定查詢的資料移轉
search_ads- Search Ads 360 資料轉移
youtube_channel - YouTube 頻道資料轉移
youtube_content_owner - YouTube 內容擁有者資料移轉
redshift - Amazon Redshift 遷移
on_premises - Teradata 遷移

例如：

   --filter labels.dataSourceIds:dcm_dt

如為轉移作業，請使用 states 做為鍵，並使用下列一或多個轉移狀態做為值：

SUCCEEDED
FAILED
PENDING
RUNNING
CANCELLED

例如：

--filter="states:FAILED"

如為職缺，請使用 states 做為鍵，並使用下列一或多個職缺狀態做為值：

RUNNING
PENDING
DONE

例如：

bq ls --jobs --filter="states:RUNNING"

bq ls --jobs --filter="states:RUNNING,PENDING"

--jobs={true|false} 或 -j={true|false}

如要列出工作，請設為 true。預設值為 false。根據預設，您會受限於 100,000 個結果。

--max_creation_time=MAX_CREATION_TIME_MS

整數，代表以毫秒為單位的 Unix 紀元時間戳記。如果搭配使用 --jobs 旗標，此旗標只會列出在時間戳記之前建立的工作。

--max_results=MAX_RESULTS or -n=MAX_RESULTS

用來表示結果數量上限的整數。預設值為 50，最大值為 1000。如果工作超過 1000 個，則可以使用 page_token 標記，透過分頁列出所有工作。

--min_creation_time=MIN_CREATION_TIME_MS

整數，代表以毫秒為單位的 Unix Epoch 時間戳記。如果搭配使用 --jobs 旗標，此旗標只會列出在時間戳記之後建立的工作。

--message_type=messageTypes:MESSAGE_TYPE

如要只列出特定類型的移轉執行記錄訊息，請指定 messageTypes:MESSAGE_TYPE。可能的值如下：

INFO
WARNING
ERROR

--models={true|false} 或 -m={true|false}

如要列出 BigQuery ML 模型，請設為 true。預設值為 false。

--page_token=TOKEN 或 -k=TOKEN

列出指定頁面符記的項目。

--projects={true|false} 或 -p={true|false}

如要顯示所有專案，請設為 true。預設值為 false。

--reservation={true|false}

如要列出特定專案和位置的所有預留項目，請設為 true。預設值為 false。搭配 --project_id 和 --location 旗標使用。

例如：

bq ls --reservation=true --project_id=myProject --location=us

--reservation_assignment={true|false}

如要列出特定專案和位置的所有保留項目指派作業，請設為 true。預設值為 false。搭配 --project_id 和 --location 旗標使用。

--routines={true|false}

如要列出指定資料集中的所有常式，請設為 true。預設值為 false。處理常式包括永久使用者定義函式、資料表函式 (搶先版) 和預存程序。

--row_access_policies

如有指定，系統會列出資料表中的所有資料列層級存取權政策。資料列層級存取權政策用於資料列層級安全性。您必須以 dataset.table 格式提供資料表名稱。

--run_attempt=RUN_ATTEMPT

請搭配 --transfer_run 旗標使用。如要列出指定移轉執行作業的所有執行嘗試，請設為 RUN_ATTEMPT_UNSPECIFIED。如要只列出最近一次的執行嘗試，請設為 LATEST。預設值為 LATEST。

--transfer_config={true|false}

如要列出指定專案和位置中的移轉設定，請設為 true。搭配 --transfer_location 和 --project_id 旗標使用。預設值為 false。

--transfer_location=LOCATION

列出指定位置中的移轉設定。移轉位置是您在建立移轉作業時所設定的。

--transfer_log={true|false}

請搭配 --transfer_run 旗標使用。如要列出指定移轉執行作業的移轉記錄訊息，請設為 true。預設值為 false。

--transfer_run={true|false}

列出指定移轉設定的移轉執行作業。

例如：

bq ls --transfer_run=true projects/myProject/locations/us/transferConfigs/12345

RESOURCE

您要列出物件的集合。資源可以是資料集、專案、保留項目或移轉設定。

如要進一步瞭解如何使用 bq ls 指令，請參閱下列文章：

`bq mk`

使用 bq mk 指令建立 BigQuery 資源。

劇情概要

bq mk TYPE_FLAG [OTHER FLAGS] [ARGS]

旗標和引數

bq mk 指令會採用 type 標記，指定要建立的資源類型，以及取決於資源類型的其他標記。

TYPE_FLAG：將下列其中一個旗標設為 true。選取要建立的資源類型。

--capacity_commitment：購買容量承諾。
--connection：建立連線。
--dataset 或 -d：建立資料集。
--materialized_view：建立具體化檢視表。
--reservation：建立預訂。
--reservation_assignment. 將資料夾、專案或機構指派給保留項目。
--table 或 -t：建立表格。
--transfer_config：建立移轉設定。
--transfer_run：為時間範圍建立轉移作業。
--view：建立檢視區塊。

bq mk 指令支援下列所有資源類型的標記：

--force={true|false} 或 -f={true|false}: 如要忽略錯誤 (如果已有名稱相同的資源)，請設為 true。如果資源已存在，則結束代碼為 0，但將此旗標設為 true 不會導致 bq mk 指令覆寫資源。預設值為 false。

視要建立的資源類型而定，bq mk 指令支援其他旗標，詳情請參閱下列章節。

`bq mk --capacity_commitment`

如要購買容量使用承諾，請將 --capacity_commitment 設為 true，並使用下列旗標：

--location=LOCATION

指定承諾的所在位置。

--plan=PLAN_TYPE

指定承諾方案類型。必須是下列其中一個值：

ANNUAL
THREE_YEAR

如果客戶使用舊版固定費率定價，也可以使用下列其中一個值：

FLEX
MONTHLY
ANNUAL

--renewal_plan=RENEWAL_TYPE

指定續訂方案類型。ANNUAL 或 THREE_YEAR 承諾方案的必要欄位。必須是下列其中一項：

ANNUAL
THREE_YEAR
NONE

如果客戶採用舊版固定費率定價，也可以使用下列其中一個值：

FLEX
MONTHLY
ANNUAL

--project_id=PROJECT_ID

指定管理該時段的專案。

--slots=NUMBER_OF_BASELINE_SLOTS

指定要購買的基準運算單元數量。

--edition=EDITION

與容量承諾相關聯的版本。必須是下列其中一個項目：

ENTERPRISE
ENTERPRISE_PLUS

詳情請參閱「購買運算單元」。

`bq mk --connection`

建立連線。支援的旗標如下：

--connection_type=CONNECTION_TYPE

連線類型，例如 Cloud SQL 連線的 CLOUD_SQL。

--properties=PROPERTIES

JSON 格式的連線專屬參數。必須指定 instanceId、database 和 type。

如果您建立 Spanner 連線並想使用 Data Boost，請加入 "useParallelism":true 和 "useDataBoost":true 配對。

--connection_credential=CONNECTION_CREDENTIAL

JSON 格式的連線憑證。必須指定 username 和 password。

--project_id=PROJECT_ID

指定連線所屬專案的 ID。

--location=LOCATION

指定連線的儲存位置。

--display_name=DISPLAY_NAME

指定連線的選用好記名稱。

--description=DESCRIPTION

指定連線的說明 (選用)。

--iam_role_id=ROLE_ID

如果是 AWS 上的 BigQuery Omni，則指定可存取資源的 IAM 角色。

請使用下列格式： "arn:aws:iam::AWS_ACCOUNT_ID:role/POLICY_NAME"，其中：

AWS_ACCOUNT_ID 是連線的 AWS IAM 使用者 ID 號碼。
POLICY_NAME 是政策名稱。

範例："arn:aws:iam::0123456789AB:policy/s3-read-role"

--tenant_id=TENANT_ID

如果是 Microsoft Azure 上的 BigQuery Omni，請指定包含 Microsoft Azure 儲存體帳戶的 Microsoft Azure 目錄租戶 ID。

CONNECTION_ID

指定連線的選用連線 ID。如果未提供連線 ID，系統會自動產生專屬 ID。連線 ID 可以包含英文字母、數字和底線。

詳情請參閱「連線簡介」。

`bq mk --dataset`

建立資料集。支援的旗標如下：

--add_tags=TAGS

指定要附加至新資料集的標記，並以半形逗號分隔。例如：556741164180/env:prod,myProject/department:sales。每個標記都必須有命名空間限定鍵名和值簡稱。

--default_kms_key=KEY

指定預設 Cloud KMS 金鑰資源 ID，用於加密資料集中的資料表資料，前提是在建立資料表或查詢時未明確提供金鑰。

--default_partition_expiration=SECONDS

一個整數，用來指定資料集中新建立分區資料表中，所有分區的預設到期時間 (以秒為單位)。分區的到期時間會設定為分區的世界標準時間日期加此整數值。如果設定此屬性，系統會覆寫資料集層級預設資料表到期時間 (如果存在)。如果您在建立或更新分區資料表時使用了 --time_partitioning_expiration 標記，則到期時間會採資料表層級的分區到期時間，而非資料集層級的預設分區到期時間。

--default_table_expiration=SECONDS

：整數，用來指定資料集中新建立資料表的預設生命週期 (以秒為單位)。到期時間會設為目前世界標準時間加此值。

--description=DESCRIPTION

指定資料集的說明。

--external_source=EXTERNAL_SOURCE

建立聯合資料集時，指定外部資料來源。

--label=KEY:VALUE

指定資料集的標籤。重複使用這個旗標即可指定多個標籤。

--location=LOCATION 或 --data_location=LOCATION

指定資料集位置。建議使用 --location 旗標，--data_location 旗標是舊版旗標。

--max_time_travel_hours=HOURS

指定資料集時間回溯期的小時數。--max_time_travel_hours 值必須是 24 的倍數 (48、72、96、120、144、168)，且介於 48 (2 天) 和 168 (7 天) 之間。如未指定此旗標，預設值為 168 小時。

--storage_billing_model=BILLING_MODEL

指定資料集的儲存空間計費模式。將 --storage_billing_model 值設為 PHYSICAL，即可在計算儲存空間費用時使用實際位元組，或設為 LOGICAL 即可使用邏輯位元組。預設為 LOGICAL。

變更資料集的計費模式後，需要 24 小時才會生效。

變更資料集的儲存空間計費模式後，必須等待 14 天，才能再次變更儲存空間計費模式。

詳情請參閱建立資料集。

`bq mk --materialized_view`

建立具體化檢視表。支援的旗標如下：

--enable_refresh={true|false}: 如要停用具體化檢視表的自動重新整理功能，請設為 false。建立具體化檢視區塊時，預設值為 true。
--refresh_interval_ms=MILLISECONDS: 指定具體化檢視區塊的重新整理間隔毫秒數。如果未指定這個旗標，已啟用重新整理的具體化檢視區塊預設重新整理間隔為 1,800,000 毫秒，也就是 30 分鐘。

詳情請參閱建立及使用具體化檢視區塊。

`bq mk --reservation`

建立具有專屬運算單元的預留項目。支援的旗標如下：

--target_job_concurrency=CONCURRENCY

指定要同時執行的查詢目標數量。預設值為 0，表示系統會根據預訂大小自動計算並行數量。詳情請參閱「使用查詢佇列」。

--ignore_idle_slots={true|false}

如要限制在此預訂項目中執行的工作只能使用分配給該預訂項目的時段，請設為 true。預設值為 false；這個預留項目中的工作可以使用其他預留項目的閒置運算單元，或未分配給任何預留項目的運算單元。詳情請參閱「閒置運算單元」。

--location=LOCATION

指定預訂的所在位置。

--project_id=PROJECT_ID

指定擁有預留項目的專案。

--slots=NUMBER_OF_BASELINE_SLOTS

指定要為這個預留項目分配的基準運算單元數量。

--edition=EDITION

與容量承諾相關聯的版本。必須是下列其中一項：

STANDARD
ENTERPRISE
ENTERPRISE_PLUS

--autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS

指派給預訂的自動調度資源運算單元數量。這等於預留項目大小上限的值，減去基準運算單元數量。僅適用於 --edition 旗標。

--max_slots=MAXIMUM_NUMBER_OF_SLOTS

預留項目可使用的運算單元數量上限。必須使用 --scaling_mode 標記 (預覽) 進行設定。

--scaling_mode=SCALING_MODE

預訂的資源調度模式。必須是下列其中一個項目：

IDLE_SLOTS_ONLY
ALL_SLOTS
AUTOSCALE_ONLY
SCALING_MODE_UNSPECIFIED

必須使用 --max_slots 標記 (預覽) 進行設定。

詳情請參閱「使用專屬運算單元建立預留項目」。

`bq mk --reservation_assignment`

將專案、資料夾或機構指派給預留項目。支援的旗標如下：

--assignee_id=ASSIGNEE_ID

指定資料夾、機構或專案的 ID。

--assignee_type=ASSIGNEE_TYPE

指定要指派給預留項目的實體類型。下列其中一項：

FOLDER
ORGANIZATION
PROJECT

--job_type=JOB_TYPE

指定要指派給預留項目的工作類型。下列其中一項：

QUERY
PIPELINE
ML_EXTERNAL
BACKGROUND

--location=LOCATION

指定預訂的所在位置。

--project_id=PROJECT_ID

指定擁有預留項目的專案。

--reservation_id=RESERVATION_ID

指定預訂 ID。

詳情請參閱「處理預留項目指派作業」。

`bq mk --table`

建立資料表。支援的旗標如下：

--add_tags=TAGS

指定要附加至新資料表的標記，並以半形逗號分隔。例如：556741164180/env:prod,myProject/department:sales。每個標記都必須有命名空間限定鍵名和值簡稱。

--clustering_fields=COLUMNS

以半形逗號分隔的清單，最多包含四個資料欄名稱，用於指定資料表分群要使用的欄位。如果指定分區，系統會先對資料表進行分區，然後使用提供的資料欄對每個分區進行分群。

--description=DESCRIPTION

指定資料表的說明。

--destination_kms_key=KEY

指定用來加密目的地資料表資料的 Cloud KMS 金鑰資源 ID。

--expiration=SECONDS

指定資料表的生命週期。如果未指定 --expiration 標記，BigQuery 會使用資料集的預設資料表生命週期建立資料表，或讓資料表永不過期。

--external_table_definition=STRING

指定用來建立外部資料表的資料表定義。

適用於 Cloud Storage 和 Google 雲端硬碟外部資料表：

--external_table_definition={PATH_TO_FILE|DEFINITION}: 這個值可以是包含資料表定義的檔案路徑 (PATH_TO_FILE)，也可以是內嵌資料表定義 (DEFINITION)。

DEFINITION 欄位的格式為 SCHEMA@FORMAT=URI。
SCHEMA 值的格式為以逗號分隔的資料欄定義清單，格式為 FIELD:DATA_TYPE, FIELD:DATA_TYPE。如果資料格式是自述式格式 (例如 Avro)，或是您使用結構定義自動偵測功能，則可以省略 SCHEMA 值。
FORMAT 值會指定資料格式，可以是下列其中一種：
- AVRO
- CSV
- DATASTORE_BACKUP (將這個值用於 Filestore)
- ICEBERG
- NEWLINE_DELIMITED_JSON
- ORC
- PARQUET

如果指定資料表定義檔案，請勿在檔案名稱中加入副檔名。

例如：

--external_table_definition=/tmp/tabledef

--external_table_definition=Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

如果是Bigtable 外部資料表，以及以 AWS 和 Azure 為基礎的 BigLake 資料表：

--external_table_definition=PATH_TO_FILE: 這個值必須是包含資料表定義的檔案路徑。

以 Cloud Storage 為基礎的 BigLake 資料表：

--external_table_definition=FORMAT=BUCKET_PATH@REGION.CONNECTION_NAME ：

FORMAT 值會指定資料格式，可以是下列其中一種：
- AVRO
- CSV
- NEWLINE_DELIMITED_JSON
- ICEBERG
- ORC
- PARQUET
BUCKET_PATH 是 Cloud Storage 中一或多個檔案的路徑，這些檔案包含 BigLake 資料表資料。您可以指定下列格式的 BUCKET_PATH：
- 單一檔案：gs://bucket_name/[folder_name/]file_name。
- 單一值區中的多個檔案： gs://bucket_name/[folder_name/]*。
- 如要從多個值區備份多個檔案： gs://mybucket1/*,gs://mybucket2/folder5/*。
  
  重要事項： 如果指定多個檔案，所有檔案都必須具有相容的結構定義。
  
  您可以使用萬用字元，限制 BigLake 表格中包含的檔案。舉例來說，如果 bucket 包含多種資料，您可以指定 gs://bucket_name/*.parquet，讓資料表只使用 PARQUET 檔案。如要進一步瞭解如何使用萬用字元，請參閱「URI 萬用字元」。
REGION 值會指定包含連線的區域或多區域。
CONNECTION_NAME 值會指定要與這個外部資料表搭配使用的雲端資源連線名稱。連線會決定要使用哪個服務帳戶從 Cloud Storage 讀取資料。

物件資料表：

--external_table_definition=BUCKET_PATH@REGION.CONNECTION_NAME ：

BUCKET_PATH 是 Cloud Storage 值區的路徑，其中包含物件表格代表的物件，格式為 gs://bucket_name/[folder_name/]*。您可以提供多個路徑來指定多個值區，例如 gs://mybucket1/*,gs://mybucket2/folder5/*。

您可以使用萬用字元，限制物件表格中包含的物件。舉例來說，如果 bucket 包含多種非結構化資料，您可以指定 gs://bucket_name/*.pdf，只針對 PDF 物件建立物件資料表。如要進一步瞭解如何使用萬用字元，請參閱「URI 萬用字元」。
REGION 值會指定包含連線的區域或多區域。
CONNECTION_NAME 值會指定要與這個外部資料表搭配使用的雲端資源連線名稱。連線會決定要使用哪個服務帳戶從 Cloud Storage 讀取資料。

--file_set_spec_type=FILE_SET_SPEC_TYPE

指定如何解讀來源 URI。

FILE_SYSTEM_MATCH：列出物件商店中的檔案，藉此擴充來源 URI。如果未設定 FileSetSpecType，系統會預設採用此行為。
NEW_LINE_DELIMITED_MANIFEST：表示提供的 URI 是以換行符分隔的資訊清單檔案，每行一個 URI。資訊清單檔案不支援萬用字元 URI，且所有參照的資料檔案都必須與資訊清單位於同一個值區。

--reference_file_schema_uri=URI

--label=KEY:VALUE

指定資料表的標籤。重複這個旗標即可指定多個標籤。

--max_staleness=INTERVAL

指定針對資料表執行的作業是否使用快取中繼資料，以及作業必須使用多新的快取中繼資料。

適用於 BigLake 資料表和物件資料表。

如要停用中繼資料快取功能，請指定 0。這是目前的預設做法。

如要啟用中繼資料快取，請使用 INTERVAL 資料類型文件所述的 Y-M D H:M:S 格式，指定 30 分鐘到 7 天之間的時間間隔值。舉例來說，如要指定 4 小時的過時間隔，請輸入 0-0 0 4:0:0。如果資料表在過去 4 小時內重新整理過，針對該資料表執行的作業就會使用快取中繼資料。如果快取中繼資料較舊，作業會改為從 Cloud Storage 擷取中繼資料。

--object_metadata=STRING

建立物件資料表時，請將這個旗標的值設為 SIMPLE。

只有在建立物件資料表時才需要。

--range_partitioning=COLUMN_NAME,START,END,INTERVAL

指定整數範圍分割區的選項，如下所示：

column_name 是用來建立整數範圍分區的資料欄。
start 是範圍分區的起始值 (含)。
end 是範圍分區的結束值 (不含)。
interval 是分區內每個範圍的寬度。

例如：

--range_partitioning=customer_id,0,10000,100

--require_partition_filter={true|false}

如要查詢提供的資料表時需要分區篩選器，請設為 true。此旗標僅適用於分區資料表。預設值為 false。

--schema={SCHEMA_FILE|SCHEMA}

範例：

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

--time_partitioning_expiration=SECONDS

一個整數，用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加此整數值。負數表示不會到期。

--time_partitioning_field=COLUMN_NAME

指定用來決定時間分區建立方式的欄位。如果啟用時間分區時沒有這個值，系統就會根據載入時間對資料表進行分區。

--time_partitioning_type=INTERVAL

針對資料表啟用時間分區並設定分區類型。請使用下列其中一個值：

DAY
HOUR
MONTH
YEAR

--use_avro_logical_types={true|false}

如果 --external_table_definition 旗標的 FORMAT 部分設為 AVRO，則這個旗標會指定是否將邏輯型別轉換為對應型別 (例如 TIMESTAMP)，而非只使用原始型別 (例如 INTEGER)。

--parquet_enable_list_inference={true|false}

如果 --external_table_definition 旗標的 FORMAT 部分設為 PARQUET，這個旗標會指定是否對 Parquet LIST 邏輯型別使用結構定義推斷。

--parquet_enum_as_string={true|false}

如果 --external_table_definition 旗標的 FORMAT 部分設為 PARQUET，則此旗標會指定是否要將 Parquet ENUM 邏輯型別推斷為 STRING 值。

詳情請參閱「建立及使用資料表」。

`bq mk --transfer_config`

建立移轉設定。支援的旗標如下：

--data_source=DATA_SOURCE: 指定資料來源。建立移轉設定時為必填欄位。請使用下列其中一個值：

amazon_s3 - Amazon S3 資料移轉
azure_blob_storage - Azure Blob 儲存體資料移轉
dcm_dt - Campaign Manager 資料移轉
google_cloud_storage - Cloud Storage 資料轉移
cross_region_copy - 資料集副本
dfp_dt- Google Ad Manager 資料轉移
displayvideo- Display & Video 360 資料轉移
google_ads - Google Ads 資料轉移
merchant_center - Google Merchant Center 資料轉移
mysql - MySQL 資料轉移
play - Google Play 資料轉移
scheduled_query - 已排定查詢的資料移轉
search_ads- Search Ads 360 資料轉移
youtube_channel - YouTube 頻道資料轉移
youtube_content_owner - YouTube 內容擁有者資料移轉
redshift - Amazon Redshift 遷移
on_premises - Teradata 遷移

--display_name=DISPLAY_NAME: 指定移轉設定的顯示名稱。
--no_auto_scheduling={true|false}: 停用這項設定的資料移轉執行作業自動排程。預設值為 false。
--params={"PARAMETER":"VALUE"} 或 -p={"PARAMETER":"VALUE"}: 以 JSON 格式指定移轉設定的參數。參數會因資料來源而有所不同。
--refresh_window_days=DAYS: 一個整數，用來指定移轉設定的更新期 (以天為單位)。預設值為 0。
--service_account_name=SERVICE_ACCOUNT: 指定要用做轉移設定憑證的服務帳戶。
--target_dataset=DATASET: 指定移轉設定的目標資料集。
--table_filter=TABLES: 只能與 google_ads 資料來源搭配使用。TABLES 參數是以半形逗號分隔的資料表清單，列出要納入轉移作業的資料表。如要排除資料表，請加上連字號 (-)。預設值包含轉移作業中的所有資料表。
--destination_kms_key=KEY: 指定用來加密目的地資料表資料的 Cloud KMS 金鑰資源 ID。

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

`bq mk --transfer_run`

使用指定的資料移轉設定，在指定時間或時間範圍內建立資料移轉執行作業。

劇情概要

bq mk --transfer_run [--run_time=RUN_TIME | --start_time=START_TIME --end_time=END_TIME] CONFIG

支援的旗標如下：

--run_time=RUN_TIME: 指定資料移轉執行作業排定時間的時間戳記。
--start_time=START_TIME: 一個時間戳記，用來針對特定範圍的資料移轉執行作業指定開始時間。
--end_time=END_TIME: 一個時間戳記，用來針對特定範圍的資料移轉執行作業指定結束時間。

時間戳記的格式為 RFC3339 UTC「Zulu」。

CONFIG 引數會指定預先存在的資料移轉設定。

範例

bq mk --transfer_run \
      --run_time=2021-01-20T17:00:00.00Z \
      projects/p/locations/l/transferConfigs/c

bq mk --transfer_run \
      --start_time=2020-12-19T16:39:57-08:00 \
      --end_time=2020-12-19T20:39:57-08:00 \
      projects/p/locations/l/transferConfigs/c

`bq mk --view`

建立檢視區塊。支援的旗標如下：

--add_tags=TAGS: 指定要附加至新檢視區塊的標記，並以半形逗號分隔。例如：556741164180/env:prod,myProject/department:sales。每個標記都必須有命名空間限定鍵名和值簡稱。
--description=DESCRIPTION: 指定檢視區塊的說明。
--expiration=SECONDS: 指定資料檢視的生命週期。如果 SECONDS 為 0，檢視畫面就不會過期。如果您未指定 --expiration 旗標，BigQuery 會使用資料集的預設資料表生命週期建立檢視區塊。
--label=KEY:VALUE: 指定檢視區塊的標籤。重複使用這個旗標即可指定多個標籤。
--use_legacy_sql={true|false}: 設為 false，即可使用 GoogleSQL 查詢建立檢視區塊。預設值取決於設定。如未指定設定，預設值為 true，使用舊版 SQL。
--view_udf_resource=FILE: 指定特定本機程式碼檔案的 Cloud Storage URI 或路徑，該檔案會在載入後立即接受評估，以做為供檢視表 SQL 查詢使用的使用者定義函式資源。重複這個標記即可指定多個檔案。

詳情請參閱建立檢視表一文。

`bq mkdef`

使用 bq mkdef 指令，以 JSON 格式針對儲存在 Cloud Storage 或 Google 雲端硬碟中的資料建立資料表定義。

劇情概要

bq mkdef [FLAGS] URI [ > FILE ]

旗標和引數

bq mkdef 指令會使用下列旗標和引數：

--autodetect={true|false}

指定是否要針對 CSV 和 JSON 資料使用結構定義自動偵測功能。預設值為 false。

--connection_id=CONNECTION_ID

用於驗證的連線資源 ID。

--hive_partitioning_mode

指定 BigQuery 讀取資料時，如何判斷分割區結構定義。支援的模式如下：

AUTO：自動推斷分區鍵名稱和類型。
STRINGS：自動推論分區鍵名稱。所有型別都會視為字串。
CUSTOM：在來源 URI 前置字串中指定分區結構定義。

預設值為 AUTO。

--hive_partitioning_source_uri_prefix

指定來源 URI 的通用前置字串。通用前置字串值是 URI 的一部分，緊接在分區索引鍵編碼之前。如果您為模式指定 CUSTOM，則必須一併識別分區結構定義。

舉例來說，請參考下列結構的檔案：

gs://bucket/path_to_table/dt=2019-06-01/country=USA/id=7/file.avro
gs://bucket/path_to_table/dt=2019-05-31/country=CA/id=3/file.avro

如果您使用 AUTO 或 STRINGS 模式，則可接受下列值：

gs://bucket/path_to_table
gs://bucket/path_to_table/

如果您使用 CUSTOM 模式，則可接受下列值：

gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:INTEGER}
gs://bucket/path_to_table/{dt:STRING}/{country:STRING}/{id:INTEGER}
gs://bucket/path_to_table/{dt:DATE}/{country:STRING}/{id:STRING}

如要進一步瞭解如何使用 bq mkdef 指令，請參閱針對外部資料來源建立資料表定義檔一文。

--ignore_unknown_values={true|false} 或 -i={true|false}

指定是否要忽略不在結構定義中的資料列值。預設值為 false。

--metadata_cache_mode=STRING

指定資料表的中繼資料快取是否自動或手動重新整理。

設為 AUTOMATIC，中繼資料快取就會以系統定義的時間間隔 (通常介於 30 到 60 分鐘之間) 重新整理。

如要依您決定的時間表重新整理中繼資料快取，請設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。

如果您使用 bq mk 指令設定 --max_staleness 旗標，就必須設定 --metadata_cache_mode 旗標。

--parquet_enable_list_inference={true|false}

如果 source_format 設為 PARQUET，這個標記會指定是否要對 Parquet LIST 邏輯型別使用結構定義推論。預設值為 false。

--parquet_enum_as_string={true|false}

如果 source_format 設為 PARQUET，這個標記會指定是否要將 Parquet ENUM 邏輯型別推斷為 STRING 值。預設值為 false。

--file_set_spec_type=FILE_SET_SPEC_TYPE

指定如何解讀來源 URI。

FILE_SYSTEM_MATCH：列出物件商店中的檔案，藉此擴充來源 URI。如果未設定 FileSetSpecType，系統會預設採用此行為。
NEW_LINE_DELIMITED_MANIFEST：表示提供的 URI 是以換行符分隔的資訊清單檔案，每行一個 URI。資訊清單檔案不支援萬用字元 URI，且所有參照的資料檔案都必須與資訊清單位於同一個值區。

--source_format=FORMAT

指定來源資料的格式。請使用下列其中一個值：

AVRO
CSV
DATASTORE_BACKUP (將這個值用於 Filestore)
GOOGLE_SHEETS
NEWLINE_DELIMITED_JSON
ORC
PARQUET

預設值為 CSV。

--use_avro_logical_types={true|false}

如果 --source_format 旗標設為 AVRO，這個旗標會指定是否將邏輯類型轉換為對應類型 (例如 TIMESTAMP)，而非只使用原始類型 (例如 INTEGER)。預設值為 false。

`bq partition`

使用 bq partition 指令，將一組含有時間單位後置字串的資料表 (例如結尾為 YYYYMMDD 的資料表，用於日期分區) 轉換為分區資料表。

劇情概要

bq partition [FLAGS] SOURCE_TABLE_BASE_NAME PARTITION_TABLE

旗標和引數

bq partition 指令會使用下列旗標和引數：

--no_clobber={true|false} 或 -n={true|false}

如要禁止覆寫現有分區，請設為 true。預設值為 false；如果分割區存在，則會遭到覆寫。

--time_partitioning_expiration=SECONDS

此整數值是用來指定系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加此整數值。負數表示不會到期。

--time_partitioning_type=INTERVAL

指定分區類型。下表列出 INTERVAL 旗標的可能值，以及每個值的預期時間單位後置字元格式：

`INTERVAL`	字尾
`HOUR`	`YYYYMMDDHH`
`DAY`	`YYYYMMDD`
`MONTH`	`YYYYMM`
`YEAR`	`YYYY`

SOURCE_TABLE_BASE_NAME

資料表群組的基本名稱，附有時間單位後置字元。

PARTITION_TABLE

目標分區資料表的名稱。

如要進一步瞭解如何使用 bq partition 指令，請參閱將日期資料分割資料表轉換成擷取時間分區資料表一節。

`bq query`

使用 bq query 指令建立查詢工作，執行指定的 SQL 查詢。

劇情概要

bq query [FLAGS] 'QUERY'

旗標和引數

bq query 指令會使用下列旗標和引數：

--allow_large_results={true|false}

如要針對舊版 SQL 查詢啟用大型目的地資料表，請設為 true。預設值為 false。

--append_table={true|false}

如要將資料附加至目的地資料表，請設為 true。預設值為 false。

--batch={true|false}

如要以批次模式執行查詢，請設為 true。預設值為 false。

--clustering_fields=COLUMNS

以逗號分隔的清單，最多包含四個資料欄名稱，用於指定要叢集查詢中的目的地資料表。如果與分區一起指定，系統會先對資料表進行分區，然後使用提供的資料欄對每個分區進行分群。

--connection_property=KEY=VALUE

鍵/值組合，可讓您指定連線層級的屬性，以自訂查詢行為。重複使用這個旗標即可指定其他屬性。

支援的連線屬性如下：

dataset_project_id：代表查詢中使用的資料集預設專案，類似於 @@dataset_project_id 系統變數。
query_label：將查詢與指定工作標籤建立關聯。如果設定，指令碼或工作階段中的所有後續查詢都會有這個標籤。如要進一步瞭解查詢標籤格式規定，請參閱JobConfiguration 資源中的 labels 欄位。
service_account：指定用於執行查詢的服務帳戶。例如：--connection_property=service_account=myserviceaccount@project.iam.gserviceaccount.com。
session_id：將查詢與指定工作階段建立關聯。
time_zone：代表執行查詢時使用的預設時區。

--continuous={true|false}

如要執行持續查詢，請設為 true。預設值為 false。

--destination_kms_key=KEY

指定用來加密目的地資料表資料的 Cloud KMS 金鑰資源 ID。

--destination_schema={PATH_TO_FILE|SCHEMA}

本機 JSON 結構定義檔路徑，或以逗號分隔的資料欄定義清單 (格式為 FIELD:DATA_TYPE, FIELD:DATA_TYPE)。

結構定義異動與查詢執行作業是分開進行。如果您指定 --destination_table 旗標，將查詢結果寫入資料表，且查詢隨後引發例外狀況，則系統可能會略過任何結構定義變更。如果發生這種情況，請檢查目的地資料表結構定義，並視需要手動更新。

--destination_table=TABLE

如有指定此旗標，查詢結果會儲存至 TABLE。請使用下列格式指定 TABLE：PROJECT:DATASET.TABLE。如果未指定 PROJECT，系統會假設為目前的專案。如果未指定 --destination_table 旗標，查詢結果會儲存至臨時資料表。

範例：

--destination_table myProject:myDataset.myTable

--destination_table myDataset.myTable

--dry_run={true|false}

如果有指定，系統就會驗證查詢 (但不執行查詢)。

--external_table_definition={TABLE::PATH_TO_FILE|TABLE::DEFINITION}

指定外部資料表查詢的資料表名稱和資料表定義。資料表定義可以是本機 JSON 結構定義檔的路徑，也可以是內嵌資料表定義。內嵌資料表定義的提供格式為 SCHEMA@SOURCE_FORMAT=CLOUD_STORAGE_URI。SCHEMA 值的格式為以逗號分隔的資料欄定義清單，格式為 FIELD:DATA_TYPE, FIELD:DATA_TYPE。如果您使用資料表定義檔，請勿在檔案名稱中加入副檔名。

例如：

--external_table_definition=myTable::/tmp/tabledef

--external_table_definition=myTable::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

重複這個標記即可查詢多個資料表。

--flatten_results={true|false}

如要禁止整併舊版 SQL 查詢結果中的巢狀和重複欄位，請設為 false。預設值為 true。

--label=KEY:VALUE

指定查詢工作的標籤。重複這個旗標即可指定多個標籤。

--max_rows=MAX_ROWS 或 -n=MAX_ROWS

一個整數，用來指定要在查詢結果中傳回的資料列數量。預設值為 100。

--maximum_bytes_billed=MAX_BYTES

一個整數，用來針對查詢指定會產生費用的位元組上限。查詢超出該上限就會失敗 (不會產生費用)。如未指定此旗標，則會將產生費用的位元組上限設為專案預設值。

--max_statement_results=VALUE

整數，用來指定查詢結果顯示的指令碼陳述式數量上限。預設值為 100。

--min_completion_ratio=RATIO

(實驗功能) 介於 0 到 1.0 之間的數字，用來指定查詢傳回結果前必須掃描的最小資料比例 (以小數表示)。如果未指定旗標，系統就會使用預設伺服器值 1.0。

--parameter={PATH_TO_FILE|PARAMETER}

包含查詢參數清單的 JSON 檔案，或格式為 NAME:TYPE:VALUE 的查詢參數。如果將名稱留空，系統會建立位置參數。如果省略 TYPE，系統會假設為 STRING 類型。NULL 指定空值。重複這個標記即可指定多個參數。

例如：

--parameter=/tmp/queryParams

--parameter=Name::Oscar

--parameter=Count:INTEGER:42

--range_partitioning=COLUMN_NAME,START,END,INTERVAL

請搭配 --destination_table 旗標使用。指定目的地資料表中整數範圍分區的選項。值是以逗號分隔的 column_name,start,end,interval 形式清單，其中

column_name 是用來建立整數範圍分區的資料欄。
start 是範圍分區的起始值 (含)。
end 是範圍分區的結束值 (不含)。
interval 是分區內每個範圍的寬度。

例如：

--range_partitioning=customer_id,0,10000,100

--replace={true|false}

如要使用查詢結果覆寫目的地資料表，請設為 true。系統會清除所有現有資料和結構定義。除非您指定 --destination_kms_key 旗標，否則系統也會移除所有 Cloud KMS 金鑰。預設值為 false。

--require_cache={true|false}

如果有指定，系統就只會在可從快取中擷取結果時執行查詢。

--require_partition_filter={true|false}

如果有指定，查詢提供的資料表時就需要分區篩選器。這個標記只能與分區資料表搭配使用。

**--reservation_id=RESERVATION

預覽。如要指定查詢執行的預訂項目。

--rpc={true|false}

如要使用 RPC-style 查詢 API (而非 REST API jobs.insert 方法)，請設為 true。預設值為 false。

--schedule="SCHEDULE"

讓查詢成為重複發生的排定查詢。您必須排定查詢的執行頻率。

範例：

--schedule="every 24 hours"

--schedule="every 3 hours"

如需排程語法的說明，請參閱「排程格式」。

--schema_update_option=OPTION

在載入工作或查詢工作中，將資料附加至資料表，或覆寫資料表分區時，指定目標資料表結構定義的更新方式。請使用下列其中一個值：

ALLOW_FIELD_ADDITION：允許新增欄位。
ALLOW_FIELD_RELAXATION：允許將 REQUIRED 欄位放寬為 NULLABLE。

重複這個標記即可指定多個結構定義更新選項。

--start_row=ROW_NUMBER 或 -s=ROW_NUMBER

一個整數，用來指定要在查詢結果中傳回的第一個資料列。預設值為 0。

--target_dataset=DATASET

如果指定此旗標時搭配使用 --schedule，系統會更新排定查詢的目的地資料集。查詢必須是 DDL 或 DML。

--time_partitioning_expiration=SECONDS

請搭配 --destination_table 旗標使用。這是一個整數，用來指定系統應在何時刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加整數值。負數表示不會到期。

--time_partitioning_field=COLUMN_NAME

請搭配 --destination_table 旗標使用。指定時間分區的分區資料欄。如果啟用時間分區時沒有這個值，系統就會根據擷取時間對資料表進行分區。

--time_partitioning_type=INTERVAL

請搭配 --destination_table 旗標使用。指定目的地資料表的分區類型。請使用下列其中一個值：

DAY
HOUR
MONTH
YEAR

--udf_resource=FILE

這個旗標僅適用於舊版 SQL 查詢。指定 Cloud Storage URI 或本機檔案路徑，其中包含舊版 SQL 查詢要使用的使用者定義函式資源。重複這個標記即可指定多個檔案。

--use_cache={true|false}

如要禁止快取查詢結果，請設為 false。預設值為 true。

--use_legacy_sql={true|false}

如要執行 GoogleSQL 查詢，請設為 false。預設值取決於設定。如未指定設定，預設值為 true，指令會使用舊版 SQL。

--job_timeout_ms={string (Int64Value)}

指定查詢執行時間上限 (以毫秒為單位)。如果超過這個時間限制，BigQuery 會嘗試停止工作。

QUERY

要執行的查詢。您可以透過下列其中一種方法指定查詢：

指定含有查詢內容的字串。

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

以下範例顯示 Bash 中的一般做法，也就是使用雙引號表示查詢中的字串常值，然後將查詢本身括在單引號中：
```
'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
```
如果從其他位置複製查詢，也必須移除查詢中的所有註解。
傳遞含有查詢的 SQL 指令碼。以下範例說明如何在 Bash 殼層中傳遞 SQL 指令碼：
```
bq query --use_legacy_sql=false < query.sql
```

如要進一步瞭解如何使用 bq query 指令，請參閱執行查詢一文。

`bq remove-iam-policy-binding`

使用 bq remove-iam-policy-binding 指令擷取資源的 IAM 政策，並從政策中移除繫結，一次完成。資源可以是資料表或檢視區塊。

這個指令可取代下列三步驟程序：

使用 bq get-iam-policy 指令擷取政策檔案 (JSON 格式)。
編輯政策檔案。
使用 bq set-iam-policy 指令更新政策，但不更新繫結。

劇情概要

bq remove-iam-policy-binding FLAGS --member=MEMBER_TYPE:MEMBER --role=ROLE RESOURCE

旗標和引數

bq remove-iam-policy-binding 指令可使用下列旗標和引數：

--member=MEMBER_TYPE:MEMBER

MEMBER_TYPE 值會指定身分與存取權管理政策繫結中的成員類型。請使用下列其中一個值：

user
serviceAccount
group
domain

MEMBER 值會指定 IAM 政策繫結中成員的電子郵件地址或網域。

--role=ROLE

這是必要旗標，指定 IAM 政策繫結的角色部分。--role 旗標必須搭配 --member 旗標。一組 --member 和 --role 標記等於一個繫結。

--table={true|false} 或 -t={true|false}

(選用步驟) 如要從資料表或檢視區塊的 IAM 政策中移除繫結，請設為 true。預設值為 false。

RESOURCE 是您要移除政策繫結的資料表或檢視區塊。

詳情請參閱 IAM 政策參考資料。

`bq rm`

使用 bq rm 指令刪除 BigQuery 資源。

劇情概要

bq rm [FLAGS] RESOURCE

旗標和引數

bq rm 指令會使用下列旗標和引數：

--capacity_commitment={false|true}: 如要刪除容量承諾，請設為 true，使用 --location 標記指定要移除的承諾位置，並將 RESOURCE 替換為要移除的承諾 ID。
--dataset={true|false} 或 -d={true|false}: 如要刪除資料集，請設為 true。預設值為 false。
--force={true|false} 或 -f={true|false}: 如要刪除資源，且不想收到提示，請設為 true。預設值為 false。
--job={true|false} 或 -j={true|false}: 如要刪除工作，請設為 true。預設值為 false。
--model={true|false} 或 -m={true|false}: 如要刪除 BigQuery ML 模型，請設為 true。預設值為 false。
--recursive={true|false} 或 -r{true|false}: 如要刪除資料集和當中的任何資料表、資料表資料或模型，請設為 true。預設值為 false。
--reservation={true|false}: 如要刪除預訂，請設為 true。預設值為 false。
--reservation_assignment={true|false}: 如要刪除保留項目指派作業，請設為 true。預設值為 false。
--routine={true|false}: 如要刪除日常安排，請設為 true。預設值為 false。常式可以是永久性使用者定義函式、資料表函式 (搶先版) 或預存程序。
--table={true|false} 或 -t={true|false}: 如要刪除資料表或檢視表，請設為 true。預設值為 false。
--transfer_config={true|false}: 如要刪除移轉設定，請設為 true。預設值為 false。
RESOURCE: 要移除的資源。

如要進一步瞭解如何使用 bq rm 指令，請參閱下列文章：

`bq set-iam-policy`

使用 bq set-iam-policy 指令指定或更新資源的 IAM 政策。資源可以是資料表、檢視區塊或時段預訂。設定政策後，新政策會列印到 stdout。政策採用 JSON 格式。

更新後政策中的 etag 欄位必須與目前政策的 etag 值相符，否則更新會失敗。這項功能可避免同時更新。

您可以使用 bq get-iam-policy 指令，取得資源的現行政策和 etag 值。

劇情概要

bq set-iam-policy [FLAGS] RESOURCE FILE_NAME

範例

bq set-iam-policy myDataset.myTable policy.json

bq set-iam-policy --reservation myReservation policy.json

旗標和引數

bq set-iam-policy 指令可使用下列旗標和引數。

--table={true|false} 或 -t={true|false}: 選用。如要設定資料表或檢視區塊的 IAM 政策，請設為 true。預設值為 false。
--reservation={true|false}: 如要設定預訂項目的 IAM 政策，請設為 true (預覽版)。預設值為 false。使用這個旗標時，RESOURCE 會視為預訂 ID。預留項目可選擇性加上專案和位置前置字元：myProject:myLocation.myReservation。

RESOURCE 是您要更新政策的資料表或檢視區塊。

FILE_NAME 是包含 JSON 格式政策的檔案名稱。

如要進一步瞭解 bq set-iam-policy 指令，請參閱「使用 IAM 控管資源存取權」。

`bq show`

使用 bq show 指令顯示資源相關資訊。

劇情概要

bq show [FLAGS] [RESOURCE]

旗標和引數

bq show 指令會使用下列旗標和引數：

--assignee_id=ASSIGNEE

與 --reservation_assignment 標記搭配使用時，可指定資料夾、機構或專案的 ID。使用 --assignee_type 標記指定要顯示的指派對象類型。

--assignee_type=TYPE

與 --reservation_assignment 標記搭配使用時，可指定要顯示的實體類型。請使用下列其中一個值：

FOLDER
ORGANIZATION
PROJECT

--connection={true|false}

如要顯示連線相關資訊，請設為 true。預設值為 false。詳情請參閱「查看連線資源」。

--dataset={true|false} 或 -d={true|false}

如要顯示資料集相關資訊，請設為 true。預設值為 false。

--encryption_service_account={true|false}

如要顯示專案的加密服務帳戶 (如果存在)，或建立加密服務帳戶 (如果本來不存在)，請設為 true。預設值為 false。搭配 --project_id 旗標使用。

--job={true|false} 或 -j={true|false}

如要顯示工作相關資訊，請設為 true。預設值為 false。

--job_type=JOB_TYPE

與 --reservation_assignment 旗標搭配使用時，可指定要顯示的保留項目指派作業工作類型。請使用下列其中一個值：

QUERY
PIPELINE
ML_EXTERNAL

--model={true|false} 或 -m={true|false}

如要顯示 BigQuery ML 模型相關資訊，請設為 true。預設值為 false。

--reservation={true|false}

如要顯示預訂資訊，請設為 true。預設值為 false。

--reservation_assignment={true|false}

設為 true 時，指令會顯示指定資料夾、機構或專案的保留項目指派作業。如有明確指派目標資源，這項指令會顯示這些指派項目；否則會顯示從上層資源繼承的指派項目。舉例來說，專案可能會沿用上層資料夾的指派項目。使用這個旗標時，適用 --job_type、--assignee_type 和 --assignee_id 旗標。預設值為 false。

--routine={true|false}

如要顯示日常安排的相關資訊，請設為 true。預設值為 false。處理常式可以是永久使用者定義函式、資料表函式 (搶先版) 或預存程序。

--schema={true|false}

如要只顯示資料表的結構定義，請設為 true。預設值為 false。

--transfer_config={true|false}

如要顯示移轉設定的相關資訊，請設為 true。預設值為 false。

--transfer_run={true|false}

如要顯示移轉執行作業的相關資訊，請設為 true。預設值為 false。

--view={true|false}

如要顯示檢視表相關資訊，請設為 true。預設值為 false。

RESOURCE

要顯示資訊的資源。

如要進一步瞭解如何使用 bq show 指令，請參閱下列文章：

`bq update`

使用 bq update 指令變更資源。

劇情概要

bq update [FLAGS] [RESOURCE]

旗標和引數

bq update 指令會使用下列旗標和引數：

--add_tags=TAGS

僅適用於資料集和資料表。指定要附加至資源的標記，並以半形逗號分隔。例如：556741164180/env:prod,myProject/department:sales。每個標記都必須有命名空間限定鍵名和值簡稱。

--autoscale_max_slots=NUMBER_OF_AUTOSCALING_SLOTS

指派給預訂的自動調度資源運算單元數量。這等於預留項目大小上限的值，減去基準運算單元數量。只有在加上 --reservation 旗標，且保留項目是使用版本建立時，才能使用這項功能。

--capacity_commitment={true|false}

如要更新容量使用承諾，請設為 true。請搭配 --merge、--plan、--renewal_plan、--split 和 --slots 旗標使用這個旗標。

--clear_all_tags={true|false}

僅適用於資料集和資料表。如要清除資源中的所有標記，請設為 true。預設值為 false。

--clear_label=KEY:VALUE

從資源中移除標籤。請使用 KEY:VALUE 格式指定要移除的標籤。重複使用這個旗標即可移除多個標籤。

--clustering_fields=COLUMNS

更新資料表的叢集規格。COLUMNS 值是以半形逗號分隔的資料欄名稱清單，用於叢集。如要移除叢集，請將 COLUMNS 設為 "" (空字串)。詳情請參閱「修改叢集規格」。

--target_job_concurrency=CONCURRENCY

與 --reservation 旗標搭配使用時，可指定要同時執行的查詢目標數量。預設值為 0，表示系統會根據預留大小自動設定並行數量。詳情請參閱「使用查詢佇列」。

--dataset={true|false} 或 -d={true|false}

如要更新資料集，請設為 true。預設值為 false。

--default_kms_key=KEY

指定用來加密資料集中資料表資料的預設 Cloud KMS 金鑰資源 ID。如果沒有為資料表建立或查詢提供明確的金鑰，系統就會使用預設金鑰。

--default_partition_expiration=SECONDS

一個整數，用來指定資料集中新建立分區資料表中，所有分區的預設到期時間 (以秒為單位)。此標記沒有最小值。

分區的到期時間會設定為分區的世界標準時間日期加此整數值。如果設定此屬性，系統會使用此整數覆寫資料集層級的預設資料表到期時間 (如果存在)。如果在建立或更新分區資料表時使用 --time_partitioning_expiration 旗標，則資料表層級的分區到期時間會覆寫資料集層級的預設分區到期時間。指定 0 可移除現有的到期時間。

--default_table_expiration=SECONDS

一個整數，用來更新資料集中新建立資料表的預設生命週期 (以秒為單位)。到期時間會設為目前世界標準時間加此值。指定 0 可移除現有的到期時間。

--description=DESCRIPTION

更新資料集、資料表、資料表快照、模型或檢視表的說明。

--destination_reservation_id=RESERVATION_ID

與 --reservation_assignment 標記搭配使用時，可將現有的預留項目指派作業移至指定的預留項目。值為目的地預訂 ID。詳情請參閱「將指派項目移至其他預留項目」。

--display_name=DISPLAY_NAME

更新移轉設定的顯示名稱。

--etag=ETAG

做為篩選器；只有在資源的 ETag 與 ETAG 引數中指定的字串相符時，才會更新資源。

--expiration SECONDS

如要更新資料表、模型、資料表快照或檢視表的到期時間，請加入這個旗標。將 SECONDS 替換為更新時間到有效期限的秒數。如要移除資料表、模型、資料表快照或檢視表的到期時間，請將 SECONDS 引數設為 0。

--external_table_definition={TABLE::PATH_TO_FILE|TABLE::DEFINITION}

使用指定資料表定義更新外部資料表。資料表定義可以是本機 JSON 資料表定義檔的路徑，也可以是格式為 SCHEMA@SOURCE_FORMAT=CLOUD_STORAGE_URI 的內嵌資料表定義。SCHEMA 值是以逗號分隔的資料欄定義清單，格式為 FIELD:DATA_TYPE, FIELD:DATA_TYPE。如果您使用資料表定義檔，請勿在檔案名稱中加入副檔名。

例如：

--external_table_definition=myTable::/tmp/tabledef

--external_table_definition=myTable::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv

--ignore_idle_slots={true|false}

請搭配 --reservation 旗標使用。如要限制在指定預留項目中執行的工作，只能使用分配給該預留項目的時段，請設為 true。預設值為 false；指定預留項目中的工作可以使用其他預留項目中的閒置運算單元，或未分配給任何預留項目的運算單元。詳情請參閱「閒置運算單元」。

--max_staleness=INTERVAL

指定 INTERVAL 值，決定查詢具體化檢視區塊或外部資料表時允許的最大陳舊程度。預設值為 0-0 0 0:0:0。

例如：

1 天：0-0 1 0:0:0
1 小時：0-0 0 1:0:0

如要使用這個旗標，您必須使用 --external_table_definition 旗標指定資料表定義。

--max_time_travel_hours=HOURS

指定資料集時間回溯期的小時數。--max_time_travel_hours 值必須是 24 的倍數 (48、72、96、120、144、168)，且介於 48 (2 天) 和 168 (7 天) 之間。

--merge={true|false}

如要合併兩個容量承諾，請將 --merge 設為 true。將 --capacity_commitment 標記設為 true，使用 --location 標記指定要合併的約定位置，並將 RESOURCE 替換為要合併的兩個約定 ID，以半形逗號分隔。詳情請參閱「合併兩項承諾」。

--metadata_cache_mode=METADATA_CACHE_MODE

為具有連線的外部資料表啟用中繼資料快取。請使用下列其中一個值：

AUTOMATIC
MANUAL

指定 AUTOMATIC，自動重新整理快取的中繼資料。指定 MANUAL停止自動重新整理。如要使用這個標記，您必須使用 --external_table_definition 標記指定表格定義。

--model={true|false} 或 -m={true|false}

如要更新 BigQuery ML 模型的中繼資料，請設為 true。預設值為 false。

--params={"PARAMETER":"VALUE"} or -p={"PARAMETER":"VALUE"}

更新移轉設定的參數。參數會因資料來源而異。詳情請參閱 BigQuery 資料移轉服務簡介一文。

--plan=PLAN

與 --capacity_commitment 旗標搭配使用時，可將容量承諾轉換為指定較長期限的承諾方案。將 PLAN 替換為下列其中一個值：

ANNUAL
THREE_YEAR

--refresh_window_days=DAYS

一個整數，用來指定移轉設定的更新期 (以天為單位)。

--remove_tags=TAG_KEYS

僅適用於資料集和資料表。指定要從資源中移除的標記，並以半形逗號分隔，例如 556741164180/env,myProject/department。每個標記鍵都必須有命名空間鍵名。

--renewal_plan=PLAN

搭配 --capacity_commitment 旗標使用時，可更新年約容量承諾的續約方案。將 PLAN 替換為下列其中一個值：

ANNUAL
THREE_YEAR
NONE

如果客戶採用舊版固定費率定價，也可以使用下列其中一個值：

FLEX
MONTHLY
ANNUAL

--reservation={true|false}

指定是否要更新預訂。預設值為 false。

--reservation_assignment={true|false}

指定是否要更新預訂指派項目。預設值為 false。

--schema={SCHEMA_FILE|SCHEMA}

例如：

--schema=/tmp/tabledef

--schema=Region:STRING,Quarter:STRING,Total_sales:INTEGER

--service_account_name=SERVICE_ACCOUNT

指定要用做移轉設定憑證的服務帳戶。

--set_label=KEY:VALUE

指定要更新的標籤。如要更新多個標籤，請重複使用這個標記。

--slots=NUMBER_OF_BASELINE_SLOTS

與 --capacity_commitment 和 --split 旗標搭配使用時，可指定要從現有容量承諾分割為新承諾的基準運算單元數量。將 RESOURCE 替換為要分割的約期 ID。

搭配 --reservation 旗標使用時，可更新預訂中的空位數。

--source=FILE

包含更新資源用酬載的本機 JSON 檔案路徑。例如，您可以使用此旗標指定 JSON 檔案，其中包含具有已更新 access 屬性的資料集資源。該檔案可用來覆寫資料集的存取權控管。JSON 檔案不得包含位元組順序標記 (BOM)。

--split={true|false}

設為 true 並搭配 --capacity_commitment 旗標使用時，表示您要分割現有的容量承諾。使用 --location 標記指定要分割的約定位置，並使用 --slots 標記指定要分割的時段數量。將 RESOURCE 替換為要分割的約定 ID。詳情請參閱「分割承諾」。

--storage_billing_model=BILLING_MODEL

指定資料集的儲存空間計費模式。將 --storage_billing_model 值設為 PHYSICAL，即可在計算儲存空間費用時使用實際位元組；設為 LOGICAL 則可使用邏輯位元組。

變更資料集的計費模式後，需要 24 小時才會生效。

變更資料集的儲存空間計費模式後，必須等待 14 天，才能再次變更儲存空間計費模式。

--table={true|false} 或 -t={true|false}

指定是否要更新資料表。預設值為 false。

--target_dataset=DATASET

如有指定，系統會更新移轉設定的目標資料集。

--time_partitioning_expiration=SECONDS

一個整數，用來更新系統應在經過多少時間後刪除時間分區 (以秒為單位)。到期時間為分區的世界標準時間日期加此整數值。負數表示不會到期。

--time_partitioning_field=COLUMN_NAME

更新用來決定時間分區建立方式的欄位。如果啟用時間分區時沒有這個值，系統就會根據載入時間對資料表進行分區。

--time_partitioning_type=INTERVAL

指定分割類型。請使用下列其中一個值：

DAY
HOUR
MONTH
YEAR

您無法變更現有資料表的分區類型。

--transfer_config={true|false}

指定是否要更新移轉設定。預設值為 false。

--update_credentials={true|false}

指定是否要更新移轉設定憑證。預設值為 false。

--use_legacy_sql={true|false}

設為 false，即可將檢視表的 SQL 查詢從舊版 SQL 更新為 GoogleSQL。預設值取決於設定。如未指定設定，預設值為 true，查詢會使用舊版 SQL。

--vertex_ai_model_id=VERTEX_AI_MODEL_ID

如有指定，系統會更新在 Vertex AI Model Registry 中註冊的 BigQuery ML 模型 ID。

--view=QUERY

如有指定，系統會更新檢視表的 SQL 查詢。

--view_udf_resource=FILE

更新特定本機程式碼檔案的 Cloud Storage URI 或路徑，該檔案會在載入後立即接受評估，以做為供檢視表 SQL 查詢使用的使用者定義函式資源。重複這個標記即可指定多個檔案。

RESOURCE

要更新的資源。

如要進一步瞭解如何使用 bq update 指令，請參閱下列文章：

`bq version`

使用 bq version 指令顯示 bq 指令列工具的版本號碼。

劇情概要

bq version

`bq wait`

使用 bq wait 指令，等待指定秒數，讓工作完成。如未指定工作，指令會等待目前工作完成。

劇情概要

bq wait [FLAGS] [JOB] [SECONDS]

範例

bq wait

bq wait --wait_for_status=RUNNING 12345 100

旗標和引數

bq wait 指令會使用下列旗標和引數：

--fail_on_error={true|false}

如要讓系統在等候時間內工作完成時傳回成功，即使工作失敗也一樣，請設為 false。預設值為 true。過了等候時間後，如果工作仍在執行，或者工作已完成但失敗，指令會退出並顯示錯誤訊息。

--wait_for_status=STATUS

如有指定，系統會等到出現特定工作狀態才會退出工作。請使用下列其中一個值：

PENDING
RUNNING
DONE

預設值為 DONE。

JOB

指定要等待的工作。您可以使用 bq ls --jobs myProject 指令找出工作 ID。

SECONDS

指定等待工作完成的秒數上限。如果您輸入 0，這個指令會輪詢工作完成狀態並立即傳回結果。如果您未指定整數值，指令會等到工作完成為止。

bq 指令列工具參考資料

使用 bq 指令列工具的方法

指令格式

指定旗標的值

在引數中指定 BigQuery 資源

如何執行指令

在指令碼中執行指令

使用服務帳戶

設定指令列旗標的預設值

如何將旗標加入 .bigqueryrc

CLI 說明

排解 CLI 指令問題

通用標記

已淘汰的通用旗標

指令

bq add-iam-policy-binding

劇情概要

範例

旗標和引數

bq cancel

劇情概要

範例

旗標和引數

bq cp

劇情概要

範例

旗標和引數

bq extract

劇情概要

範例

旗標和引數

bq get-iam-policy

劇情概要

範例

旗標和引數

bq head

劇情概要

範例

旗標和引數

bq help

劇情概要

旗標和引數

bq insert

劇情概要

範例

旗標和引數

bq load

劇情概要

範例

旗標和引數

bq ls

劇情概要

範例

旗標和引數

bq mk

劇情概要

旗標和引數

bq mk --capacity_commitment

bq mk --connection

bq mk --dataset

bq mk --materialized_view

bq mk --reservation

bq mk --reservation_assignment

bq mk --table

bq mk --transfer_config

bq mk --transfer_run

劇情概要

範例

bq mk --view

bq mkdef

劇情概要

旗標和引數

bq partition

劇情概要

旗標和引數

bq query

劇情概要

旗標和引數

bq remove-iam-policy-binding

劇情概要

如何將旗標加入 `.bigqueryrc`

`bq add-iam-policy-binding`

`bq cancel`

`bq cp`

`bq extract`

`bq get-iam-policy`

`bq head`

`bq help`

`bq insert`

`bq load`

`bq ls`

`bq mk`

`bq mk --capacity_commitment`

`bq mk --connection`

`bq mk --dataset`

`bq mk --materialized_view`

`bq mk --reservation`

`bq mk --reservation_assignment`

`bq mk --table`

`bq mk --transfer_config`

`bq mk --transfer_run`

`bq mk --view`

`bq mkdef`

`bq partition`

`bq query`

`bq remove-iam-policy-binding`

`bq rm`

`bq set-iam-policy`

`bq show`

`bq update`

`bq version`

`bq wait`