寫入查詢結果
本文件說明如何將查詢結果寫入暫時或永久資料表。
暫時性與永久性資料表
BigQuery 會將所有查詢結果儲存至永久或臨時資料表:
BigQuery 會使用臨時表格,快取未寫入永久表格的查詢結果。系統會在特殊資料集中建立資料表,並隨機命名。您也可以在多陳述式查詢和工作階段中建立暫時性資料表,供您使用。您不需要為臨時快取查詢結果資料表付費。您需要為未快取查詢結果的臨時資料表付費。
查詢完成後,這個臨時表最多會存在 24 小時。如要查看資料表結構和資料,請前往 BigQuery 控制台,按一下「個人記錄」,然後選擇建立臨時資料表的查詢。然後在「Destination table」列中,按一下「Temporary table」。
只有建立查詢工作的使用者或服務帳戶,才能存取臨時表資料。
您無法共用臨時資料表,也無法透過任何一種標準清單或其他資料表操縱方法來顯示。系統會在與要查詢的資料表相同的區域中建立臨時資料表。
永久資料表可以是您有權存取的任何資料集中之新資料表或現有資料表。如果您將查詢結果寫入新資料表,就必須支付資料的儲存費用。當您將查詢結果寫入永久資料表時,所查詢的資料表必須與包含目標資料表的資料集位於相同位置。
啟用受限網域機構政策時,您無法將查詢結果儲存至暫存資料表。暫時停用網域限制機構政策,執行查詢,然後重新啟用政策。或者,您也可以將查詢結果儲存在目的地資料表中。
所需權限
如要將查詢結果寫入資料表,您至少必須具備下列權限:
bigquery.tables.create
:建立新資料表的權限bigquery.tables.updateData
:將資料寫入新資料表、覆寫資料表或將資料附加至資料表bigquery.jobs.create
:執行查詢工作
您可能還需要其他權限 (例如 bigquery.tables.getData
),才能存取您要查詢的資料。
以下是同時具有 bigquery.tables.create
和 bigquery.tables.updateData
權限的預先定義 IAM 角色:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
以下是具有 bigquery.jobs.create
權限的預先定義 IAM 角色:
bigquery.user
bigquery.jobUser
bigquery.admin
此外,當具備 bigquery.datasets.create
權限的使用者建立資料集時,會獲得該資料集的 bigquery.dataOwner
存取權。bigquery.dataOwner
存取權可讓使用者在資料集裡建立及更新資料表。
如要進一步瞭解 BigQuery 中的 IAM 角色和權限,請參閱「預先定義的角色與權限」一文。
將查詢結果寫入永久資料表
將查詢結果寫入永久資料表時,您可以建立新資料表、將結果附加到現有資料表,或覆寫現有資料表。
寫入查詢結果
請按照下列程序,將查詢結果寫入永久資料表。為協助您控管費用,您可以在執行查詢前預覽資料。
主控台
在 Google Cloud 控制台開啟「BigQuery」頁面。
在「Explorer」面板中展開專案並選取資料集。
輸入有效的 SQL 查詢。
按一下「More」,然後選取「Query settings」。
選取「Set a destination table for query results」(為查詢結果設定目標資料表) 選項。
在「Destination」(目的地) 部分,選取要建立資料表的「Dataset」(資料集),然後選擇「Table ID」(資料表 ID)。
在「Destination table write preference」(目標資料表寫入偏好設定) 區段,選擇下列其中一項:
- [Write if empty] (空白時寫入):僅在資料表空白時將查詢結果寫入資料表。
- [Append to table] (附加到資料表中):將查詢結果附加到現有的資料表。
- [Overwrite table] (覆寫資料表):使用查詢結果覆寫名稱相同的現有資料表。
選用:在「Data location」(資料位置),選擇您的位置。
如要更新查詢設定,請按一下「儲存」。
按一下「執行」。這會建立一個查詢工作,將查詢結果寫入您指定的資料表。
如果您在執行查詢前忘記指定目標資料表,也可以按一下編輯器上方的 「儲存結果」按鈕,將快取結果資料表複製至永久性資料表。
SQL
以下範例使用 CREATE TABLE
陳述式,根據公開 bikeshare_trips
資料表中的資料建立 trips
資料表:
前往 Google Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
CREATE TABLE mydataset.trips AS ( SELECT bike_id, start_time, duration_minutes FROM bigquery-public-data.austin_bikeshare.bikeshare_trips );
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
詳情請參閱「從現有資料表建立新資料表」。
bq
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
輸入
bq query
指令並指定--destination_table
旗標,根據查詢結果建立永久性資料表。指定use_legacy_sql=false
旗標以使用 GoogleSQL 語法。如要將查詢結果寫入不在預設專案內的資料表,請使用下列格式將專案 ID 新增至資料集名稱:project_id:dataset
。選用:提供
--location
旗標,並將值設為您的位置。如要控管現有目標資料表的寫入配置,請指定下列其中一種選用標記:
--append_table
:如果目標資料表已存在,查詢結果會附加至該資料表。--replace
:如果目標資料表已存在,查詢結果會覆寫該資料表。bq --location=location query \ --destination_table project_id:dataset.table \ --use_legacy_sql=false 'query'
更改下列內容:
location
是用於處理查詢的位置名稱。--location
是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設為asia-northeast1
。您可以使用.bigqueryrc
檔案設定位置的預設值。project_id
是您的專案 ID。dataset
是您要寫入查詢結果的資料表所屬資料集的名稱。table
是您要寫入查詢結果的資料表名稱。query
是採用 GoogleSQL 語法的查詢。如未指定任何寫入配置旗標,預設動作是僅在資料表空白時,才將結果寫入資料表。如果資料表存在且非空白,系統會傳回下列錯誤:
BigQuery error in query operation: Error processing job project_id:bqjob_123abc456789_00000e1234f_1: Already Exists: Table project_id:dataset.table
。範例:
輸入下列指令,將查詢結果寫入
mydataset
中名為mytable
的目標資料表。該資料集位於預設專案中。由於您未在指令中指定任何寫入配置旗標,因此資料表必須為新資料表或空白資料表。否則,系統會傳回Already exists
錯誤。查詢會從美國名稱資料公開資料集擷取資料。bq query \ --destination_table mydataset.mytable \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
輸入下列指令,使用查詢結果覆寫
mydataset
中名為mytable
的目標資料表。該資料集位於預設專案中。該指令使用--replace
旗標來覆寫目標資料表。bq query \ --destination_table mydataset.mytable \ --replace \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
輸入下列指令,將查詢結果附加至
mydataset
中名為mytable
的目標資料表。該資料集位於my-other-project
,而非預設專案。指令使用--append_table
旗標將查詢結果附加至目標資料表。bq query \ --append_table \ --use_legacy_sql=false \ --destination_table my-other-project:mydataset.mytable \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
各範例的輸出內容如下。為了方便閱讀,以下僅顯示部分輸出內容。
Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE +---------+--------+ | name | number | +---------+--------+ | Robert | 10021 | | John | 9636 | | Robert | 9297 | | ... | +---------+--------+
API
如要將查詢結果儲存至永久資料表,請呼叫 jobs.insert
方法,設定 query
工作,然後加入 destinationTable
屬性的值。如要控管現有目標資料表的寫入配置,請設定 writeDisposition
屬性。
如要控管查詢工作的處理位置,請在工作資源的 jobReference
區段中指定 location
屬性。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要將查詢結果儲存至永久資料表,請在 QueryJobConfiguration 中將目標資料表設為所要的 TableId。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要將查詢結果儲存至永久性資料表,請建立 QueryJobConfig,並將目的地設為所需的 TableReference。接著,將工作設定傳送至查詢方法。寫入大型查詢結果
通常,查詢都有回應大小上限。如果您打算執行可能會傳回較大結果的查詢,您可以執行下列任一操作:
- 在 GoogleSQL 中,指定查詢結果的目標資料表。
- 在舊版 SQL 中,指定目標資料表並設定
allowLargeResults
選項。
如果您指定的目標資料表會寫入大型查詢結果,則必須支付資料的儲存費用。
限制
在舊版 SQL 中,寫入大型結果受到下列限制:
- 您必須指定目標資料表。
- 不能指定頂層
ORDER BY
、TOP
或LIMIT
子句。這麼做會抵銷使用allowLargeResults
的好處,因為再也無法平行計算查詢輸出。 - 窗型函式只有在合併使用
PARTITION BY
子句時才能傳回大型查詢結果。
使用舊版 SQL 寫入大型結果
如要使用舊版 SQL 寫入大型結果集:
主控台
在 Google Cloud 控制台開啟「BigQuery」頁面。
按一下 [Compose new query] (撰寫新查詢)。
在「Query editor」(查詢編輯器) 文字區域中輸入有效的 SQL 查詢。請使用
#legacySQL
前置字串,或確認您已在查詢設定中勾選 [Use Legacy SQL] (使用舊版 SQL)。按一下 [More] (更多),然後選取 [Query settings] (查詢設定)。
在「Destination」(目的地) 部分,勾選 [Set a destination table for query results] (為查詢結果設定目標資料表)。
在「Dataset」(資料集) 部分,選擇要儲存資料表的資料集。
在「Table ID」(資料表 ID) 欄位中,輸入資料表名稱。
如果您要將大型結果集寫入現有資料表,可以使用「Destination table write preference」(目標資料表寫入偏好設定) 選項來控管目標資料表的寫入配置:
- Write if empty:僅在資料表空白時將查詢結果寫入資料表。
- 附加到資料表:將查詢結果附加到現有資料表。
- 覆寫資料表:使用查詢結果覆寫名稱相同的現有資料表。
在「Results Size」(結果大小) 部分,勾選「Allow large results (no size limit)」(允許大型結果 (無大小上限))。
選用:針對「Data location」(資料位置),選擇資料的位置。
按一下 [Save] (儲存) 以更新查詢設定。
按一下 [Run] (執行)。這會建立一個查詢工作,將大型結果集寫入您指定的資料表。
bq
使用 --allow_large_results
旗標搭配 --destination_table
旗標,建立目標資料表來保存大型結果集。因為 --allow_large_results
選項只適用於舊版 SQL,您也必須指定 --use_legacy_sql=true
標記。如要將查詢結果寫入不在預設專案內的資料表,請使用下列格式將專案 ID 新增至資料集名稱:PROJECT_ID:DATASET
。加上 --location
旗標,並將旗標的值設為您的位置。
如要控管現有目標資料表的寫入配置,請指定以下其中一種選用旗標:
--append_table
:如果目標資料表已存在,查詢結果會附加至該資料表。--replace
:如果目標資料表已存在,查詢結果會覆寫該資料表。
bq --location=location query \ --destination_table PROJECT_ID:DATASET.TABLE \ --use_legacy_sql=true \ --allow_large_results "QUERY"
更改下列內容:
LOCATION
是用於處理查詢的位置名稱。--location
是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設為asia-northeast1
。您可以使用.bigqueryrc
檔案設定位置的預設值。PROJECT_ID
是您的專案 ID。DATASET
是您要寫入查詢結果的資料表所屬資料集的名稱。TABLE
是您要寫入查詢結果的資料表名稱。QUERY
是舊版 SQL 語法中的查詢。
範例:
輸入下列指令,將大型查詢結果寫入 mydataset
中名為 mytable
的目標資料表。該資料集位於預設專案中。由於您未在指令中指定任何寫入配置旗標,因此資料表必須為新資料表或空白資料表。否則,系統會傳回 Already exists
錯誤。查詢會從美國名稱資料公開資料集擷取資料。此查詢僅做示範之用。傳回的結果集不會超出回應大小上限。
bq query \
--destination_table mydataset.mytable \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
輸入下列指令,使用大型查詢結果覆寫 mydataset
中名為 mytable
的目標資料表。該資料集位於 myotherproject
,而非預設專案中。指令使用 --replace
旗標覆寫目標資料表。
bq query \
--destination_table mydataset.mytable \
--replace \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
輸入下列指令,將大型查詢結果附加至 mydataset
中名為 mytable
的目標資料表。該資料集位於 myotherproject
,而非預設專案中。指令使用 --append_table
旗標將查詢結果附加至目標資料表。
bq query \
--destination_table myotherproject:mydataset.mytable \
--append_table \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
API
如要將大型結果寫入目標資料表,請呼叫 jobs.insert
方法,設定 query
工作,並將 allowLargeResults
屬性設為 true
。使用 destinationTable
屬性指定目標資料表。如要控管現有目標資料表的寫入配置,請設定 writeDisposition
屬性。
在工作資源的 jobReference
區段中,利用 location
屬性指定您的位置。
Go
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Go 設定說明進行操作。詳情請參閱 BigQuery Go API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Java
如要啟用大型結果,請在 QueryJobConfiguration 中將允許大型結果設為 true
,並將目標資料表設為需要的 TableId。
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Node.js
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 BigQuery Node.js API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
Python
在嘗試這個範例之前,請先按照 BigQuery 快速入門:使用用戶端程式庫中的 Python 設定說明進行操作。詳情請參閱 BigQuery Python API 參考說明文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
從 Google Cloud 控制台下載並儲存查詢結果
使用 Google Cloud 控制台執行 SQL 查詢後,您可以將結果儲存到其他位置。您可以使用 Google Cloud 主控台將查詢結果下載到本機檔案、Google 試算表或 Google 雲端硬碟。如果您先依資料欄排序查詢結果,下載的資料就會保留該順序。bq 指令列工具或 API 都不支援將結果儲存到本機檔案、Google 試算表或 Google 雲端硬碟。
限制
下載並儲存查詢結果受到下列限制:
- 您只能以 CSV 或以換行符號分隔的 JSON 格式將查詢結果下載到本機檔案。
- 您無法將包含巢狀與重複資料的查詢結果儲存到 Google 試算表。
- 如要使用 Google Cloud 主控台將查詢結果儲存到 Google 雲端硬碟,結果集必須為 1GB 或以下。如果結果較大,您可以改為將結果儲存到資料表。
- 將查詢結果儲存至本機 CSV 檔案時,下載大小上限為 10 MB。下載大小上限取決於
tabledata.list
方法回應中傳回的每個資料列大小,並可能因查詢結果的結構定義而異。因此,下載的 CSV 檔案大小可能會有所不同,且可能小於下載大小上限。 - 您只能以 CSV 或以換行符號分隔的 JSON 格式將查詢結果儲存到 Google 雲端硬碟。
後續步驟
- 瞭解如何以程式輔助方式將資料表匯出為 JSON 檔案。
- 瞭解查詢工作配額。
- 瞭解 BigQuery 儲存空間定價。