建立 Amazon S3 BigLake 外部資料表

本文說明如何建立 Amazon Simple Storage Service (Amazon S3) BigLake 資料表。BigLake 資料表可讓您使用存取權委派功能，查詢 Amazon S3 中的資料。存取權委派功能可將 BigLake 資料表的存取權，與基礎資料儲存空間的存取權分離開來。

如要瞭解 BigQuery 和 Amazon S3 之間的資料流動方式，請參閱「查詢資料時的資料流動」。

事前準備

請確認您已連線至 Amazon S3 資料。

必要的角色

如要取得建立外部資料表所需的權限，請要求管理員授予您資料集的 BigQuery 管理員 (roles/bigquery.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色包含建立外部資料表所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

如要建立外部資料表，您必須具備下列權限：

• bigquery.tables.create
• bigquery.connections.delegate

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

建立資料集

建立外部資料表前，您必須在支援的區域中建立資料集。請選取下列其中一個選項：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，選取要建立資料集的專案。
3. 展開 「View actions」 選項，然後按一下「Create dataset」。
4. 在「Create dataset」(建立資料集) 頁面中指定下列詳細資料：
1. 針對「Dataset ID」(資料集 ID)，輸入唯一的資料集名稱。
2. 針對「Data location」(資料位置)，選擇支援的地區。
3. 選用：如要自動刪除資料表，請勾選「Enable table expiration」核取方塊，並設定「Default maximum table age」的預設資料表存在時間上限 (以天為單位)。資料表到期時，Amazon S3 中的資料不會遭到刪除。
4. 如果要使用預設定序，請展開「進階選項」部分，然後選取「啟用預設定序」選項。
5. 點選「建立資料集」。

SQL

使用 CREATE SCHEMA DDL 陳述式。以下範例會在 aws-us-east-1 區域中建立資料集：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');

3. 按一下 「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

bq

在指令列環境中，使用 bq mk 指令建立資料集：

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

--project_id 參數會覆寫預設專案。

更改下列內容：

• LOCATION：資料集的位置

  如要瞭解支援的地區，請參閱「據點」一文。建立資料集後，就無法變更位置。您可以使用 .bigqueryrc 檔案設定位置的預設值。

• PROJECT_ID：您的專案 ID

• DATASET_NAME：要建立的資料集名稱

  如要在非預設專案中建立資料集，請採用下列格式將專案 ID 新增至資料集：PROJECT_ID:DATASET_NAME。

Java

在嘗試這個範例之前，請先按照 BigQuery 快速入門：使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

使用未分區的資料建立 BigLake 資料表

選取下列選項之一：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中展開專案，然後選取資料集。

3. 在「資料集資訊」部分，按一下 「建立資料表」。

4. 在「Create table」(建立資料表) 頁面的「Source」(來源) 區段中，執行下列操作：

   1. 在「Create table from」(建立資料表來源) 中，選取「Amazon S3」。
   2. 在「選取 S3 路徑」中，輸入指向 Amazon S3 資料的 URI，格式為 s3://BUCKET_NAME/PATH。將 BUCKET_NAME 替換為 Amazon S3 值區的名稱；值區的區域應與資料集的區域相同。將 PATH 替換為您要寫入匯出檔案的路徑，其中可以包含一個萬用字元 *。
   3. 在「File format」(檔案格式) 部分，選取 Amazon S3 中的資料格式。支援的格式包括 AVRO、CSV、DELTA_LAKE、ICEBERG、JSONL、ORC 和 PARQUET。

5. 在「Destination」部分中，指定下列詳細資料：

   1. 針對「Dataset」(資料集)，選擇適當的資料集。
   2. 在「Table」(資料表) 欄位中輸入資料表名稱。
   3. 確認「Table type」(資料表類型) 已設為 [External table] (外部資料表)。
   4. 在「Connection ID」(連線 ID) 專區中，從下拉式選單中選擇適當的連線 ID。如要瞭解連線資訊，請參閱「連結至 Amazon S3」。

6. 在「Schema」區段中，您可以啟用結構定義自動偵測功能，或手動指定結構定義 (如果有來源檔案)。如果沒有來源檔案，您必須手動指定結構定義。

   • 如要啟用結構定義自動偵測功能，請選取「Auto-detect」(自動偵測) 選項。

   • 如要手動指定結構定義，請不要勾選「Auto-detect」選項。啟用「Edit as text」，然後以 JSON 陣列的形式輸入資料表結構定義。

7. 點選「建立資料表」。

SQL

如要建立 BigLake 資料表，請使用 CREATE EXTERNAL TABLE 陳述式搭配 WITH CONNECTION 子句：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
     WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
     OPTIONS (
       format = "DATA_FORMAT",
       uris = ["S3_URI"],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE');

   更改下列內容：

   • DATASET_NAME：您建立的資料集名稱
   • TABLE_NAME：您要為這個資料表命名的名稱
   • AWS_LOCATION： Google Cloud 中的 AWS 位置(例如 `aws-us-east-1`)
   • CONNECTION_NAME：您建立的連線名稱
   • DATA_FORMAT：任何支援的 BigQuery 聯合格式 (例如 AVRO、CSV、DELTA_LAKE、ICEBERG 或 PARQUET (預先發布版))
   • S3_URI：指向 Amazon S3 資料的 URI (例如 s3://bucket/path)
   • STALENESS_INTERVAL：指定 BigLake 資料表的作業是否會使用快取中繼資料，以及作業要使用快取中繼資料時，該中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。

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

     如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的 間隔文字常值。例如，指定 INTERVAL 4 HOUR 的過時間隔為 4 小時。使用這個值時，如果資料表在過去 4 小時內已重新整理，對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料比這還舊，作業會改為從 Amazon S3 擷取中繼資料。

   • CACHE_MODE：指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」一文。

     將其設為 AUTOMATIC，即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。

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

     如果 STALENESS_INTERVAL 設為大於 0 的值，您必須設定 CACHE_MODE。

3. 按一下 「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

範例：

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

建立資料表定義檔：

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

更改下列內容：

• DATA_FORMAT：任何支援的 BigQuery 聯合格式 (例如 AVRO、CSV、DELTA_LAKE、ICEBERG 或 PARQUET)。
• S3_URI：指向 Amazon S3 資料的 URI (例如 s3://bucket/path)。
• AWS_LOCATION： Google Cloud 中的 AWS 位置(例如 aws-us-east-1)。

• CONNECTION_NAME：您建立的連線名稱。

• CACHE_MODE：指定中繼資料快取是自動或手動重新整理。只有在您打算在後續 bq mk 指令中使用 --max_staleness 標記，以便啟用中繼資料快取功能時，才需要加入這個標記。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。

  將其設為 AUTOMATIC，即可在系統定義的間隔 (通常介於 30 到 60 分鐘之間) 重新整理中繼資料快取。

  如果您想依照指定的時間表重新整理中繼資料快取，請將其設為 MANUAL。在這種情況下，您可以呼叫 BQ.REFRESH_EXTERNAL_METADATA_CACHE 系統程序來重新整理快取。如果 STALENESS_INTERVAL 設為大於 0 的值，您必須設定 CACHE_MODE。

注意： 如要覆寫預設專案，請使用 --project_id=PROJECT_ID 參數。將 PROJECT_ID 替換為 Google Cloud 專案 ID。

接著，建立 BigLake 資料表：

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

更改下列內容：

• STALENESS_INTERVAL：指定 BigLake 表格的作業是否會使用快取的中繼資料，以及作業要使用快取的中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。

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

  如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔文字常值。例如，指定 INTERVAL 4 HOUR 的過時間隔為 4 小時。使用這個值時，如果資料表在過去 4 小時內已重新整理，針對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料比此時間還舊，作業會改為從 Amazon S3 擷取中繼資料。

• DATASET_NAME：您建立的資料集名稱。

• TABLE_NAME：您要為這個資料表命名的名稱。

舉例來說，下列指令會建立新的 BigLake 資料表 awsdataset.awstable，可查詢儲存在路徑 s3://s3-bucket/path/file.csv 且在位置 aws-us-east-1 中具有讀取連結的 Amazon S3 資料：

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

API

呼叫 tables.insert 方法 API 方法，並在您傳入的 Table 資源中建立 ExternalDataConfiguration。

指定 schema 屬性，或將 autodetect 屬性設為 true，為支援的資料來源啟用結構定義自動偵測功能。

指定 connectionId 屬性，以識別用於連線至 Amazon S3 的連線。

Java

在嘗試這個範例之前，請先按照 BigQuery 快速入門：使用用戶端程式庫中的 Java 設定說明進行操作。詳情請參閱 BigQuery Java API 參考說明文件。

如要向 BigQuery 進行驗證，請設定應用程式預設憑證。詳情請參閱「設定用戶端程式庫的驗證機制」。

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

根據分區資料建立 BigLake 資料表

您可以為 Amazon S3 中的 Hive 分區資料建立 BigLake 資料表。建立外部分區資料表後，您就無法變更分區鍵。您需要重新建立資料表才能變更分割鍵。

如要根據 Hive 分區資料建立 BigLake 資料表，請選取下列任一選項：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中展開專案並選取資料集。

3. 依序按一下 「查看動作」和「建立資料表」。系統會開啟「Create table」窗格。

4. 在「Source」部分中，指定下列詳細資料：

   1. 在「Create table from」(建立資料表的來源) 中，選取「Amazon S3」。

   2. 使用萬用字元提供資料夾路徑。例如：s3://mybucket/*。

      資料夾必須與要建立、附加或覆寫的資料表所屬的資料集位置相同。

   3. 從「File format」清單中選取檔案類型。

   4. 選取「Source data partitioning」核取方塊，然後指定下列詳細資料：

      1. 在「選取來源 URI 前置字串」中輸入 URI 前置字串，例如：s3://mybucket/my_files。
      2. 選用：如要要求在所有針對此資料表的查詢中使用分區篩選器，請選取「Require partition filter」(需要分區篩選器) 核取方塊。使用分區篩選器可以降低成本並提升效能。詳情請參閱「在查詢中要求分區鍵的述詞篩選器」。

      3. 在「分區推論模式」部分中，選取下列其中一個選項：

         • 自動推論類型：將分區結構定義偵測模式設為 AUTO。
         • 所有資料欄皆為字串：將分區結構定義偵測模式設為 STRINGS。
         • 提供自己的：將分區結構定義偵測模式設為 CUSTOM，然後手動輸入分區鍵的結構定義資訊。詳情請參閱「自訂分區索引鍵結構定義」。

5. 在「Destination」部分中，指定下列詳細資料：

   1. 在「Project」(專案) 部分，選取要建立資料表的專案。
   2. 在「Dataset」(資料集) 部分，選取要建立資料表的資料集。
   3. 在「Table」中，輸入要建立的資料表名稱。
   4. 針對「Table type」(資料表類型)，確認已選取「External table」(外部資料表)。
   5. 在「Connection ID」(連線 ID) 部分，選取先前建立的連線。

6. 在「Schema」區段中，您可以啟用結構定義自動偵測功能，或手動指定結構定義 (如果有來源檔案)。如果沒有來源檔案，您必須手動指定結構定義。

   • 如要啟用結構定義自動偵測功能，請選取「Auto-detect」(自動偵測) 選項。

   • 如要手動指定結構定義，請不要勾選「Auto-detect」選項。啟用「Edit as text」，然後以 JSON 陣列的形式輸入資料表結構定義。

7. 如要忽略含有與結構定義不符之額外資料欄值的資料列，請展開「Advanced options」(進階選項) 部分，然後選取「Unknown values」(不明的值)。

8. 點選「建立資料表」。

SQL

使用 CREATE EXTERNAL TABLE DDL 陳述式：

1. 前往 Google Cloud 控制台的「BigQuery」頁面。

   前往 BigQuery

2. 在查詢編輯器中輸入以下陳述式：

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     format ="TABLE_FORMAT"
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE'
   );

   請依指示取代下列項目：

   • PROJECT_ID：您要建立資料表的專案名稱，例如 myproject
   • DATASET：您要建立資料表的 BigQuery 資料集名稱，例如 mydataset
   • EXTERNAL_TABLE_NAME：您要建立的資料表名稱，例如 mytable
   • PARTITION_COLUMN：分區欄名稱
   • PARTITION_COLUMN_TYPE：分區欄的類型
   • REGION：包含連線的區域，例如 us
   • CONNECTION_ID：連線名稱，例如 myconnection
   • HIVE_PARTITION_URI_PREFIX：hive 分區 URI 前置字串，例如：s3://mybucket/
   • FILE_PATH：要建立的外部資料表的資料來源路徑，例如：s3://mybucket/*.parquet
   • TABLE_FORMAT：您要建立的資料表格式，例如 PARQUET
   • STALENESS_INTERVAL：指定 BigLake 資料表的作業是否會使用快取中繼資料，以及作業要使用快取中繼資料時，該中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。

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

     如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的 間隔文字常值。例如，指定 INTERVAL 4 HOUR 的過時間隔為 4 小時。使用這個值時，如果資料表已在過去 4 小時內重新整理，對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料比這還舊，作業會改為從 Amazon S3 擷取中繼資料。

   • CACHE_MODE：指定中繼資料快取是否自動或手動重新整理。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」一文。

     將其設為 AUTOMATIC，即可按照系統定義的間隔 (通常為 30 到 60 分鐘) 重新整理中繼資料快取。

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

     如果 STALENESS_INTERVAL 設為大於 0 的值，您必須設定 CACHE_MODE。

3. 按一下 「Run」。

如要進一步瞭解如何執行查詢，請參閱「執行互動式查詢」一文。

範例

以下範例會在 Amazon S3 中，針對分區資料建立 BigLake 資料表。系統會自動偵測結構定義。

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

bq

首先，請使用 bq mkdef 指令建立資料表定義檔：

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 URIS > DEFINITION_FILE

更改下列內容：

• SOURCE_FORMAT：外部資料來源的格式。例如：CSV。
• REGION：包含連線的區域，例如 us。
• CONNECTION_ID：連線名稱，例如 myconnection。
• PARTITIONING_MODE：Hive 分區模式。請使用下列其中一個值：
  • AUTO：自動偵測索引鍵名稱和類型。
  • STRINGS：自動將索引鍵名稱轉換為字串。
  • CUSTOM：在來源 URI 前置字串中編碼索引鍵結構定義。
• 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。

• URIS：Amazon S3 資料夾的路徑，使用萬用字元格式。

• DEFINITION_FILE：本機電腦上資料表定義檔的路徑。

如果 PARTITIONING_MODE 是 CUSTOM，請在來源 URI 前置字串中加入分區索引鍵結構定義，並使用以下格式：

--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

建立資料表定義檔後，請使用 bq mk 指令建立 BigLake 資料表：

bq mk --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

更改下列內容：

• STALENESS_INTERVAL：指定 BigLake 表格的作業是否會使用快取的中繼資料，以及作業要使用快取的中繼資料的最新程度。如要進一步瞭解中繼資料快取的考量事項，請參閱「為提升效能而快取中繼資料」。

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

  如要啟用中繼資料快取功能，請指定介於 30 分鐘至 7 天之間的間隔文字常值。例如，指定 INTERVAL 4 HOUR 的過時間隔為 4 小時。使用這個值時，如果資料表在過去 4 小時內已重新整理，針對資料表執行的作業會使用快取的中繼資料。如果快取的中繼資料比此時間還舊，作業會改為從 Amazon S3 擷取中繼資料。

• DEFINITION_FILE：資料表定義檔案的路徑。

• DATASET_NAME：包含資料表的資料集名稱。

• TABLE_NAME：您要建立的資料表名稱。

• SCHEMA：指定 JSON 結構定義檔的路徑，或以 field:data_type,field:data_type,... 格式指定結構定義。如要使用結構定義自動偵測功能，請省略這個引數。

範例

以下範例會針對 Amazon S3 資料使用 AUTO Hive 區隔模式：

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

以下範例會針對 Amazon S3 資料使用 STRING Hive 區隔模式：

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --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 欄位中對分區索引鍵結構定義進行編碼，如下所示：s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

如要強制在查詢時使用述詞篩選器，請將 hivePartitioningOptions.requirePartitionFilter 欄位設為 true。

Delta Lake 資料表

Delta Lake 是開放原始碼資料表格式，支援 PB 等級的資料表。Delta Lake 資料表可做為臨時和永久資料表進行查詢，並支援 BigLake 資料表。

結構定義同步處理

Delta Lake 會維護標準化結構定義，做為中繼資料的一部分。您無法使用 JSON 中繼資料檔案更新結構定義。如要更新結構定義，請按照下列步驟操作：

1. 使用加上 --autodetect_schema 旗標的 bq update 指令：

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   更改下列內容：

   • PROJECT_ID：包含要更新的資料表的專案 ID

   • DATASET：包含要更新資料表的資料集

   • TABLE：要更新的資料表

類型轉換

BigQuery 會將 Delta Lake 資料類型轉換為下列 BigQuery 資料類型：

Delta Lake 類型	BigQuery 類型
boolean	BOOL
byte	INT64
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	NUMERIC 或 BIG_NUMERIC，視精確度而定
date	DATE
time	TIME
timestamp (not partition column)	TIMESTAMP
timestamp (partition column)	DATETIME
string	STRING
binary	BYTES
array<Type>	ARRAY<Type>
struct	STRUCT
map<KeyType, ValueType>	ARRAY<Struct<key KeyType, value ValueType>>

限制

以下限制適用於 Delta Lake 資料表：

• 外部資料表限制適用於 Delta Lake 資料表。

• 只有 BigQuery Omni 支援 Delta Lake 資料表，且有相關限制。

• 您無法使用新的 JSON 中繼資料檔案更新資料表。您必須使用自動偵測結構定義資料表更新作業。詳情請參閱「結構定義同步處理」。

• BigLake 安全性功能只會在透過 BigQuery 服務存取時，保護 Delta Lake 資料表。

建立 Delta Lake 資料表

以下範例使用 Delta Lake 格式的 CREATE EXTERNAL TABLE 陳述式建立外部資料表：

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

更改下列內容：

• table_name：資料表名稱。

• connection_name：連線名稱。連線必須識別 Amazon S3 或 Blob Storage 來源。

• parent_directory：父目錄的 URI。

使用 Delta Lake 進行跨雲端傳輸

以下範例使用 LOAD DATA 陳述式，將資料載入至適當的資料表：

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

如需更多跨雲端資料移轉範例，請參閱「透過跨雲端作業載入資料」。

查詢 BigLake 資料表

詳情請參閱「查詢 Amazon S3 資料」。

查看資源中繼資料

預先發布版

這項功能受《服務專屬條款》中「一般服務條款」一節的「正式發布前產品條款」規範。 正式發布前功能是依「原樣」提供，支援服務可能受限。 詳情請參閱推出階段說明。

您可以使用 INFORMATION_SCHEMA 檢視表查看資源中繼資料。查詢 JOBS_BY_*、JOBS_TIMELINE_BY_* 和 RESERVATION* 檢視畫面時，您必須指定查詢的處理位置，該位置必須與資料表的區域相鄰。如要瞭解 BigQuery Omni 位置，請參閱「位置」一文。對於所有其他系統表格，指定查詢工作位置為選填。

如要瞭解 BigQuery Omni 支援的系統表，請參閱限制。

如要查詢 JOBS_* 和 RESERVATION* 系統表格，請選取下列其中一種方法指定處理位置：

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 如果找不到「Editor」分頁，請按一下「Compose new query」圖示 。

3. 依序按一下「更多」「查詢設定」。「查詢設定」對話方塊隨即開啟。

4. 在「查詢設定」對話方塊中，依序選取「其他設定」>「資料位置」，然後選取與 BigQuery Omni 區域同區的 BigQuery 區域。舉例來說，如果您的 BigQuery Omni 區域為 aws-us-east-1，請指定 us-east4。

5. 選取其餘欄位，然後按一下「儲存」。

bq

使用 --location 旗標，將工作處理位置設為與 BigQuery Omni 區域同處的 BigQuery 區域。舉例來說，如果您的 BigQuery Omni 區域為 aws-us-east-1，請指定 us-east4。

示例

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

如果您透過程式執行工作，請將位置引數設為與 BigQuery Omni 區域同處的 BigQuery 區域。舉例來說，如果您的 BigQuery Omni 區域為 aws-us-east-1，請指定 us-east4。

以下範例會列出過去六小時的中繼資料重新整理工作：

SELECT
 *
FROM
 `region-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

將 REGION_NAME 替換為您的地區。

VPC Service Controls

您可以使用 VPC Service Controls 範圍，限制 BigQuery Omni 對外部雲端服務的存取權，做為額外的防護層。舉例來說，VPC Service Controls 範圍可限制從 BigQuery Omni 資料表匯出至特定 Amazon S3 值區或 Blob Storage 容器。

如要進一步瞭解 VPC Service Controls，請參閱「VPC Service Controls 總覽」。

必要權限

請確認您具備設定服務範圍所需的權限。如要查看設定 VPC Service Controls 時所需的 IAM 角色清單，請參閱 VPC Service Controls 說明文件中的「使用 IAM 進行存取權控管」。

使用 Google Cloud 控制台設定 VPC Service Controls

1. 在 Google Cloud 控制台導覽選單中，依序點選「Security」(安全性) 和「VPC Service Controls」。

   前往「VPC Service Controls」頁面

2. 如要為 BigQuery Omni 設定 VPC Service Controls，請按照「建立服務範圍」指南中的步驟操作，然後在「Egress rules」窗格中執行下列步驟：

   1. 在「Egress rules」面板中，按一下「Add rule」。

   2. 在「From attributes of the API client」(從 API 用戶端的屬性) 部分，從「Identity」(身分) 清單中選取選項。

   3. 選取「外部資源的 TO 屬性」。

   4. 如要新增外部資源，請按一下「新增外部資源」。

   5. 在「Add external resource」對話方塊中，輸入有效的資源名稱。例如：

      • Amazon Simple Storage Service (Amazon S3)：s3://BUCKET_NAME

        請將 BUCKET_NAME 替換為 Amazon S3 值區名稱。

      • Azure Blob 儲存體：azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        將 CONTAINER NAME 替換為 Blob 儲存體容器名稱。

      如需輸出規則屬性清單，請參閱輸出規則參考資料。

   6. 選取要允許在外部資源上使用的做法：

      1. 如要允許所有方法，請在「Methods」清單中選取「All methods」。
      2. 如果您想允許特定方法，請選取「Selected method」，然後點選「Select methods」，接著選取要允許在外部資源上使用的特定方法。

   7. 按一下「建立範圍」。

使用 gcloud CLI 設定 VPC Service Controls

如要使用 gcloud CLI 設定 VPC Service Controls，請按照下列步驟操作：

1. 設定預設存取權政策。
2. 建立輸出政策輸入檔案。
3. 新增出口政策。

設定預設存取權政策

存取權政策是全機構的存取層級和服務範圍容器。如要瞭解如何設定預設存取權政策或取得存取權政策名稱，請參閱「管理存取權政策」。

建立輸出政策輸入檔案

輸出規則區塊會定義範圍內允許存取的範圍外資源。針對外部資源，externalResources 屬性會定義 VPC Service Controls 範圍內允許存取的外部資源路徑。

您可以使用 JSON 檔案或 YAML 檔案設定外送規則。以下範例使用 .yaml 格式：

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

• egressTo：列出範圍外指定專案中 Google Cloud 資源的允許服務作業。

• operations：列出可存取的服務，以及滿足 from 封鎖條件的用戶端可存取的動作或方法。

• serviceName：為 BigQuery Omni 設定 bigquery.googleapis.com。

• methodSelectors：列出符合 from 條件的用戶端可存取的方法。如要瞭解可限制的服務方法和權限，請參閱「支援的服務方法限制」。

• method：有效的服務方法，或 \"*\" 以允許所有 serviceName 方法。

• permission：有效的服務權限，例如 \"*\"、externalResource.read 或 externalResource.write。對於需要此權限的作業，系統允許存取範圍外部的資源。

• externalResources：列出外圍內的用戶端可存取的外部資源。將 EXTERNAL_RESOURCE_PATH 替換為有效的 Amazon S3 值區 (例如 s3://bucket_name)，或 Blob 儲存體容器路徑 (例如 azure://myaccount.blob.core.windows.net/container_name)。

• egressFrom：列出範圍內指定專案中 Google Cloud資源的允許服務作業。

• identityType 或 identities：定義可存取外圍範圍外指定資源的身分類型。將 IDENTITY_TYPE 替換為下列有效值之一：

  • ANY_IDENTITY：允許所有身分。
  • ANY_USER_ACCOUNT：允許所有使用者。
  • ANY_SERVICE_ACCOUNT：允許所有服務帳戶

• identities：列出可存取範圍外指定資源的服務帳戶。

• serviceAccount (選用)：將 SERVICE_ACCOUNT 替換為可存取服務範圍外指定資源的服務帳戶。

範例

以下範例是允許從邊界內部到 AWS 中 s3://mybucket Amazon S3 位置的出站作業政策。

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

以下範例會允許 Blob 儲存體容器的傳出作業：

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

如要進一步瞭解輸出政策，請參閱輸出規則參考資料。

新增出口政策

如要在建立新的服務範圍時新增出口政策，請使用 gcloud access-context-manager perimeters create 指令。舉例來說，下列指令會建立名為 omniPerimeter 的新外圍，其中包含專案號碼 12345 的專案、限制 BigQuery API，以及新增 egress.yaml 檔案中定義的出口政策：

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

如要為現有服務範圍新增出口政策，請使用 gcloud access-context-manager perimeters update 指令。舉例來說，下列指令會將 egress.yaml 檔案中定義的出口政策新增至名為 omniPerimeter 的現有服務範圍：

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

確認範圍

如要驗證範圍，請使用 gcloud access-context-manager perimeters describe 指令：

gcloud access-context-manager perimeters describe PERIMETER_NAME

將 PERIMETER_NAME 替換為邊界名稱。

例如，下列指令會說明周界 omniPerimeter：

gcloud access-context-manager perimeters describe omniPerimeter

詳情請參閱「管理服務範圍」。

允許 BigQuery Omni VPC 存取 Amazon S3

身為 BigQuery 管理員，您可以建立 S3 值區政策，授予 BigQuery Omni 存取 Amazon S3 資源的權限。這樣一來，只有經過授權的 BigQuery Omni VPC 才能與 Amazon S3 互動，進而提升資料安全性。

為 BigQuery Omni VPC 套用 S3 儲存貯體政策

如要套用 S3 值區政策，請使用 AWS CLI 或 Terraform：

AWS CLI

執行下列指令，套用 S3 值區政策，其中包含使用 aws:SourceVpc 屬性的條件：

  aws s3api put-bucket-policy \
    --bucket=BUCKET_NAME \
    --policy "{
      \"Version\": \"2012-10-17\",
      \"Id\": \"RestrictBucketReads\",
      \"Statement\": [
          {
              \"Sid\": \"AccessOnlyToOmniVPC\",
              \"Principal\": \"*\",
              \"Action\": [\"s3:ListBucket\", \"s3:GetObject\"],
              \"Effect\": \"Allow\",
              \"Resource\": [\"arn:aws:s3:::BUCKET_NAME\",
                             \"arn:aws:s3:::BUCKET_NAME/*\"],
              \"Condition\": {
                  \"StringEquals\": {
                    \"aws:SourceVpc\": \"VPC_ID\"
                  }
              }
          }
      ]
    }"

更改下列內容：

• BUCKET_NAME：您要讓 BigQuery 存取的 Amazon S3 儲存桶。
• VPC_ID：與 Amazon S3 儲存桶一併使用的 BigQuery Omni 區域的 BigQuery Omni VPC ID。您可以在本頁表格中找到這項資訊。

Terraform

在 Terraform 設定檔中新增下列內容：

  resource "aws_s3_bucket" "example" {
    bucket = "BUCKET_NAME"
  }

  resource "aws_s3_bucket_policy" "example" {
    bucket = aws_s3_bucket.example.id
    policy = jsonencode({
      Version = "2012-10-17"
      Id      = "RestrictBucketReads"
      Statement = [
          {
              Sid       = "AccessOnlyToOmniVPC"
              Effect    = "Allow"
              Principal = "*"
              Action    = ["s3:GetObject", "s3:ListBucket"]
              Resource  = [
                  aws_s3_bucket.example.arn,
                  "${aws_s3_bucket.example.arn}/*"
                  ]
              Condition = {
                  StringEquals = {
                      "aws:SourceVpc": "VPC_ID"
                  }
              }
          },
      ]
    })
  }

更改下列內容：

• BUCKET_NAME：您要讓 BigQuery 存取的 Amazon S3 儲存桶。
• VPC_ID：與 Amazon S3 儲存桶一併使用的 BigQuery Omni 區域的 BigQuery Omni VPC ID。

BigQuery Omni VPC 資源 ID

區域	虛擬私有雲 ID
aws-ap-northeast-2	vpc-0b488548024288af2
aws-ap-southeast-2	vpc-0726e08afef3667ca
aws-eu-central-1	vpc-05c7bba12ad45558f
aws-eu-west-1	vpc-0e5c646979bbe73a0
aws-us-east-1	vpc-0bf63a2e71287dace
aws-us-west-2	vpc-0cc24e567b9d2c1cb

限制

如要查看適用於 Amazon S3 和 Blob 儲存體 BigLake 資料表的完整限制清單，請參閱「限制」。

後續步驟

• 瞭解 BigQuery Omni。
• 使用 BigQuery Omni 與 AWS 實驗室。
• 瞭解 BigLake 資料表。
• 瞭解如何將查詢結果匯出至 Amazon S3。
• 瞭解如何在 Amazon Simple Storage Service (Amazon S3) 啟用中繼資料快取的資料表上，建立具體化檢視表。
• 瞭解如何建立 materialized view 的副本，讓 materialized view 中的 Amazon S3 資料可在本機上用於彙整。