# 访问 Data Catalog
<a name="access_catalog"></a>

 您可以使用 AWS Glue Data Catalog (Data Catalog) 来发现和理解您的数据。Data Catalog 提供了一种一致的方法来维护架构定义、数据类型、位置和其他元数据。您可以使用如下方法访问 Data Catalog：
+ AWS Glue 控制台 – 您可以通过 AWS Glue 控制台（基于 Web 的用户界面）访问和管理 Data Catalog。控制台允许您浏览和搜索数据库、表及其关联的元数据，以及创建、更新和删除元数据定义。
+ AWS Glue 爬网程序 – 爬网程序是自动扫描您的数据来源并以元数据填充 Data Catalog 的程序。您可以创建和运行爬网程序来发现来自各种来源的数据并对其进行编目，例如 Amazon S3、Amazon RDS、Amazon DynamoDB、Amazon CloudWatch、兼容 JDBC 的关系数据库（例如 MySQL 和 PostgreSQL）以及一些非 AWS 的来源，例如 Snowflake 和 Google BigQuery。
+ AWS Glue API – 您可以使用 AWS Glue API 以编程方式访问 Data Catalog。这些 API 允许您以编程方式与 Data Catalog 进行交互，从而实现自动化并与其他应用程序和服务集成。
+ AWS Command Line Interface（AWS CLI）– 您可以使用 AWS CLI 从命令行访问和管理 Data Catalog。CLI 提供了用于创建、更新和删除元数据定义以及查询和检索元数据信息的命令。
+ 与其他 AWS 服务集成 – Data Catalog 与其他各种 AWS 服务集成，使您能够访问和使用存储在目录中的元数据。例如，您可以使用 Data Catalog 中的元数据，利用 Amazon Athena 查询数据来源，并使用 AWS Lake Formation 来管理 Data Catalog 资源的数据访问和治理。

**Topics**
+ [使用 AWS Glue Iceberg REST 端点连接到 Data Catalog](connect-glu-iceberg-rest.md)
+ [使用 AWS Glue Iceberg REST 扩展端点连接到 Data Catalog](connect-glue-iceberg-rest-ext.md)
+ [适用于 Apache Iceberg 的 AWS Glue REST API 规范](iceberg-rest-apis.md)
+ [从独立 Spark 应用程序连接到 Data Catalog](connect-gludc-spark.md)
+ [Amazon Redshift 与 Apache Iceberg 之间的数据映射](data-mapping-rs-iceberg.md)
+ [使用 AWS Glue Glue Iceberg REST 目录 API 时的注意事项和限制](limitation-glue-iceberg-rest-api.md)

# 使用 AWS Glue Iceberg REST 端点连接到 Data Catalog
<a name="connect-glu-iceberg-rest"></a>

 AWS Glue 的 Iceberg REST 端点支持 Apache Iceberg REST 规范中指定的 API 操作。使用 Iceberg REST 客户端，您可以将在分析引擎上运行的应用程序连接到 Data Catalog 中托管的 REST 目录。

 该端点支持 Apache Iceberg 表规范 v1 和 v2，默认为 v2。当使用 Iceberg 表 v1 规范时，必须在 API 调用中指定 v1。使用 API 操作，您可以访问 Amazon S3 对象存储和 Amazon S3 表存储中存储的 Iceberg 表。

**端点配置**

可以使用服务端点访问 AWS Glue Iceberg REST 目录。有关区域特定的端点，请参阅 [AWS Glue service endpoints reference guide](https://docs.aws.amazon.com/general/latest/gr/glue.html#glue_region)。例如，连接到 us-east-1 区域中的 AWS Glue 时，需要配置端点 URI 属性，如下所示：

```
Endpoint : https://glue.us-east-1.amazonaws.com/iceberg
```

**其他配置属性** – 当使用 Iceberg 客户端将 Spark 等分析引擎连接到服务端点时，需要指定以下应用程序配置属性：

```
catalog_name = "mydatacatalog"
aws_account_id = "123456789012"
aws_region = "us-east-1"
spark = SparkSession.builder \
    ... \
    .config("spark.sql.defaultCatalog", catalog_name) \
    .config(f"spark.sql.catalog.{catalog_name}", "org.apache.iceberg.spark.SparkCatalog") \
    .config(f"spark.sql.catalog.{catalog_name}.type", "rest") \
    .config(f"spark.sql.catalog.{catalog_name}.uri", "https://glue.{aws_region}.amazonaws.com/iceberg") \
    .config(f"spark.sql.catalog.{catalog_name}.warehouse", "{aws_account_id}") \
    .config(f"spark.sql.catalog.{catalog_name}.rest.sigv4-enabled", "true") \
    .config(f"spark.sql.catalog.{catalog_name}.rest.signing-name", "glue") \    
    .config("spark.sql.extensions","org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
    .getOrCreate()
```

AWS Glue Iceberg 端点 ` https://glue.us-east-1.amazonaws.com/iceberg` 支持以下 Iceberg REST API：
+ GetConfig
+ ListNamespaces
+ CreateNamespace
+ LoadNamespaceMetadata
+ UpdateNamespaceProperties
+ DeleteNamespace
+ ListTables
+ CreateTable
+ LoadTable
+ TableExists
+ UpdateTable
+ DeleteTable

## 前缀和目录路径参数
<a name="prefix-catalog-path-parameters"></a>

Iceberg REST 目录 API 的请求 URL 中有一个自由格式前缀。例如，`ListNamespaces` API 调用使用 `GET/v1/{prefix}/namespaces` URL格式。AWS Glue 前缀始终遵循 `/catalogs/{catalog}` 结构，以确保 REST 路径符合 AWS Glue 多目录层次结构。`{catalog}` 路径参数可以根据以下规则推导：


| **访问模式** |  **Glue 目录 ID 样式**  |  **前缀样式**  | **示例默认目录 ID** |  **示例 REST 路由**  | 
| --- | --- | --- | --- | --- | 
|  访问当前账户中的默认目录  | 非必需 | : |  不适用  |  GET /v1/catalogs/:/namespaces  | 
|  访问特定账户中的默认目录  | accountID | accountID | 111122223333 | GET /v1/catalogs/111122223333/namespaces | 
|  访问当前账户中的嵌套目录  |  catalog1/catalog2  |  catalog1/catalog2  |  rmscatalog1:db1  |  GET /v1/catalogs/rmscatalog1:db1/namespaces  | 
|  访问特定账户中的嵌套目录  |  accountId:catalog1/catalog2  |  accountId:catalog1/catalog2  |  123456789012/rmscatalog1:db1  |  GET /v1/catalogs/123456789012:rmscatalog1:db1/namespaces  | 

只有在直接调用 REST API 时，才必须提供此目录 ID 到前缀的映射。通过引擎来使用 AWS Glue Iceberg REST 目录 API 时，需要在 Iceberg REST 目录 API 设置的 `warehouse` 参数或 AWS Glue 扩展 API 设置的 `glue.id` 参数中指定 AWS Glue 目录 ID。例如，您可以参阅[将 Iceberg 集群与 Spark 结合使用](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-iceberg-use-spark-cluster.html)以了解如何将其与 EMR Spark 结合使用。

## 命名空间路径参数
<a name="ns-path-param"></a>

Iceberg REST 目录 API 路径中的命名空间可以有多级。但是，AWS Glue 仅支持单级命名空间。要访问多级目录层次结构中的命名空间，您可以通过连接到该命名空间之上的多级目录来引用该命名空间。与使用多级命名空间相比，这样可让任何支持 `catalog.namespace.table` 三部分表示法的查询引擎访问 AWS Glue 多级目录层次结构中的对象，同时不会出现兼容性问题。

# 使用 AWS Glue Iceberg REST 扩展端点连接到 Data Catalog
<a name="connect-glue-iceberg-rest-ext"></a>

 AWS Glue Iceberg REST 扩展端点提供了 Apache Iceberg REST 规范中不存在的其他 API，并提供了服务器端扫描规划功能。当您访问存储在 Amazon Redshift 托管存储中的表时，将使用这些附加 API。可以使用 Apache Iceberg AWS Glue Data Catalog 扩展从应用程序访问该端点。

**端点配置** – 使用服务端点可以访问 Redshift 托管存储中的表目录。有关区域特定的端点，请参阅 [AWS Glue service endpoints reference guide](https://docs.aws.amazon.com/general/latest/gr/glue.html#glue_region)。例如，连接到 us-east-1 区域中的 AWS Glue 时，需要配置端点 URI 属性，如下所示：

```
Endpoint : https://glue.us-east-1.amazonaws.com/extensions
```

```
catalog_name = "myredshiftcatalog"
aws_account_id = "123456789012"
aws_region = "us-east-1"
spark = SparkSession.builder \
    .config("spark.sql.defaultCatalog", catalog_name) \
    .config(f"spark.sql.catalog.{catalog_name}", "org.apache.iceberg.spark.SparkCatalog") \
    .config(f"spark.sql.catalog.{catalog_name}.type", "glue") \
    .config(f"spark.sql.catalog.{catalog_name}.glue.id", "{123456789012}:redshiftnamespacecatalog/redshiftdb") \
    .config("spark.sql.extensions","org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
    .getOrCreate()
```

# 适用于 Apache Iceberg 的 AWS Glue REST API 规范
<a name="iceberg-rest-apis"></a>

本节包含有关 AWS Glue Iceberg REST 目录 API 和 AWS Glue 扩展 API 的规范，以及使用这些 API 时的注意事项。

对 AWS Glue Data Catalog 端点的 API 请求使用 AWS 签名版本 4（SigV4）进行身份验证。请参阅[适用于 API 请求的 AWS 签名版本 4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html) 部分以了解有关 AWS SigV4 的更多信息。

访问 AWS Glue 服务端点和 AWS Glue 元数据时，应用程序将代入一个需要 `glue:getCatalog` IAM 操作的 IAM 角色。

可以使用 IAM、Lake Formation 或 Lake Formation 混合模式权限来管理对 Data Catalog 及其对象的访问权限。

Data Catalog 中的联合目录具有 Lake Formation 注册的数据位置。Lake Formation 可与 Data Catalog 结合使用，从而提供数据库式的权限来管理用户对 Data Catalog 对象的访问权限。

您可以使用 IAM、AWS Lake Formation 或 Lake Formation 混合模式权限来管理对默认 Data Catalog 及其对象的访问。

要创建、插入或删除 Lake Formation 托管式对象中的数据，必须为该 IAM 用户或角色设置具体的权限。
+ CREATE\$1CATALOG：创建目录所必需的 
+ CREATE\$1DATABASE：创建数据库所必需的
+ CREATE\$1TABLE：创建表所必需的
+ DELETE：从表中删除数据所必需的
+ DESCRIBE：读取元数据所必需的 
+ DROP：删除表或数据库所必需的
+ INSERT – 当主体需要将数据插入表中时需要
+ SELECT – 当主体需要选择表中数据时需要

有关更多信息，请参阅《AWS Lake Formation 开发人员指南》中的 [Lake Formation permissions reference](https://docs.aws.amazon.com/lake-formation/latest/dg/lf-permissions-reference.html)。

# GetConfig
<a name="get-config"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | GetConfig | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET /iceberg/v1/config  | 
| IAM 操作 |  glue:GetCatalog  | 
| Lake Formation 权限 | 不适用 | 
| CloudTrail 事件 |  glue:GetCatalog  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L67 | 

****注意事项和限制****
+ `warehouse` 查询参数必须设置为 AWS Glue 目录 ID。如果未设置，则将使用当前账户中的根目录来返回响应。有关更多信息，请参阅 [前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)。

# GetCatalog
<a name="get-catalog"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | GetCatalog | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  GET/extensions/v1/catalogs/\$1catalog\$1  | 
| IAM 操作 |  glue:GetCatalog  | 
| Lake Formation 权限 | DESCRIBE | 
| CloudTrail 事件 |  glue:GetCatalog  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L40 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。

# ListNamespaces
<a name="list-ns"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | ListNamespaces | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET/iceberg/v1/catalogs/\$1catalog\$1/namespaces  | 
| IAM 操作 |  glue:GetDatabase  | 
| Lake Formation 权限 | ALL、DESCRIBE、SELECT | 
| CloudTrail 事件 |  glue:GetDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L205 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 仅显示下一层级的命名空间。要列出更深层级的命名空间，请在目录路径参数中指定嵌套目录 ID。

# CreateNamespace
<a name="create-ns"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | CreateNamespace | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  POST/iceberg/v1/catalogs/\$1catalog\$1/namespaces  | 
| IAM 操作 |  glue:CreateDatabase  | 
| Lake Formation 权限 | ALL、DESCRIBE、SELECT | 
| CloudTrail 事件 |  glue:CreateDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L256 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能创建单级命名空间。要创建多级命名空间，必须以迭代方式创建每个层级，然后使用目录路径参数连接到该层级。

# StartCreateNamespaceTransaction
<a name="start-create-ns-transaction"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | StartCreateNamespaceTransaction | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  POST/extensions/v1/catalogs/\$1catalog\$1/namespaces  | 
| IAM 操作 |  glue:CreateDatabase  | 
| Lake Formation 权限 | ALL、DESCRIBE、SELECT | 
| CloudTrail 事件 |  glue:CreateDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L256 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能创建单级命名空间。要创建多级命名空间，必须以迭代方式创建每个层级，然后使用目录路径参数连接到该层级。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  只有当 `GetCatalog` API 调用在响应中包含 `use-extensions=true`参数时，才能调用此 API。

## LoadNamespaceMetadata
<a name="load-ns-metadata"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | LoadNamespaceMetadata | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1  | 
| IAM 操作 |  glue:GetDatabase  | 
| Lake Formation 权限 | ALL、DESCRIBE、SELECT | 
| CloudTrail 事件 |  glue:GetDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L302 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。

## UpdateNamespaceProperties
<a name="w2aac20c29c16c21c13"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | UpdateNamespaceProperties | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  POST /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/properties  | 
| IAM 操作 |  glue:UpdateDatabase  | 
| Lake Formation 权限 | ALL、ALTER | 
| CloudTrail 事件 |  glue:UpdateDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L400 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。

# DeleteNamespace
<a name="delete-ns"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | DeleteNamespace | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  DELETE/iceberg/v1/catalogs/\$1catalog\$1/namespces/\$1ns\$1  | 
| IAM 操作 |  glue:DeleteDatabase  | 
| Lake Formation 权限 | ALL、DROP | 
| CloudTrail 事件 |  glue:DeleteDatabase  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L365 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 如果数据库中有对象，则操作将失败。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  只有当 `GetCatalog` API 调用的响应中指示 `use-extensions=true` 时，才能使用此 API。

# StartDeleteNamespaceTransaction
<a name="start-delete-ns-transaction"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | StartDeleteNamespaceTransaction | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  DELETE /extensions/v1/catalogs/\$1catalog\$1/namespces/\$1ns\$1  | 
| IAM 操作 |  glue:DeleteDatabase  | 
| Lake Formation 权限 | ALL、DROP | 
| CloudTrail 事件 |  glue:DeleteDatabase  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L85 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 您只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 如果数据库中有对象，则操作将失败。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  只有当 `GetCatalog` API 调用的响应中指示 `use-extensions=true` 时，才能使用此 API。

# ListTables
<a name="list-tables"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | ListTables | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables  | 
| IAM 操作 |  glue:GetTables  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTables  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L463 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 将列出所有表，包括非 Iceberg 表。要确定某个表是否可以作为 Iceberg 表加载，请调用 `LoadTable` 操作。

# CreateTable
<a name="create-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | CreateTable | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables  | 
| IAM 操作 |  glue:CreateTable  | 
| Lake Formation 权限 | ALL、CREATE\$1TABLE | 
| CloudTrail 事件 |  glue:CreateTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L497 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 不支持将 `CreateTable` 与暂存功能结合使用。如果指定了 `stageCreate` 查询参数，则操作将失败。这意味着不支持类似于 `CREATE TABLE AS SELECT` 的操作，您可以通过组合使用 `CREATE TABLE` 和 `INSERT INTO` 来解决问题。
+ `CreateTable` API 操作不支持 `state-create = TRUE` 选项。

# StartCreateTableTransaction
<a name="start-create-table-transaction"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | CreateTable | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  POST/extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables  | 
| IAM 操作 |  glue:CreateTable  | 
| Lake Formation 权限 | ALL、CREATE\$1TABLE | 
| CloudTrail 事件 |  glue:CreateTable  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L107 | 

****注意事项和限制****
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 不支持将 `CreateTable` 与暂存功能结合使用。如果指定了 `stageCreate` 查询参数，则操作将失败。这意味着不支持类似于 `CREATE TABLE AS SELECT` 的操作，用户应组合使用 `CREATE TABLE` 和 `INSERT INTO` 来解决问题。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  只有当 `GetCatalog` API 调用的响应中指示 `use-extensions=true` 时，才能使用此 API。

# LoadTable
<a name="load-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | LoadTable | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  GET /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:GetTable  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L616 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 不支持将 `CreateTable` 与暂存功能结合使用。如果指定了 `stageCreate` 查询参数，则操作将失败。这意味着不支持类似于 `CREATE TABLE AS SELECT` 的操作，用户应组合使用 `CREATE TABLE` 和 `INSERT INTO` 来解决问题。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  只有当 `GetCatalog` API 调用的响应中指示 `use-extensions=true` 时，才能使用此 API。

# ExtendedLoadTable
<a name="extended-load-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | LoadTable | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  GET /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:GetTable  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTable  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L134 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 快照查询参数仅支持 `all` 模式。
+ 与 `LoadTable` API 相比，`ExtendedLoadTable` API 的差异在于以下方面：
  +  并未严格强制要求所有字段都可用。
  + 在响应的配置字段中提供了以下额外参数：  
**额外参数**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/glue/latest/dg/extended-load-table.html)

# PreplanTable
<a name="preplan-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | PreplanTable | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  POST /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1/preplan  | 
| IAM 操作 |  glue:GetTable  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTable  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L211 | 

**注意事项**
+ 目录路径参数应遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 此 API 的调用者应始终根据页面令牌来确定是否还有剩余的结果需要获取。如果服务器端仍在处理中但无法在给定的响应时间内生成任何结果，则可能出现除分页令牌外其他页面项为空的响应。
+  只有当 `ExtendedLoadTable` API 响应包含 `aws.server-side-capabilities.scan-planning=true` 时，您才能使用此 API。

# PlanTable
<a name="plan-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | PlanTable | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  POST /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1/plan  | 
| IAM 操作 |  glue:GetTable  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTable  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L243 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 此 API 的调用者应始终根据页面令牌来确定是否还有剩余的结果需要获取。如果服务器端仍在处理中但无法在给定的响应时间内生成任何结果，则可能出现除分页令牌外其他页面项为空的响应。
+  只有当 `ExtendedLoadTable` API 响应包含 `aws.server-side-capabilities.scan-planning=true` 时，您才能使用此 API。

# TableExists
<a name="table-exists"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | TableExists | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  HEAD/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:GetTable  | 
| Lake Formation 权限 | ALL、SELECT、DESCRIBE | 
| CloudTrail 事件 |  glue:GetTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L833 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。

# UpdateTable
<a name="update-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | UpdateTable | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  POST /iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:UpdateTable  | 
| Lake Formation 权限 | ALL、ALTER | 
| CloudTrail 事件 |  glue:UpdateTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L677 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。

# StartUpdateTableTransaction
<a name="start-update-table-transaction"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | StartUpdateTableTransaction | 
| 类型 | AWS Glue 扩展 API | 
| REST 路径 |  POST/extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:UpdateTable  | 
| Lake Formation 权限 |  ALL、ALTER  | 
| CloudTrail 事件 |  glue:UpdateTable  | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L154 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 此 API 是异步的，并且会返回一个可以用于通过 `CheckTransactionStatus` API 调用进行跟踪的事务 ID。
+  也可以通过此 API 执行 `RenamTable` 操作。发生这种情况时，调用者还必须拥有要重命名的表的 glue:CreateTable 或 LakeFormation CREATE\$1TABLE 权限。
+  只有当 `ExtendedLoadTable` API 响应包含 `aws.server-side-capabilities.scan-planning=true` 时，您才能使用此 API。

# DeleteTable
<a name="delete-table"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | DeleteTable | 
| 类型 |  Iceberg REST 目录 API  | 
| REST 路径 |  DELETE/iceberg/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:DeleteTable  | 
| Lake Formation 权限 | ALL、DROP | 
| CloudTrail 事件 |  glue:DeleteTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L793 | 

**注意事项**
+ 目录路径参数应遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ `DeleteTable` API 操作支持 purge 选项。当清除设置为 `true` 时，表数据会被删除，否则数据不会被删除。对于 Amazon S3 中的表，此操作不会删除表数据。当表存储在 Amazon S3 中且 `purge = TRUE,` 时，此操作将会失败。

  对于存储在 Amazon Redshift 托管存储中的表，该操作将删除表数据，类似于 Amazon Redshift 中的 `DROP TABLE` 行为。当表存储在 Amazon Redshift 中且 `purge = FALSE` 时，操作会失败。
+ 不支持 `purgeRequest=true`。

# StartDeleteTableTransaction
<a name="start-delete-table-transaction"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | StartDeleteTableTransaction | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  DELETE /extensions/v1/catalogs/\$1catalog\$1/namespaces/\$1ns\$1/tables/\$1table\$1  | 
| IAM 操作 |  glue:DeleteTable  | 
| Lake Formation 权限 | ALL、DROP | 
| CloudTrail 事件 |  glue:DeleteTable  | 
| Open API 定义 | https://github.com/apache/iceberg/blob/apache-iceberg-1.6.1/open-api/rest-catalog-open-api.yaml\$1L793 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。
+ 只能在 REST 路径参数中指定单级命名空间。有关更多信息，请参阅[命名空间路径参数](connect-glu-iceberg-rest.md#ns-path-param)部分。
+ 不支持 `purgeRequest=false`。
+  此 API 是异步的，并且会返回一个可以通过 `CheckTransactionStatus` 进行跟踪的事务 ID。

# CheckTransactionStatus
<a name="check-transaction-status"></a>


**一般信息**  

|  |  | 
| --- |--- |
| 操作名称 | CheckTransactionStatus | 
| 类型 |  AWS Glue 扩展 API  | 
| REST 路径 |  POST/extensions/v1/transactions/status  | 
| IAM 操作 |  权限与启动事务的操作相同  | 
| Lake Formation 权限 | 权限与启动事务的操作相同 | 
| Open API 定义 | https://github.com/awslabs/glue-extensions-for-iceberg/blob/main/glue-extensions-api.yaml\$1L273 | 

**注意事项**
+ 目录路径参数必须遵循[前缀和目录路径参数](connect-glu-iceberg-rest.md#prefix-catalog-path-parameters)部分中描述的样式。

# 从独立 Spark 应用程序连接到 Data Catalog
<a name="connect-gludc-spark"></a>

您可以使用 Apache Iceberg 连接器从独立应用程序连接到 Data Catalog。

1. 为 Spark 应用程序创建 IAM 角色。

1. 使用 Iceberg 连接器连接到 AWS Glue Iceberg Rest 端点。

   ```
   # configure your application. Refer to https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html for best practices on configuring environment variables.
   export AWS_ACCESS_KEY_ID=$(aws configure get appUser.aws_access_key_id)
   export AWS_SECRET_ACCESS_KEY=$(aws configure get appUser.aws_secret_access_key)
   export AWS_SESSION_TOKEN=$(aws configure get appUser.aws_secret_token)
   
   export AWS_REGION=us-east-1
   export REGION=us-east-1
   export AWS_ACCOUNT_ID = {specify your aws account id here}
   
   ~/spark-3.5.3-bin-hadoop3/bin/spark-shell \
       --packages org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.6.0 \
       --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
       --conf "spark.sql.defaultCatalog=spark_catalog" \
       --conf "spark.sql.catalog.spark_catalog=org.apache.iceberg.spark.SparkCatalog" \
       --conf "spark.sql.catalog.spark_catalog.type=rest" \
       --conf "spark.sql.catalog.spark_catalog.uri=https://glue.us-east-1.amazonaws.com/iceberg" \
       --conf "spark.sql.catalog.spark_catalog.warehouse = {AWS_ACCOUNT_ID}" \
       --conf "spark.sql.catalog.spark_catalog.rest.sigv4-enabled=true" \
       --conf "spark.sql.catalog.spark_catalog.rest.signing-name=glue" \
       --conf "spark.sql.catalog.spark_catalog.rest.signing-region=us-east-1" \
       --conf "spark.sql.catalog.spark_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO" \
       --conf "spark.hadoop.fs.s3a.aws.credentials.provider=org.apache.hadoop.fs.s3a.SimpleAWSCredentialProvider"
   ```

1. 查询 Data Catalog 中的数据。

   ```
   spark.sql("create database myicebergdb").show()
   spark.sql("""CREATE TABLE myicebergdb.mytbl (name string) USING iceberg location 's3://bucket_name/mytbl'""")
   spark.sql("insert into myicebergdb.mytbl values('demo') ").show()
   ```

# Amazon Redshift 与 Apache Iceberg 之间的数据映射
<a name="data-mapping-rs-iceberg"></a>

Redshift 和 Iceberg 支持各种数据类型。以下兼容性矩阵概括介绍了在这两个数据系统之间映射数据时的支持和限制。有关相应数据系统中支持的数据类型的更多详细信息，请参阅 [Amazon Redshift 数据类型](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html)和 [Apache Iceberg Table Specifications](https://iceberg.apache.org/spec/#primitive-types)。


| Redshift 数据类型 | 别名 | Iceberg 数据类型 | 
| --- | --- | --- | 
| SMALLINT | INT2 | 整数 | 
| INTEGER | INT、INT4 | 整数 | 
| BIGINT | INT8 | 长整数 | 
| DECIMAL | NUMERIC | decimal | 
| REAL | FLOAT4 | 浮点数 | 
| REAL | FLOAT4 | 浮点数 | 
| DOUBLE PRECISION | FLOAT8、FLOAT | double | 
| CHAR | CHARACTER、NCHAR | 字符串 | 
| VARCHAR | CHARACTER VARYING、NVARCHAR | 字符串 | 
| BPCHAR |  | 字符串 | 
| TEXT |  | 字符串 | 
| DATE |  | date | 
| TIME | TIME WITHOUT TIMEZONE | 时间 | 
| TIME | TIME WITH TIMEZONE | 不支持 | 
| TIMESTAMP | TIMESTAMP WITHOUT TIMEZONE | TIMESTAMP | 
| TIMESTAMPZ | TIMESTAMP WITH TIMEZONE | TIMESTAMPZ | 
| INTERVAL YEAR TO MONTH |  | 不支持 | 
| INTERVAL DAY TO SECOND |  | 不支持 | 
| BOOLEAN | BOOL | 布尔 | 
| HLLSKETCH |  | 不支持 | 
| SUPER |  | 不支持 | 
| VARBYTE | VARBINARY，BINARY VARYING | binary | 
| GEOMETRY |  | 不支持 | 
| GEOGRAPHY |  | 不支持 | 

# 使用 AWS Glue Glue Iceberg REST 目录 API 时的注意事项和限制
<a name="limitation-glue-iceberg-rest-api"></a>

下面是使用 Apache Iceberg REST 目录数据定义语言 (DDL) 操作行为时的注意事项和限制。

**注意事项**
+  **`RenameTable` API 行为**：Amazon Redshift 中的表支持 `RenameTable` 操作，但 Amazon S3 中不支持。
+  **Amazon Redshift 中命名空间和表的 DDL 操作**：Amazon Redshift 中命名空间和表的创建、更新、删除操作是异步操作，因为它们依赖于 Amazon Redshift 托管工作组何时可用以及是否有冲突的 DDL 和 DML 事务正在进行，并且操作必须等待锁定，然后再尝试提交更改。

**限制**
+  AWS Glue Glue Iceberg REST 目录不支持 Apache Iceberg REST 规范中的视图 API。