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

# 使用 Amazon S3 Tables Catalog for Apache Iceberg 存取 Amazon S3 Tables
<a name="s3-tables-client-catalog"></a>

您可以使用 Amazon S3 Tables Catalog for Apache Iceberg 用戶端目錄，從像 Apache Spark 一樣的開放原始碼查詢引擎存取 S3 資料表。適用於 的 Amazon S3 Tables Catalog Apache Iceberg 是由 AWS Labs 託管的開放原始碼程式庫。其運作方式是將查詢引擎中的 Apache Iceberg 操作 (例如資料表探索、中繼資料更新，以及新增或移除資料表) 轉換為 S3 Tables API 操作。

Amazon S3 Tables Catalog for Apache Iceberg 以稱為 `s3-tables-catalog-for-iceberg.jar` 的 Maven JAR 形式發布。您可以從 [AWS Labs GitHub 儲存庫](https://github.com/awslabs/s3-tables-catalog)建置用戶端目錄 JAR，或直接從 [Maven](https://mvnrepository.com/artifact/software.amazon.s3tables/s3-tables-catalog-for-iceberg) 下載。連線至資料表時，當您初始化 Apache Iceberg 的 Spark 工作階段時，用戶端目錄 JAR 會用作相依項。

## 搭配使用 Amazon S3 Tables Catalog for Apache Iceberg 和 Apache Spark
<a name="s3-tables-integrating-open-source-spark"></a>

您可以在初始化 Spark 工作階段時，使用 Amazon S3 Tables Catalog for Apache Iceberg 用戶端目錄，從開放原始碼應用程式連線到資料表。在您的工作階段組態中，您可以指定 Iceberg 和 Amazon S3 相依項，並建立使用資料表儲存貯體做為中繼資料倉儲的自訂目錄。

****先決條件****
+ 可存取資料表儲存貯體和 S3 Tables 動作的 IAM 身分。如需詳細資訊，請參閱[S3 Tables 的存取管理](s3-tables-setting-up.md)。

**使用 Amazon S3 Tables Catalog for Apache Iceberg 初始化 Spark 工作階段**
+ 使用下列命令初始化 Spark。若要使用命令，可將 Amazon S3 Tables Catalog for Apache Iceberg *version number* 取代為 [AWS Labs GitHub 儲存庫](https://github.com/awslabs/s3-tables-catalog)的最新版本，並將 *table bucket ARN* 取代為您自己的資料表儲存貯體 ARN。

  ```
  spark-shell \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.6.1,software.amazon.s3tables:s3-tables-catalog-for-iceberg-runtime:0.1.4 \
  --conf spark.sql.catalog.s3tablesbucket=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.s3tablesbucket.catalog-impl=software.amazon.s3tables.iceberg.S3TablesCatalog \
  --conf spark.sql.catalog.s3tablesbucket.warehouse=arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
  ```

### 使用 Spark SQL 查詢 S3 資料表
<a name="query-with-spark"></a>

您可以使用 Spark 在 S3 資料表上執行 DQL、DML 和 DDL 操作。當您查詢資料表時，請使用完整資料表名稱，包括遵循此模式的工作階段目錄名稱：

`CatalogName.NamespaceName.TableName`

下列範例查詢顯示您可以與 S3 資料表互動的部分方式。若要在查詢引擎中使用這些範例查詢，請以您自己的值取代 *user input placeholder* 值：

**使用 Spark 查詢資料表**
+ 建立命名空間。

  ```
  spark.sql(" CREATE NAMESPACE IF NOT EXISTS s3tablesbucket.my_namespace")
  ```
+ 建立資料表

  ```
  spark.sql(" CREATE TABLE IF NOT EXISTS s3tablesbucket.my_namespace.`my_table` 
  ( id INT, name STRING, value INT ) USING iceberg ")
  ```
+ 查詢資料表

  ```
  spark.sql(" SELECT * FROM s3tablesbucket.my_namespace.`my_table` ").show()
  ```
+ 將資料插入至資料表

  ```
  spark.sql(
  """
      INSERT INTO s3tablesbucket.my_namespace.my_table 
      VALUES 
          (1, 'ABC', 100), 
          (2, 'XYZ', 200)
  """)
  ```
+ 將現有資料檔案載入到資料表

  1. 將資料讀取至 Spark。

     ```
     val data_file_location = "Path such as S3 URI to data file"
     val data_file = spark.read.parquet(data_file_location)
     ```

  1. 將資料寫入 Iceberg 資料表。

     ```
     data_file.writeTo("s3tablesbucket.my_namespace.my_table").using("Iceberg").tableProperty ("format-version", "2").createOrReplace()
     ```