查詢外部資料表中的 Cloud Storage 資料
本文說明如何查詢儲存在 Cloud Storage 外部資料表中的資料。
事前準備
確認您有 Cloud Storage 外部資料表。
必要的角色
如要查詢 Cloud Storage 外部資料表,請確認您具備下列角色:
- BigQuery 資料檢視者 (
roles/bigquery.dataViewer) - BigQuery 使用者 (
roles/bigquery.user) - Storage 物件檢視者 (
roles/storage.objectViewer)
視權限而定,您可以將這些角色授予自己,或要求管理員授予。如要進一步瞭解如何授予角色,請參閱「查看可針對資源授予的角色」。
如要查看查詢外部資料表所需的確切 BigQuery 權限,請展開「Required permissions」(必要權限) 部分:
所需權限
bigquery.jobs.createbigquery.readsessions.create(只有在使用 BigQuery Storage Read API 讀取資料時才需要)bigquery.tables.getbigquery.tables.getData
查詢永久外部資料表
建立 Cloud Storage 外部資料表後,您可以使用 GoogleSQL 語法查詢,就像查詢標準 BigQuery 資料表一樣。例如:SELECT field1, field2
FROM mydataset.my_cloud_storage_table;。
查詢臨時外部資料表
使用臨時資料表查詢外部資料來源,適合用於對外部資料執行一次性、臨時查詢,或用於擷取、轉換和載入 (ETL) 程序。
如要查詢外部資料來源,但不想建立永久資料表,請提供臨時資料表的資料表定義,然後在指令或呼叫中使用該資料表定義,查詢臨時資料表。您可以透過下列任一方式提供資料表定義:
- 資料表定義檔案
- 內嵌結構定義
- JSON 結構定義檔案
系統會使用資料表定義檔案或提供的結構定義,建立臨時外部資料表,並對該資料表執行查詢。
使用臨時外部資料表時,並不會在某個 BigQuery 資料集中建立資料表。由於資料表並非永久儲存在資料集中,因此無法與他人共用。
您可以使用 bq 指令列工具、API 或用戶端程式庫,建立及查詢連結至外部資料來源的臨時資料表。
bq
您可以使用 bq query 指令搭配 --external_table_definition 旗標,查詢連結至外部資料來源的臨時資料表。使用 bq 指令列工具查詢連結至外部資料來源的臨時資料表時,您可以使用下列方式識別資料表的結構定義:
- 資料表定義檔 (儲存在本機)
- 內嵌結構定義
- JSON 結構定義檔案 (儲存在本機電腦)
(選用) 提供 --location 旗標,並將值設為您的位置。
如要使用資料表定義檔查詢連接外部資料來源的臨時資料表,請輸入下列指令。
bq --location=LOCATION query \ --external_table_definition=TABLE::DEFINITION_FILE \ 'QUERY'
更改下列內容:
LOCATION:位置名稱。--location是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設定為asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。TABLE:要建立的臨時資料表名稱。DEFINITION_FILE:本機電腦上的資料表定義檔案路徑。QUERY:您要提交至臨時資料表的查詢。
舉例來說,下列指令會使用名為 sales_def 的資料表定義檔,建立及查詢名為 sales 的臨時資料表。
bq query \
--external_table_definition=sales::sales_def \
'SELECT
Region,
Total_sales
FROM
sales'
如要使用內嵌結構定義來查詢連結至外部資料來源的臨時資料表,請輸入下列指令。
bq --location=LOCATION query \ --external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH \ 'QUERY'
更改下列內容:
LOCATION:位置名稱。--location是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設定為asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。TABLE:要建立的臨時資料表名稱。SCHEMA:內嵌結構定義定義,格式為field:data_type,field:data_type。SOURCE_FORMAT:外部資料來源的格式,例如CSV。BUCKET_PATH:Cloud Storage bucket 的路徑,其中包含資料表的資料,格式為gs://bucket_name/[folder_name/]file_pattern。您可以在
file_pattern中指定一個星號 (*) 萬用字元,從 bucket 中選取多個檔案。例如:gs://mybucket/file00*.parquet。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris選項指定多個 bucket。以下範例顯示有效的
uris值:gs://bucket/path1/myfile.csvgs://bucket/path1/*.parquetgs://bucket/path1/file1*、gs://bucket1/path1/*
指定多個檔案的
uris值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
QUERY:您要提交至臨時資料表的查詢。
舉例來說,下列指令會使用 Region:STRING,Quarter:STRING,Total_sales:INTEGER 結構定義,建立和查詢名為 sales 的臨時資料表,且此表會連結至儲存在 Cloud Storage 中的 CSV 檔案。
bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
'SELECT
Region,
Total_sales
FROM
sales'
如要使用 JSON 結構定義檔來查詢連接外部資料來源的臨時資料表,請輸入下列指令。
bq --location=LOCATION query \ --external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH \ 'QUERY'
更改下列內容:
LOCATION:位置名稱。--location是選用旗標。舉例來說,如果您在東京地區使用 BigQuery,就可以將該旗標的值設定為asia-northeast1。您可以使用 .bigqueryrc 檔案設定位置的預設值。SCHEMA_FILE:本機電腦上的 JSON 結構定義檔案路徑。SOURCE_FORMAT:外部資料來源的格式,例如CSV。BUCKET_PATH:Cloud Storage bucket 的路徑,其中包含資料表的資料,格式為gs://bucket_name/[folder_name/]file_pattern。您可以在
file_pattern中指定一個星號 (*) 萬用字元,從 bucket 中選取多個檔案。例如:gs://mybucket/file00*.parquet。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris選項指定多個 bucket。以下範例顯示有效的
uris值:gs://bucket/path1/myfile.csvgs://bucket/path1/*.parquetgs://bucket/path1/file1*、gs://bucket1/path1/*
指定多個檔案的
uris值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
QUERY:您要提交至臨時資料表的查詢。
舉例來說,下列指令會使用 /tmp/sales_schema.json 結構定義檔,建立和查詢名為 sales 的臨時資料表,且此表會連結至儲存在 Cloud Storage 中的 CSV 檔案。
bq query \ --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv \ 'SELECT Region, Total_sales FROM sales'
API
如要使用 API 執行查詢,請按照下列步驟操作:
- 建立
Job物件。 - 使用
JobConfiguration物件填入Job物件的configuration區段。 - 使用
JobConfigurationQuery物件填入JobConfiguration物件的query區段。 - 使用
ExternalDataConfiguration物件填入JobConfigurationQuery物件的tableDefinitions區段。 - 呼叫
jobs.insert方法以非同步方式執行查詢,或呼叫jobs.query方法以同步方式執行查詢,並傳入Job物件。
Java
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Java 設定操作說明進行操作。詳情請參閱 BigQuery Java API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Node.js
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Node.js 設定操作說明進行操作。詳情請參閱 BigQuery Node.js API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
Python
在試用這個範例之前,請先按照「使用用戶端程式庫的 BigQuery 快速入門導覽課程」中的 Python 設定操作說明進行操作。詳情請參閱 BigQuery Python API 參考文件。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
執行程式碼範例前,請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。
查詢 _FILE_NAME 虛擬資料欄
以外部資料來源為基礎的資料表會提供名為 _FILE_NAME 的虛擬資料欄。這一欄包含資料列所屬檔案的完整路徑。這個資料欄僅適用於參照儲存在 Cloud Storage、Google 雲端硬碟、Amazon S3 和 Azure Blob Storage 中外部資料的資料表。
_FILE_NAME 資料欄名稱為保留名稱,也就是說,您無法在任何資料表中建立該名稱的資料欄。如要選取 _FILE_NAME 的值,您必須使用別名。以下查詢範例示範如何將別名 fn 指派給虛擬資料欄,藉此選取 _FILE_NAME。
bq query \
--project_id=PROJECT_ID \
--use_legacy_sql=false \
'SELECT
name,
_FILE_NAME AS fn
FROM
`DATASET.TABLE_NAME`
WHERE
name contains "Alex"' 更改下列內容:
-
PROJECT_ID是有效的專案 ID (如果您使用 Cloud Shell,或是在 Google Cloud CLI 中設定預設專案,則不需要這個旗標) -
DATASET是儲存永久外部資料表的資料集名稱 -
TABLE_NAME是永久外部資料表的名稱
如果查詢在 _FILE_NAME 虛擬資料欄上有篩選器述詞,BigQuery 會嘗試略過讀取不符合篩選條件的檔案。使用 _FILE_NAME 虛擬資料欄建構查詢述詞時,建議做法與
使用虛擬資料欄查詢擷取時間分區資料表
類似。
最佳化外部資料表查詢
使用外部資料表查詢 Cloud Storage 資料時,建議啟用 Rapid Cache。Rapid Cache 為 Cloud Storage bucket 提供採用 SSD 的可用區讀取快取,可提升查詢效能,並降低查詢外部資料表的費用。詳情請參閱「最佳化 Cloud Storage 外部資料表查詢」。
後續步驟
- 瞭解如何在 BigQuery 中使用 SQL。
- 瞭解外部資料表。
- 瞭解 BigQuery 配額。