建立 Amazon S3 BigLake 外部資料表

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 在「Explorer」窗格中，選取要建立資料集的專案。
3. 展開 more_vert「View actions」(查看動作) 選項，然後按一下「Create dataset」(建立資料集)。
4. 在「建立資料集」頁面中，指定下列詳細資料：
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. 按一下「執行」play_circle。

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

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

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());
    }
  }
}

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

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

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

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

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

5. 在「目的地」部分，指定下列詳細資料：

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

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

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

   • 如要手動指定結構定義，請取消勾選「自動偵測」選項。啟用「以文字形式編輯」，然後以 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：AWS 位置(例如 `aws-us-east-1`) Google Cloud
   • 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 天之間的間隔常值。舉例來說，如要指定 4 小時的過時間隔，請輸入 INTERVAL 4 HOUR。如果資料表在過去 4 小時內重新整理過，針對該資料表執行的作業就會使用快取中繼資料。如果快取中繼資料較舊，作業會改為從 Amazon S3 擷取中繼資料。

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

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

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

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

3. 按一下「執行」play_circle。

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

範例：

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：AWS 位置(例如 Google Cloud )。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。

接著，建立 BigLake 資料表：

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

更改下列內容：

• STALENESS_INTERVAL：指定對 BigLake 表格執行的作業是否使用快取中繼資料，以及快取中繼資料必須有多新，作業才能使用。如要進一步瞭解中繼資料快取注意事項，請參閱「中繼資料快取提升效能」。

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

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

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

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

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

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

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());
    }
  }
}

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

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

3. 按一下「查看動作」more_vert，然後按一下「建立資料表」。系統會開啟「建立資料表」窗格。

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

   1. 在「使用下列資料建立資料表」中，選取「Amazon S3」。

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

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

   3. 從「檔案格式」清單中選取檔案類型。

   4. 選取「來源資料分割」核取方塊，然後指定下列詳細資料：

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

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

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

5. 在「目的地」部分，指定下列詳細資料：

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

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

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

   • 如要手動指定結構定義，請取消勾選「自動偵測」選項。啟用「以文字形式編輯」，然後以 JSON 陣列的形式輸入資料表結構定義。

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

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 天之間的間隔常值。舉例來說，如要指定 4 小時的過時間隔，請輸入 INTERVAL 4 HOUR。如果資料表在過去 4 小時內重新整理過，針對該資料表執行的作業就會使用快取中繼資料。如果快取中繼資料較舊，作業會改為從 Amazon S3 擷取中繼資料。

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

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

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

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

3. 按一下「執行」play_circle。

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

範例

下列範例會在 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 天之間的間隔常值。舉例來說，如要指定 4 小時的過時間隔，請輸入 INTERVAL 4 HOUR。如果資料表在過去 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。

主控台

1. 前往「BigQuery」頁面

   前往 BigQuery

2. 如果沒有看到「Editor」(編輯器) 分頁，請按一下 add_box「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。

AWS CLI

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

  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 儲存空間。
• ：與 Amazon S3 儲存空間值區共置的 BigQuery Omni 區域 BigQuery Omni VPC ID。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 儲存空間。
• ：與 Amazon S3 儲存空間值區共置的 BigQuery Omni 區域 BigQuery Omni VPC ID。VPC_ID