為 Cloud Storage 建立 BigLake 外部資料表
本文件說明如何建立 Cloud Storage BigLake 資料表。BigLake 資料表可讓您使用存取權委派功能,查詢 Cloud Storage 中的結構化資料。存取權委派功能可將 BigLake 資料表的存取權,與基礎資料儲存空間的存取權分離開來。
事前準備
-
In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.
-
Make sure that billing is enabled for your Trusted Cloud project.
-
Enable the BigQuery Connection API.
如果您想透過 Apache Spark 等開放原始碼引擎讀取 BigLake 資料表,就必須啟用 BigQuery Storage Read API。
-
In the Trusted Cloud console, activate Cloud Shell.
確認您有 BigQuery 資料集。
請確認您的 Google Cloud SDK 版本為 366.0.0 以上版本:
gcloud version
- 選用:如要使用 Terraform,必須使用
terraform-provider-google
4.25.0 以上版本。terraform-provider-google
版本列於 GitHub 上。您可以前往 HashiCorp Terraform 下載頁面下載最新版的 Terraform。
- 選用:如要使用 Terraform,必須使用
建立 Cloud 資源連線,或設定外部資料來源的預設連線。連線需要額外的角色和權限。詳情請參閱「建立 Cloud 資源連線」和「預設連線總覽」。
必要的角色
如要建立 BigLake 資料表,您必須具備下列 BigQuery 身分與存取權管理 (IAM) 權限:
bigquery.tables.create
bigquery.connections.delegate
BigQuery 管理員 (roles/bigquery.admin
) 預先定義的 Identity and Access Management 角色包含這些權限。
如果您不是這個角色的主要使用者,請要求管理員授予存取權,或為您建立 BigLake 資料表。
如要進一步瞭解 BigQuery 中的 Identity and Access Management 角色和權限,請參閱「預先定義的角色和權限」一文。
位置考量
使用 Cloud Storage 儲存資料檔案時,請使用 Cloud Storage 單區域或雙區域值區,而非多區域值區,以提升效能。
使用未分區的資料建立 BigLake 資料表
如果您熟悉如何在 BigQuery 中建立資料表,建立 BigLake 資料表的程序也大同小異。資料表可使用 BigLake 支援的任何檔案格式。詳情請參閱「限制」一節。
建立 BigLake 資料表前,您必須擁有資料集和可存取 Cloud Storage的 Cloud 資源連線。
如要建立 BigLake 資料表,請選取下列任一選項:
主控台
前往「BigQuery」頁面
在「Explorer」窗格中展開專案並選取資料集。
展開
「動作」選項,然後按一下「建立資料表」。在「Source」部分中,指定下列詳細資料:
在「Create table from」(使用下列資料建立資料表) 區段,選取「Google Cloud Storage」
如要從 GCS 值區選取檔案或使用 URI 模式,請瀏覽並選取要使用的值區和檔案,或輸入
gs://bucket_name/[folder_name/]file_name
格式的路徑。您無法在 Trusted Cloud 控制台中指定多個 URI,但可以指定一個星號 (
*
) 萬用字元來選取多個檔案。例如gs://mybucket/file_name*
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。Cloud Storage 值區的位置必須和要建立的資料表所在的資料集位置相同。
在「File format」(檔案格式) 部分,選取與檔案相符的格式。
在「Destination」部分中,指定下列詳細資料:
在「Project」(專案) 部分,選擇要建立資料表的專案。
在「Dataset」(資料集) 部分,選擇要建立資料表的資料集。
在「Table」(資料表) 中,輸入要建立的資料表名稱。
在「Table type」(資料表類型) 中,選取「External table」(外部資料表)。
選取「使用 Cloud 資源連線建立 BigLake 資料表」。
在「Connection ID」(連線 ID) 中,選取先前建立的連線。
在「Schema」區段中,您可以啟用結構定義自動偵測功能,或手動指定結構定義 (如果有來源檔案)。如果沒有來源檔案,您必須手動指定結構定義。
如要啟用結構定義自動偵測功能,請選取「Auto-detect」(自動偵測) 選項。
如要手動指定結構定義,請不要勾選「Auto-detect」選項。啟用「Edit as text」,然後以 JSON 陣列的形式輸入資料表結構定義。
如要忽略含有與結構定義不符的額外資料欄值的資料列,請展開「進階選項」部分,然後選取「不明的值」。
點選「建立資料表」。
建立永久資料表後,您就可以把這個資料表當做原生 BigQuery 資料表一樣執行查詢。查詢完成後,可以將結果匯出為 CSV 或 JSON 檔案、將結果儲存為資料表,或將結果儲存至 Google 試算表。
SQL
使用 CREATE EXTERNAL TABLE
DDL 陳述式。您可以明確指定結構定義,也可以使用結構定義自動偵測功能,從外部資料推斷結構定義。
前往 Trusted Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT} OPTIONS ( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'[,...]], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
請依指示取代下列項目:
PROJECT_ID
:您要建立資料表的專案名稱,例如myproject
DATASET
:您要建立資料表的 BigQuery 資料集名稱,例如mydataset
EXTERNAL_TABLE_NAME
:您要建立的資料表名稱,例如mytable
REGION
:包含連線的區域,例如us
CONNECTION_ID
:連線 ID,例如myconnection
在 Trusted Cloud 控制台 查看連線詳細資料時,連線 ID 是連線 ID 中顯示的完整連線 ID 最後一節的值,例如
projects/myproject/locations/connection_location/connections/myconnection
。如要使用 預設連線,請指定
DEFAULT
,而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。TABLE_FORMAT
:您要建立的資料表格式,例如PARQUET
如要進一步瞭解支援的格式,請參閱「限制」一節。
BUCKET_PATH
:包含外部資料表資料的 Cloud Storage 值區路徑,格式為['gs://bucket_name/[folder_name/]file_name']
。您可以在路徑中指定一個星號 (
*
) 萬用字元,從值區中選取多個檔案。例如,['gs://mybucket/file_name*']
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris
選項指定多個值區。以下範例顯示有效的
uris
值:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
指定目標為多個檔案的
uris
值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
STALENESS_INTERVAL
:指定 BigLake 資料表的作業是否會使用快取中繼資料,以及作業要使用快取中繼資料時,該中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請指定介於 30 分鐘至 7 天之間的 間隔文字常值。例如,指定
INTERVAL 4 HOUR
的過時間隔為 4 小時。使用這個值時,如果快取的中繼資料在過去 4 小時內已重新整理,對資料表執行的作業就會使用快取的中繼資料。如果快取的中繼資料較舊,則操作會改為從 Cloud Storage 擷取中繼資料。CACHE_MODE
:指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。將其設為
AUTOMATIC
,即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。如果您想依照指定的時間表重新整理中繼資料快取,請將其設為
MANUAL
。在這種情況下,您可以呼叫BQ.REFRESH_EXTERNAL_METADATA_CACHE
系統程序來重新整理快取。如果
STALENESS_INTERVAL
設為大於 0 的值,您必須設定CACHE_MODE
。
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
選項 1:資料表定義檔
使用 bq mkdef
指令建立資料表定義檔案,然後將路徑傳遞至 bq mk
指令,如下所示:
bq mkdef \ --connection_id=CONNECTION_ID \ --source_format=SOURCE_FORMAT \ BUCKET_PATH > DEFINITION_FILE bq mk --table \ --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \ SCHEMA
更改下列內容:
CONNECTION_ID
:連線 ID,例如myconnection
在 Trusted Cloud 控制台查看連線詳細資料時,連線 ID 是「連線 ID」中顯示的完整限定連線 ID 最後一個部分的值,例如
projects/myproject/locations/connection_location/connections/myconnection
。如要使用預設連線,請指定
DEFAULT
,而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。SOURCE_FORMAT
:外部資料來源的格式。例如:PARQUET
。BUCKET_PATH
:包含資料表資料的 Cloud Storage 值區路徑,格式為gs://bucket_name/[folder_name/]file_pattern
。您可以在
file_pattern
中指定一個星號 (*
) 萬用字元,從值區中選取多個檔案。例如gs://mybucket/file00*.parquet
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris
選項指定多個值區。以下範例顯示有效的
uris
值:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
、gs://bucket1/path1/*
指定以多個檔案為目標的
uris
值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
DEFINITION_FILE
:本機電腦上資料表定義檔的路徑。STALENESS_INTERVAL
:指定 BigLake 資料表作業是否使用快取中繼資料,以及作業必須使用多新鮮的快取中繼資料。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請使用
INTERVAL
資料類型說明文件中所述的Y-M D H:M:S
格式,指定 30 分鐘至 7 天之間的間隔值。例如,指定0-0 0 4:0:0
為 4 小時的過時間隔。使用這個值時,如果資料表在過去 4 小時內已重新整理,針對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料較舊,作業會改為從 Cloud Storage 擷取中繼資料。DATASET
:您要建立資料表的 BigQuery 資料集名稱,例如mydataset
EXTERNAL_TABLE_NAME
:您要建立的資料表名稱,例如mytable
SCHEMA
:BigLake 資料表的結構定義
範例:
bq mkdef --connection_id=myconnection --metadata_cache_mode=CACHE_MODE --source_format=CSV 'gs://mybucket/*.csv' > mytable_def bq mk --table --external_table_definition=mytable_def='gs://mybucket/*.csv' --max_staleness=0-0 0 4:0:0 myproject:mydataset.mybiglaketable Region:STRING,Quarter:STRING,Total_sales:INTEGER
如要使用結構定義自動偵測功能,請在 mkdef
指令中設定 --autodetect=true
標記,並省略結構定義:
bq mkdef \ --connection_id=myconnection \ --metadata_cache_mode=CACHE_MODE \ --source_format=CSV --autodetect=true \ gs://mybucket/*.csv > mytable_def bq mk \ --table \ --external_table_definition=mytable_def=gs://mybucket/*.csv \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable
選項 2:內嵌資料表定義
您可以直接將資料表定義傳遞至 bq mk
指令,而非建立資料表定義檔。使用 @connection
修飾子,指定 --external_table_definition
標記結尾處要使用的連線。
bq mk --table \ --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \ DATASET_NAME.TABLE_NAME \ SCHEMA
更改下列內容:
SOURCE_FORMAT
:外部資料來源的格式例如
CSV
。BUCKET_PATH
:包含資料表資料的 Cloud Storage 值區路徑,格式為gs://bucket_name/[folder_name/]file_pattern
。您可以在
file_pattern
中指定一個星號 (*
) 萬用字元,從值區中選取多個檔案。例如gs://mybucket/file00*.parquet
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris
選項指定多個值區。以下範例顯示有效的
uris
值:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
、gs://bucket1/path1/*
指定以多個檔案為目標的
uris
值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
PROJECT_ID
:要建立資料表的專案名稱,例如myproject
REGION
:包含連線的區域,us
CONNECTION_ID
:連線 ID,例如myconnection
在 Trusted Cloud 控制台查看連線詳細資料時,連線 ID 是「連線 ID」中顯示的完整限定連線 ID 最後一個部分的值,例如
projects/myproject/locations/connection_location/connections/myconnection
。如要使用預設連線,請指定
DEFAULT
,而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。DATASET_NAME
:要建立 BigLake 資料表的資料集名稱TABLE_NAME
:BigLake 資料表名稱SCHEMA
:BigLake 資料表的結構定義
範例:
bq mk --table \ --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \ --max_staleness=0-0 0 4:0:0 \ myproject:mydataset.myexternaltable \ Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
呼叫 tables.insert
方法 API 方法,並在您傳入的 Table
資源中建立 ExternalDataConfiguration
。
指定 schema
屬性,或將 autodetect
屬性設為 true
,為支援的資料來源啟用結構定義自動偵測功能。
指定 connectionId
屬性,以識別用於連線至 Cloud Storage 的連線。
Terraform
本範例會在未分割的資料上建立 BigLake 資料表。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要在 Trusted Cloud 專案中套用 Terraform 設定,請完成下列各節中的步驟。
準備 Cloud Shell
- 啟動 Cloud Shell。
-
設定要套用 Terraform 設定的預設 Trusted Cloud 專案。
您只需為每個專案執行這個指令一次,而且可以在任何目錄中執行。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 設定檔中設定明確的值,系統就會覆寫環境變數。
準備目錄
每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。
-
在 Cloud Shell 中建立目錄,並在該目錄中建立新檔案。檔案名稱必須包含
.tf
副檔名,例如main.tf
。在本教學課程中,檔案稱為main.tf
。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您正在參考教學課程,可以複製各個章節或步驟中的程式碼範例。
將範例程式碼複製到新建立的
main.tf
中。您可以視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分,建議您採用這種做法。
- 查看並修改要套用至環境的範例參數。
- 儲存變更。
-
初始化 Terraform。這項操作只需對每個目錄執行一次。
terraform init
如要使用最新版的 Google 供應器,您可以選擇加入
-upgrade
選項:terraform init -upgrade
套用變更
-
檢查設定,確認 Terraform 要建立或更新的資源符合您的預期:
terraform plan
視需要修正設定。
-
執行下列指令,並在提示中輸入
yes
,即可套用 Terraform 設定:terraform apply
等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。
- 開啟 Trusted Cloud 專案即可查看結果。在 Trusted Cloud 控制台中,前往 UI 中的資源,確認 Terraform 已建立或更新這些資源。
BigLake 支援結構定義自動偵測功能。不過,如果您未提供結構定義,且服務帳戶在先前步驟中未獲得存取權,則嘗試自動偵測結構定義時,這些步驟會失敗,並顯示存取遭拒的訊息。
在 Apache Hive 分區資料上建立 BigLake 資料表
您可以為 Cloud Storage 中的 Hive 分區資料建立 BigLake 資料表。建立外部分區資料表後,您就無法變更分區鍵。您需要重新建立資料表才能變更分割鍵。
如要根據 Cloud Storage 中的 Hive 分區資料建立 BigLake 資料表,請選取下列任一選項:
主控台
前往「BigQuery」頁面
在「Explorer」窗格中展開專案並選取資料集。
依序按一下
「查看動作」和「建立資料表」。系統會開啟「Create table」窗格。在「Source」部分中,指定下列詳細資料:
在「Create table from」(使用下列資料建立資料表) 部分,選取「Google Cloud Storage」。
使用萬用字元提供資料夾路徑。例如:
my_bucket/my_files*
。資料夾必須與要建立、附加或覆寫的資料表所屬的資料集位置相同。從「File format」清單中選取檔案類型。
選取「Source data partitioning」核取方塊,然後指定下列詳細資料:
- 在「選取來源 URI 前置字串」中輸入 URI 前置字串,例如:
gs://my_bucket/my_files
。 - 選用:如要要求在所有針對此資料表的查詢中使用分區篩選器,請選取「Require partition filter」(需要分區篩選器) 核取方塊。使用分區篩選器可以降低成本並提升效能。詳情請參閱「在查詢中要求分區鍵的述詞篩選器」。
在「分區推論模式」部分中,選取下列其中一個選項:
- 自動推論類型:將分區結構定義偵測模式設為
AUTO
。 - 所有資料欄皆為字串:將分區結構定義偵測模式設為
STRINGS
。 - 提供自己的:將分區結構定義偵測模式設為
CUSTOM
,然後手動輸入分區鍵的結構定義資訊。詳情請參閱「提供自訂分區索引鍵結構定義」。
- 自動推論類型:將分區結構定義偵測模式設為
- 在「選取來源 URI 前置字串」中輸入 URI 前置字串,例如:
在「Destination」部分中,指定下列詳細資料:
- 在「Project」(專案) 部分,選取要建立資料表的專案。
- 在「Dataset」(資料集) 部分,選取要建立資料表的資料集。
- 在「Table」中,輸入要建立的資料表名稱。
- 在「Table type」(資料表類型) 中,選取「External table」(外部資料表)。
- 勾選「使用 Cloud 資源連線建立 BigLake 資料表」核取方塊。
- 在「Connection ID」(連線 ID) 部分,選取先前建立的連線。
在「Schema」(結構定義) 區段中,選取「Auto detect」(自動偵測) 選項,啟用結構定義自動偵測功能。
如要忽略含有與結構定義不符之額外資料欄值的資料列,請展開「Advanced options」(進階選項) 部分,然後選取「Unknown values」(不明的值)。
點選「建立資料表」。
SQL
使用 CREATE EXTERNAL TABLE
DDL 陳述式:
前往 Trusted Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH PARTITION COLUMNS ( PARTITION_COLUMN PARTITION_COLUMN_TYPE, ) WITH CONNECTION {`PROJECT_ID.REGION.CONNECTION_ID` | DEFAULT} OPTIONS ( hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX", uris=['FILE_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE', format ="TABLE_FORMAT" );
請依指示取代下列項目:
PROJECT_ID
:您要建立資料表的專案名稱,例如myproject
DATASET
:您要建立資料表的 BigQuery 資料集名稱,例如mydataset
EXTERNAL_TABLE_NAME
:您要建立的資料表名稱,例如mytable
PARTITION_COLUMN
:分區欄名稱PARTITION_COLUMN_TYPE
:分區欄的類型REGION
:包含連線的區域,例如us
CONNECTION_ID
:連線 ID,例如myconnection
在 Trusted Cloud 控制台查看連線詳細資料時,連線 ID 是「連線 ID」中顯示的完整連線 ID 最後一節的值,例如
projects/myproject/locations/connection_location/connections/myconnection
。如要使用 預設連線,請指定
DEFAULT
,而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。HIVE_PARTITION_URI_PREFIX
:hive 分割作業 URI 前置字串,例如gs://mybucket/
FILE_PATH
:要建立的外部資料表的資料來源路徑,例如gs://mybucket/*.parquet
STALENESS_INTERVAL
:指定 BigLake 資料表的作業是否會使用快取中繼資料,以及作業要使用快取中繼資料時,該中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請指定介於 30 分鐘至 7 天之間的 間隔文字常值。例如,指定
INTERVAL 4 HOUR
的過時間隔為 4 小時。使用這個值時,如果快取的中繼資料在過去 4 小時內已重新整理,對資料表執行的作業就會使用快取的中繼資料。如果快取的中繼資料較舊,則操作會改為從 Cloud Storage 擷取中繼資料。CACHE_MODE
:指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」一文。將其設為
AUTOMATIC
,即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。如果您想依照指定的時間表重新整理中繼資料快取,請將其設為
MANUAL
。在這種情況下,您可以呼叫BQ.REFRESH_EXTERNAL_METADATA_CACHE
系統程序來重新整理快取。如果
STALENESS_INTERVAL
設為大於 0 的值,您必須設定CACHE_MODE
。TABLE_FORMAT
:您要建立的資料表格式,例如PARQUET
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
範例
以下範例會在分區資料上建立 BigLake 資料表,其中:
- 系統會自動偵測結構定義。
- 資料表的中繼資料快取過時間隔為 1 天。
- 中繼資料快取會自動重新整理。
CREATE EXTERNAL TABLE `my_dataset.my_table` WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 1 DAY, metadata_cache_mode = 'AUTOMATIC' );
以下範例會在分區資料上建立 BigLake 資料表,其中:
- 已指定結構定義。
- 資料表的中繼資料快取過時間隔為 8 小時。
- 必須手動重新整理中繼資料快取。
CREATE EXTERNAL TABLE `my_dataset.my_table` ( ProductId INTEGER, ProductName STRING, ProductType STRING ) WITH PARTITION COLUMNS ( sku STRING, ) WITH CONNECTION `us.my-connection` OPTIONS( hive_partition_uri_prefix = "gs://mybucket/products", uris = ['gs://mybucket/products/*'], max_staleness = INTERVAL 8 HOUR, metadata_cache_mode = 'MANUAL' );
bq
首先,請使用 bq mkdef
指令建立資料表定義檔:
bq mkdef \ --source_format=SOURCE_FORMAT \ --connection_id=REGION.CONNECTION_ID \ --hive_partitioning_mode=PARTITIONING_MODE \ --hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX \ --require_hive_partition_filter=BOOLEAN \ --metadata_cache_mode=CACHE_MODE \ GCS_URIS > DEFINITION_FILE
更改下列內容:
SOURCE_FORMAT
:外部資料來源的格式。例如:CSV
。REGION
:包含連線的區域,例如us
。CONNECTION_ID
:連線 ID,例如myconnection
。在 Trusted Cloud 控制台查看連線詳細資料時,連線 ID 是「連線 ID」中顯示的完整限定連線 ID 最後一個部分的值,例如
projects/myproject/locations/connection_location/connections/myconnection
。如要使用預設連線,請指定
DEFAULT
,而非包含 PROJECT_ID.REGION.CONNECTION_ID 的連線字串。PARTITIONING_MODE
:Hive 分區模式。請使用下列其中一個值:AUTO
:自動偵測索引鍵名稱和類型。STRINGS
:自動將索引鍵名稱轉換為字串。CUSTOM
:在來源 URI 前置字串中編碼索引鍵結構定義。
GCS_URI_SHARED_PREFIX
:來源 URI 前置字串。BOOLEAN
:指定是否要在查詢時要求述詞篩選器。這個標記是選用的,預設值為false
。CACHE_MODE
:指定中繼資料快取是自動或手動重新整理。只有在您打算在後續bq mk
指令中使用--max_staleness
標記,以便啟用中繼資料快取功能時,才需要加入這個標記。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」一文。將其設為
AUTOMATIC
,即可在系統定義的間隔 (通常介於 30 到 60 分鐘之間) 重新整理中繼資料快取。如果您想依照指定的時間表重新整理中繼資料快取,請將其設為
MANUAL
。在這種情況下,您可以呼叫BQ.REFRESH_EXTERNAL_METADATA_CACHE
系統程序來重新整理快取。如果
STALENESS_INTERVAL
設為大於 0 的值,您必須設定CACHE_MODE
。GCS_URIS
:Cloud Storage 資料夾的路徑,使用萬用字元格式。DEFINITION_FILE
:本機電腦上資料表定義檔的路徑。
如果 PARTITIONING_MODE
是 CUSTOM
,請在來源 URI 前置字串中加入分區索引鍵結構定義,並使用以下格式:
--hive_partitioning_source_uri_prefix=GCS_URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...
建立資料表定義檔後,請使用 bq mk
指令建立 BigLake 資料表:
bq mk --external_table_definition=DEFINITION_FILE \ --max_staleness=STALENESS_INTERVAL \ DATASET_NAME.TABLE_NAME \ SCHEMA
更改下列內容:
DEFINITION_FILE
:資料表定義檔案的路徑。STALENESS_INTERVAL
:指定 BigLake 資料表作業是否使用快取中繼資料,以及作業必須使用多新鮮的快取中繼資料。如果您納入此標記,則必須在先前的bq mkdef
指令中為--metadata_cache_mode
標記指定值。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請使用
INTERVAL
資料類型 說明中的Y-M D H:M:S
格式,指定 30 分鐘至 7 天之間的間隔值。例如,指定0-0 0 4:0:0
為 4 小時的過時間隔。使用這個值時,如果快取的中繼資料在過去 4 小時內已重新整理,對資料表執行的作業就會使用快取的中繼資料。如果快取的中繼資料較舊,則操作會改為從 Cloud Storage 擷取中繼資料。DATASET_NAME
:包含資料表的資料集名稱。TABLE_NAME
:您要建立的資料表名稱。SCHEMA
:指定 JSON 結構定義檔的路徑,或以field:data_type,field:data_type,...
格式指定結構定義。如要使用結構定義自動偵測功能,請省略這個引數。
範例
以下範例使用 AUTO
Hive 區隔模式,並將中繼資料快取設為 12 小時的過時間隔,並自動重新整理:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=AUTO \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
--metadata_cache_mode=AUTOMATIC \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
--max_staleness=0-0 0 12:0:0 \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
以下範例使用 STRING
Hive 分割模式:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=STRING \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
以下範例使用 CUSTOM
Hive 分割模式:
bq mkdef --source_format=CSV \
--connection_id=us.my-connection \
--hive_partitioning_mode=CUSTOM \
--hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
gs://myBucket/myTable/* > mytable_def
bq mk --external_table_definition=mytable_def \
mydataset.mytable \
Region:STRING,Quarter:STRING,Total_sales:INTEGER
API
如要使用 BigQuery API 設定 Hive 分割,請在建立資料表定義檔時,將 hivePartitioningOptions
物件納入 ExternalDataConfiguration
物件。如要建立 BigLake 資料表,您也必須為 connectionId
欄位指定值。
如果您將 hivePartitioningOptions.mode
欄位設為 CUSTOM
,就必須在 hivePartitioningOptions.sourceUriPrefix
欄位中對分區索引鍵結構定義進行編碼,如下所示:gs://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...
如要強制在查詢時使用述詞篩選器,請將 hivePartitioningOptions.requirePartitionFilter
欄位設為 true
。
Terraform
本範例會在分區資料上建立 BigLake 資料表。
如要向 BigQuery 進行驗證,請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。
如要在 Trusted Cloud 專案中套用 Terraform 設定,請完成下列各節中的步驟。
準備 Cloud Shell
- 啟動 Cloud Shell。
-
設定要套用 Terraform 設定的預設 Trusted Cloud 專案。
您只需為每個專案執行這個指令一次,而且可以在任何目錄中執行。
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
如果您在 Terraform 設定檔中設定明確的值,系統就會覆寫環境變數。
準備目錄
每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。
-
在 Cloud Shell 中建立目錄,並在該目錄中建立新檔案。檔案名稱必須包含
.tf
副檔名,例如main.tf
。在本教學課程中,檔案稱為main.tf
。mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
如果您正在參考教學課程,可以複製各個章節或步驟中的程式碼範例。
將範例程式碼複製到新建立的
main.tf
中。您可以視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分,建議您採用這種做法。
- 查看並修改要套用至環境的範例參數。
- 儲存變更。
-
初始化 Terraform。這項操作只需對每個目錄執行一次。
terraform init
如要使用最新版的 Google 供應器,您可以選擇加入
-upgrade
選項:terraform init -upgrade
套用變更
-
檢查設定,確認 Terraform 要建立或更新的資源符合您的預期:
terraform plan
視需要修正設定。
-
執行下列指令,並在提示中輸入
yes
,即可套用 Terraform 設定:terraform apply
等待 Terraform 顯示「Apply complete!」(套用完成) 訊息。
- 開啟 Trusted Cloud 專案即可查看結果。在 Trusted Cloud 控制台中,前往 UI 中的資源,確認 Terraform 已建立或更新這些資源。
設定存取控管政策
您可以透過多種方法控管 BigLake 資料表的存取權:
如需設定資料欄層級安全防護機制的操作說明,請參閱資料欄層級的安全性指南。
如要瞭解如何設定資料遮罩,請參閱資料遮罩指南。
如需設定資料列層級安全防護機制的指引,請參閱資料列層級的安全性指南。
舉例來說,假設您想限制資料集 mydataset
中資料表 mytable
的資料列存取權:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | | JP | tablet | 300 | | UK | laptop | 200 | +---------+---------+-------+
您可以為 Kim (kim@example.com
) 建立資料列層級篩選器,限制他們只能存取 country
等於 US
的資料列。
CREATE ROW ACCESS POLICY only_us_filter ON mydataset.mytable GRANT TO ('user:kim@example.com') FILTER USING (country = 'US');
接著,Kim 執行以下查詢:
SELECT * FROM projectid.mydataset.mytable;
輸出結果只會顯示 country
等於 US
的資料列:
+---------+---------+-------+ | country | product | price | +---------+---------+-------+ | US | phone | 100 | +---------+---------+-------+
查詢 BigLake 資料表
詳情請參閱「查詢 BigLake 資料表中的 Cloud Storage 資料」。
更新 BigLake 資料表
您可以視需要更新 BigLake 資料表,例如變更中繼資料快取。如要取得來源格式和來源 URI 等資料表詳細資料,請參閱「取得資料表資訊」。
您也可以使用相同的程序,將以 Cloud Storage 為基礎的外部資料表連結至連線,然後將資料表升級為 BigLake 資料表。詳情請參閱「將外部資料表升級為 BigLake 資料表」。
如要更新 BigLake 資料表,請選取下列任一選項:
SQL
使用 CREATE OR REPLACE EXTERNAL TABLE
DDL 陳述式更新資料表:
前往 Trusted Cloud 控制台的「BigQuery」頁面。
在查詢編輯器中輸入以下陳述式:
CREATE OR REPLACE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME` WITH CONNECTION {`REGION.CONNECTION_ID` | DEFAULT} OPTIONS( format ="TABLE_FORMAT", uris = ['BUCKET_PATH'], max_staleness = STALENESS_INTERVAL, metadata_cache_mode = 'CACHE_MODE' );
請依指示取代下列項目:
PROJECT_ID
:包含資料表的專案名稱DATASET
:含有資料表的資料集名稱EXTERNAL_TABLE_NAME
:資料表名稱REGION
:包含連線的區域CONNECTION_ID
:要使用的連線名稱如要使用 預設連線,請指定
DEFAULT
,而非包含REGION.CONNECTION_ID
的連線字串。TABLE_FORMAT
:資料表使用的格式更新資料表時無法變更這項設定。
BUCKET_PATH
:包含外部資料表資料的 Cloud Storage 值區路徑,格式為['gs://bucket_name/[folder_name/]file_name']
。您可以在路徑中指定一個星號 (
*
) 萬用字元,從值區中選取多個檔案。例如,['gs://mybucket/file_name*']
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris
選項指定多個值區。以下範例顯示有效的
uris
值:['gs://bucket/path1/myfile.csv']
['gs://bucket/path1/*.csv']
['gs://bucket/path1/*', 'gs://bucket/path2/file00*']
指定目標為多個檔案的
uris
值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
STALENESS_INTERVAL
:指定是否允許作業使用針對資料表的快取中繼資料,以及作業必須使用多新鮮的快取中繼資料如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。
如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請指定介於 30 分鐘至 7 天之間的 間隔文字常值。例如,指定
INTERVAL 4 HOUR
的過時間隔為 4 小時。使用這個值時,如果快取的中繼資料在過去 4 小時內已重新整理,對資料表執行的作業就會使用快取的中繼資料。如果快取的中繼資料較舊,則操作會改為從 Cloud Storage 擷取中繼資料。CACHE_MODE
:指定中繼資料快取是否自動或手動重新整理如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。
將其設為
AUTOMATIC
,即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。如果您想依照指定的時間表重新整理中繼資料快取,請將其設為
MANUAL
。在這種情況下,您可以呼叫BQ.REFRESH_EXTERNAL_METADATA_CACHE
系統程序來重新整理快取。如果
STALENESS_INTERVAL
設為大於 0 的值,您必須設定CACHE_MODE
。
按一下
「Run」。
如要進一步瞭解如何執行查詢,請參閱「執行互動式查詢」一文。
bq
使用 bq mkdef
和 bq update
指令更新資料表:
產生外部資料表定義,說明要變更的資料表層面:
bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \ --source_format=TABLE_FORMAT \ --metadata_cache_mode=CACHE_MODE \ "BUCKET_PATH" > /tmp/DEFINITION_FILE
更改下列內容:
PROJECT_ID
:包含連線的專案名稱REGION
:包含連線的區域CONNECTION_ID
:要使用的連線名稱TABLE_FORMAT
:資料表使用的格式。更新資料表時無法變更這項設定。CACHE_MODE
:指定中繼資料快取是自動或手動重新整理。如要進一步瞭解中繼資料快取考量事項,請參閱「中繼資料快取可提升效能」。將其設為
AUTOMATIC
,即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。如果您想依據自訂的時間表重新整理中繼資料快取,請將其設為
MANUAL
。在這種情況下,您可以呼叫BQ.REFRESH_EXTERNAL_METADATA_CACHE
系統程序來重新整理快取。如果
STALENESS_INTERVAL
設為大於 0 的值,您必須設定CACHE_MODE
。BUCKET_PATH
:包含外部資料表資料的 Cloud Storage 值區路徑,格式為gs://bucket_name/[folder_name/]file_name
。您可以在路徑中指定一個星號 (
*
) 萬用字元,藉此限制從值區中選取的檔案。例如,gs://mybucket/file_name*
。詳情請參閱「Cloud Storage URI 的萬用字元支援」。您可以提供多個路徑,為
uris
選項指定多個值區。以下範例顯示有效的
uris
值:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.csv
gs://bucket/path1/*,gs://bucket/path2/file00*
指定以多個檔案為目標的
uris
值時,所有檔案都必須共用相容的結構定義。如要進一步瞭解如何在 BigQuery 中使用 Cloud Storage URI,請參閱「Cloud Storage 資源路徑」。
DEFINITION_FILE
:您要建立的資料表定義檔案名稱。
使用新的外部資料表定義更新資料表:
bq update --max_staleness=STALENESS_INTERVAL \ --external_table_definition=/tmp/DEFINITION_FILE \ PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME
更改下列內容:
STALENESS_INTERVAL
:指定作業是否會使用針對資料表的快取中繼資料,以及作業必須使用多新鮮的快取中繼資料。如要進一步瞭解中繼資料快取的考量事項,請參閱「為提升效能而快取中繼資料」。如要停用中繼資料快取功能,請指定 0。這是目前的預設做法。
如要啟用中繼資料快取功能,請使用
INTERVAL
資料類型說明文件中所述的Y-M D H:M:S
格式,指定 30 分鐘至 7 天之間的間隔值。例如,指定0-0 0 4:0:0
的過時間隔為 4 小時。使用這個值時,如果資料表在過去 4 小時內已重新整理,針對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料較舊,作業會改為從 Cloud Storage 擷取中繼資料。DEFINITION_FILE
:您建立或更新的資料表定義檔案名稱。PROJECT_ID
:包含資料表的專案名稱DATASET
:含有資料表的資料集名稱EXTERNAL_TABLE_NAME
:資料表名稱
示例
以下範例會更新 mytable
,只要在過去 4.5 小時內重新整理過,就會使用快取中繼資料,並自動重新整理快取中繼資料:
bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable
其中 enable_metadata.json
包含以下內容:
json
{
"metadataCacheMode": "AUTOMATIC"
}
稽核記錄
如要瞭解如何在 BigQuery 中記錄資料,請參閱「BigQuery 監控簡介」。如要進一步瞭解如何記錄 Trusted Cloud,請參閱 Cloud Logging。
後續步驟
- 進一步瞭解 BigLake。
- 瞭解 Cloud Storage。
- 瞭解如何查詢 Amazon Web Services (AWS) 資料。
- 瞭解如何查詢 Microsoft Azure 資料。