本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 從 Athena 註冊 S3 Tables 儲存貯體目錄和查詢資料表
<a name="gdc-register-s3-table-bucket-cat"></a>

Amazon S3 Tables 儲存貯體是 Amazon S3 中的儲存貯體類型，專門用於在 Apache Iceberg 資料表中存放表格式資料。資料表儲存貯體可自動化資料表管理任務，例如壓縮、快照管理和垃圾回收，進而持續最佳化查詢效能並將成本降至最低。無論您是剛開始，還是在 Iceberg 環境中已擁有數千個資料表，資料表儲存貯體都可以簡化任何規模的資料湖。如需詳細資訊，請參閱[資料表儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets.html)。

## 考量和限制
<a name="gdc-register-s3-table-consideration"></a>
+ S3 Tables 支援 Iceberg 資料表支援的所有 DDL 操作，除了以下例外：
  + 不支援 `ALTER TABLE RENAME`、`CREATE VIEW` 和 `ALTER DATABASE`。
  + `OPTIMIZE` 和 `VACUUM` – 您可以在 S3 中管理壓縮和快照管理。如需詳細資訊，請參閱 [S3 Tables 維護文件](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-maintenance.html)。
+ 不支援對註冊為 Athena 資料來源的 S3 Tables 進行 DDL 查詢。
+ 不支援查詢結果重複使用。
+ 在已啟用 SSE-KMS、CSE-KMS 加密的工作群組中，您無法在 S3 Tables 上執行寫入操作，例如 `INSERT`、`UPDATE`、`DELETE` 或 `MERGE`。
+ 在已啟用 S3 請求者支付選項的工作群組中，您無法在 S3 Tables 上執行 DML 操作。

## 從 Athena 查詢 S3 Tables
<a name="gdc-register-s3-table-prereq-setup"></a>

**在 Athena 中查詢 S3 Tables 之前，請先完成以下先決條件步驟**

1. 建立 S3 資料表儲存貯體。如需詳細資訊，請參閱《Amazon Simple Storage Service 使用者指南》中的[建立資料表儲存貯體](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets-create.html)。

1. 請確定資料表儲存貯體與 的整合 AWS Glue Data Catalog 成功。如需必要的許可和設定步驟，請參閱《 AWS Glue 開發人員指南》中的 [ S3 Tables 整合和啟用 S3 Tables 與 Glue Data Catalog 整合的先決條件](https://docs.aws.amazon.com/glue/latest/dg/s3tables-catalog-prerequisites.html)。 [ S3 ](https://docs.aws.amazon.com/glue/latest/dg/enable-s3-tables-catalog-integration.html) 

1. 對於您使用 Athena 執行查詢的委託人，請使用下列其中一種方法授予 S3 Table 目錄的許可：

   **選項 1：使用 IAM 許可**

   使用 IAM 存取控制時，您的主體需要 AWS Glue Data Catalog 資源和 Amazon S3 Tables 資源的許可。

   下列清單包含對 Athena 中的 S3 資料表執行任何支援的 DDL 或 DML 操作所需的所有`s3tables`許可：
   + `s3tables:GetTableBucket`
   + `s3tables:GetNamespace`
   + `s3tables:GetTable`
   + `s3tables:GetTableData`
   + `s3tables:PutTableData`
   + `s3tables:ListNamespaces`
   + `s3tables:ListTables`
   + `s3tables:DeleteNamespace`
   + `s3tables:DeleteTable`
   + `s3tables:CreateNamespace`
   + `s3tables:CreateTable`
   + `s3tables:UpdateTableMetadataLocation`

   將這些許可套用至特定的 S3 資料表儲存貯體和 S3 資料表資源，或使用 `*`做為資源，以授予您帳戶中所有資料表儲存貯體和資料表的存取權。這些許可可以與 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonAthenaFullAccess.html)受管政策結合，以啟用完整的功能。

   **選項 2：使用 Lake Formation 許可**

   或者，若要啟用精細存取控制，您可以透過 Lake Formation 主控台或 授予 S3 Table 目錄的 Lake Formation 許可 AWS CLI。這需要將您的 S3 資料表儲存貯體註冊為 Lake Formation 資料位置。如需詳細資訊，請參閱 Lake Formation 開發人員指南[中的建立 Amazon S3 Tables 目錄 AWS Glue Data Catalog](https://docs.aws.amazon.com/lake-formation/latest/dg/create-s3-tables-catalog.html)。

------
#### [ AWS 管理主控台 ]

   1. 開啟位於 的 AWS Lake Formation 主控台[https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)，並以資料湖管理員身分登入。如需如何建立資料湖管理員的詳細資訊，請參閱[建立資料湖管理員](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。

   1. 在導覽窗格中，選擇**資料許可**，然後選擇**授予**。

   1. 在**授予許可**頁面的**主體**下，選擇要用來從 Athena 提交查詢的主體。

   1. 在 **LF-標籤或型錄資源**下，選擇**已命名的的資料型錄資源**。

   1. 針對**目錄**，請選擇您從資料表儲存貯體整合中建立的 Glue 資料目錄。例如，*<accoundID>*:s3tablescatalog/*amzn-s3-demo-bucket*。

   1. 對於**目錄許可**，選擇**超級**。

   1. 選擇 **Grant** (授予)。

------
#### [ AWS CLI ]

   使用 Lake Formation 資料湖管理員角色執行下列命令，以授予您用於從 Athena 提交查詢的主體存取權。

   ```
   aws lakeformation grant-permissions \
   --region <region (Example,us-east-1)> \
   --cli-input-json \
   '{
       "Principal": {
           "DataLakePrincipalIdentifier": "<user or role ARN (Example, arn:aws:iam::<Account ID>:role/ExampleRole>"
       },
       "Resource": {
           "Catalog": {
               "Id":"<Account ID>:s3tablescatalog/amzn-s3-demo-bucket"
           }
       },
       "Permissions": ["ALL"]
   }'
   ```

------

**提交 S3 Tables 的查詢**

1. 使用上文授予的使用者/角色從 Athena 提交 `CREATE DATABASE` 查詢。在此範例中，`s3tablescatalog` 是從整合建立的父 Glue Data Catalog，` s3tablescatalog/amzn-s3-demo-bucket` 是為每個 S3 Tables 儲存貯體建立的子 Glue Data Catalog。您進行查詢的方式有兩種。

------
#### [ Option 1 ]

   直接從主控台或 指定子 Glue Data Catalog (`s3tablescatalog/amzn-s3-demo-bucket`) AWS CLI。

   **使用 AWS 管理主控台**

   1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) 開啟 Athena 主控台。

   1. 在左側導覽中，對於**資料來源名稱**，選擇 **AwsDataCatalog**。

   1. 對於**目錄**，選擇 **s3tablescatalog/*amzn-s3-demo-bucket***。

   1. 在查詢編輯器中，輸入類似 `CREATE DATABASE test_namespace` 的查詢。

   **使用 AWS CLI**

   執行下列命令。

   ```
   aws athena start-query-execution \ 
   --query-string 'CREATE DATABASE `test_namespace`' \ 
   --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket"}' \
   --work-group "primary"
   ```

------
#### [ Option 2 ]

   在 Athena 主控台中，從子 Glue Data Catalog 建立 Athena 資料目錄，並在查詢中將其指定為目錄。如需詳細資訊，請參閱[將 S3 Tables 儲存貯體目錄註冊為 Athena 資料來源](#gdc-register-s3-table-console-steps)。

------

1. 使用您在先前步驟中建立的資料庫，使用 `CREATE TABLE` 建立資料表。下列範例會在您先前在 `s3tablescatalog/amzn-s3-demo-bucket` Glue 目錄中建立的 *`test_namespace`* 資料庫中建立資料表。

------
#### [ AWS 管理主控台 ]

   1. 在左側導覽中，對於**資料來源名稱**，選擇 **AwsDataCatalog**。

   1. 對於**目錄**，選擇 **s3tablescatalog/*amzn-s3-demo-bucket***。

   1. 對於**資料庫**，選擇 **test\$1namespace**。

   1. 在查詢編輯器中，執行下列查詢。

      ```
      CREATE TABLE daily_sales (
              sale_date date,
              product_category
              string, sales_amount double)
      PARTITIONED BY (month(sale_date))
      TBLPROPERTIES ('table_type' = 'iceberg')
      ```

------
#### [ AWS CLI ]

   執行下列命令。

   ```
   aws athena start-query-execution \
   --query-string "CREATE TABLE daily_sales (
           sale_date date,
           product_category
           string, sales_amount double)
   PARTITIONED BY (month(sale_date))
   TBLPROPERTIES ('table_type' = 'iceberg')" \
   --query-execution-context '{"Catalog": "s3tablescatalog/amzn-s3-demo-bucket", "Database":"test_namespace"}' \
   --work-group "primary"
   ```

------

1. 將資料插入您在上一個步驟中建立的資料表。

------
#### [ AWS 管理主控台 ]

   1. 在左側導覽中，對於**資料來源名稱**，選擇 **AwsDataCatalog**。

   1. 對於**目錄**，選擇 **s3tablescatalog/*amzn-s3-demo-bucket***。

   1. 對於**資料庫**，選擇 **test\$1namespace**。

   1. 在查詢編輯器中，執行下列查詢。

      ```
      INSERT INTO daily_sales
      VALUES 
          (DATE '2024-01-15', 'Laptop', 900.00),
          (DATE '2024-01-15', 'Monitor', 250.00),
          (DATE '2024-01-16', 'Laptop', 1350.00),
          (DATE '2024-02-01', 'Monitor', 300.00);
      ```

------
#### [ AWS CLI ]

   執行下列命令。

   ```
   aws athena start-query-execution \
   --query-string "INSERT INTO \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales
   VALUES 
   (DATE '2024-01-15', 'Laptop', 900.00),
   (DATE '2024-01-15', 'Monitor', 250.00),
   (DATE '2024-01-16', 'Laptop', 1350.00),
   (DATE '2024-02-01', 'Monitor', 300.00)"\ 
   --work-group "primary"
   ```

------

1. 將資料插入資料表後，即可進行查詢。

------
#### [ AWS 管理主控台 ]

   1. 在左側導覽中，對於**資料來源名稱**，選擇 **AwsDataCatalog**。

   1. 對於**目錄**，選擇 **s3tablescatalog/*amzn-s3-demo-bucket***。

   1. 對於**資料庫**，選擇 **test\$1namespace**。

   1. 在查詢編輯器中，執行下列查詢。

      ```
      SELECT
          product_category,
          COUNT(*) AS units_sold,
          SUM(sales_amount) AS total_revenue,
          AVG(sales_amount) AS average_price
      FROM
          daily_sales
      WHERE
          sale_date BETWEEN DATE '2024-02-01' 
                       AND DATE '2024-02-29'
      GROUP BY
          product_category
      ORDER BY
          total_revenue DESC
      ```

------
#### [ AWS CLI ]

   執行下列命令。

   ```
   aws athena start-query-execution \
   --query-string "SELECT product_category,
       COUNT(*) AS units_sold,
       SUM(sales_amount) AS total_revenue,
       AVG(sales_amount) AS average_price
   FROM \"s3tablescatalog/amzn-s3-demo-bucket\".test_namespace.daily_sales
   WHERE sale_date BETWEEN DATE '2024-02-01' AND DATE '2024-02-29'
   GROUP BY product_category
   ORDER BY total_revenue DESC"\
   --work-group "primary"
   ```

------

## 在 Athena 中建立 S3 Tables
<a name="gdc-create-s3-tables-athena"></a>

Athena 支援使用 `CREATE DATABASE` 陳述式在現有的 S3 Table 命名空間中或在 Athena 中建立的命名空間中建立資料表。若要從 Athena 建立 S3 資料表，則語法與[建立一般 Iceberg 資料表](querying-iceberg-creating-tables.md)時相同，只是您不需要指定 `LOCATION`，如下列範例所示。

```
CREATE TABLE
[db_name.]table_name (col_name data_type [COMMENT col_comment] [, ...] )
[PARTITIONED BY (col_name | transform, ... )]
[TBLPROPERTIES ([, property_name=property_value] )]
```

您也可以使用 CREATE TABLE AS SELECT (CTAS) 陳述式建立 S3 Tables。如需詳細資訊，請參閱[S3 Tables 的 CTAS](#ctas-s3-tables)。

## 將 S3 Tables 儲存貯體目錄註冊為 Athena 資料來源
<a name="gdc-register-s3-table-console-steps"></a>

要向 Athena 主控台註冊 S3 Tables 儲存貯體目錄，請遵循下列步驟。

1. 前往 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/) 開啟 Athena 主控台。

1. 在導覽窗格中，選擇**資料來源和目錄**。

1. 在**資料來源和目錄**頁面上，選擇**建立資料來源**。

1. 對於**選擇資料來源**，選擇 **Amazon S3 - AWS Glue Data Catalog**。

1. 在 **AWS Glue Data Catalog** 區段中，對於**資料來源帳戶**，選擇**此帳戶中的AWS Glue Data Catalog **。

1. 針對**建立資料表或註冊目錄**，選擇**註冊新的 AWS Glue 目錄**。

1. 在**資料來源詳細資訊**區段中，對於**資料來源名稱**，輸入要用來在 SQL 查詢中指定資料來源的名稱，或使用產生的預設名稱。

1. 針對**目錄**，選擇**瀏覽**以搜尋相同帳戶中的 AWS Glue 目錄清單。如果沒有看到任何現有的目錄，請在 [AWS Glue 主控台](https://console.aws.amazon.com/glue/)中建立一個。

1. 在**瀏覽 AWS Glue 目錄**對話方塊中，選取您要使用的目錄，然後選擇**選擇**。

1. (選用) 對於**標籤**，輸入您希望與資料來源關聯的鍵值對。

1. 選擇**下一步**。

1. 在**檢閱和建立**頁面上，驗證您輸入的資訊是否正確無誤，然後選擇**建立資料來源**。

## S3 Tables 的 CTAS
<a name="ctas-s3-tables"></a>

Amazon Athena 現在支援對 S3 Tables 執行 CREATE TABLE AS SELECT (CTAS) 操作。這項功能可讓您根據 SELECT 查詢的結果建立新的 S3 Tables。

與標準 Athena 資料表相比，為 S3 資料表建立 CTAS 查詢時，有幾項重要差異：
+ 您必須省略位置屬性，因為 S3 Tables 會自動管理自己的儲存位置。
+ `table_type` 屬性預設為 `ICEBERG`，因此您無需在查詢中明確進行指定。
+ 如果您未指定格式，則系統會自動使用 `PARQUET` 作為資料的預設格式。
+ 所有其他屬性都遵循與一般 Iceberg 資料表相同的語法。

使用 CTAS 建立 S3 資料表之前，請確定您已在 IAM 或 中設定必要的許可 AWS Lake Formation。具體而言，您需要許可才能在 S3 Tables 目錄中建立資料表。如果沒有這些許可，您的 CTAS 操作將會失敗。

**注意**  
如果您的 CTAS 查詢失敗，您可能需要使用 [S3 Tables API](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-delete.html) 刪除資料表，然後才能嘗試重新執行查詢。您無法使用 Athena `DROP TABLE` 陳述式來移除部分由查詢建立的資料表。

**範例**

```
CREATE TABLE "s3tablescatalog/amzn-s3-demo-bucket"."namespace"."s3-table-name"
WITH (
    format = 'PARQUET'
)
AS SELECT *
FROM source_table;
```