# 将元数据导出到 S3 表类数据存储服务（预览）
<a name="catalog-export-s3-tables"></a>

**注意**  
目录元数据导出功能作为预览功能提供。此功能在正式发布之前可能会更改。

## 概述
<a name="catalog-export-overview"></a>

您可以将 Amazon Glue Data Catalog 元数据导出到存储在 Amazon S3 表类数据存储服务中的托管目录系统表。当您启用 S3 表类数据存储服务导出时，您的技术和业务元数据将存储在 Amazon 托管的 `aws-catalog` 表存储桶的只读 Apache Iceberg 表中，因此可以使用 SQL 以及 Amazon 分析服务（如 Amazon Redshift 和 Amazon EMR）对其进行查询。

在 `aws-catalog` 表存储桶中，系统表位于以下命名空间中：
+ `glue`：包含 `tables` 和 `table_columns`。
+ `catalog_metadata`：包含 `glossaries`、`glossary_terms`、`associated_glossary_terms`、`attachments` 和 `item_attachments`。

目前支持以下系统表：


| 系统表 | 包含 | 
| --- | --- | 
| `tables` | Data Catalog 中每个表的技术和业务元数据，例如其名称、数据库、描述、存储位置和格式。 | 
| `table_columns` | 每个目录表的列，包括每列的名称、数据类型、描述以及该列是否为分区键。 | 
| `glossaries` | 目录中的业务术语表，包括每个术语表的名称、描述和状态。 | 
| `glossary_terms` | 术语表中定义的术语，包括每个术语的名称、描述、父术语表和状态。 | 
| `associated_glossary_terms` | 术语表术语与资产之间的关联，包括资产标识符和术语表术语标识符。 | 
| `attachments` | 在资产级别附加的自定义表单元数据，包括表单类型和附件内容。 | 
| `item_attachments` | 附加到资产内各项目（例如各个列）的自定义表单元数据，包括可迭代表单名称、项目名称、表单类型和附件内容。 | 

有关每个表的完整列级架构，请参阅 [目录系统表参考](#catalog-export-system-tables-reference)。

## 目录元数据导出的工作原理
<a name="catalog-export-how-it-works"></a>

启用导出功能后，Data Catalog 会对您现有的目录元数据执行一次性回填，然后在您进行更改时持续更新系统表。新写入或更新的元数据通常会在约 5 分钟内显示在系统表中。

系统表位于 `aws-catalog` 表存储桶内的 `glue` 和 `catalog_metadata` 命名空间中。当您的目录中首次出现某类元数据时，给定的系统表才会显示。例如，如果您启用了导出功能，并且目录仅包含表和数据库，则只能看到与表相关的系统表。术语表系统表将在您创建第一个术语表后显示。

## 使用 Amazon CLI 启用目录元数据导出
<a name="catalog-export-enable"></a>

目录元数据导出是账户级别的设置。您可以使用 Amazon CLI 启用或禁用此功能。

### 先决条件
<a name="catalog-export-prerequisites"></a>

您使用的 IAM 身份必须具有调用导出配置操作 `glue:PutDataCatalogExportConfiguration` 和 `glue:GetDataCatalogExportConfiguration` 以及 `s3tables:CreateTable` 的权限。有关 S3 表类数据存储服务权限的更多信息，请参阅 *Amazon Simple Storage Service 用户指南*中的[在 S3 表存储桶中创建表](https://docs.amazonaws.cn/AmazonS3/latest/userguide/s3-tables-create.html)。

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "glue:PutDataCatalogExportConfiguration",
                "glue:GetDataCatalogExportConfiguration"
            ],
            "Resource": "*"
        }
    ]
}
```

S3 表类数据存储服务中的所有数据（包括 Data Catalog 元数据）均默认使用 SSE-S3 加密进行加密。您可以选择使用 Amazon KMS 密钥（SSE-KMS）加密目录导出。如果您选择使用 Amazon KMS 密钥加密，则必须通过采取以下步骤添加额外的权限：

1. 向 Data Catalog 导出服务主体和 S3 表类数据存储服务维护服务主体授予使用 KMS 密钥（密钥策略）的权限。

1. 向运行导出的 IAM 主体授予使用 KMS 密钥（身份策略）的权限。

#### 向 Data Catalog 导出服务主体和 S3 表类数据存储服务维护服务主体授予对 KMS 密钥的权限
<a name="export-kms-permissions-service-principal"></a>

要允许 Amazon Glue 导出加密的目录元数据，并对导出的表执行自动表维护（例如压缩和未引用文件移除），必须向以下服务主体授予对您的 KMS 密钥的访问权限：
+ `systemtables.catalog.amazonaws.com`：将加密的目录元数据导出到 S3 表类数据存储服务。
+ `maintenance.s3tables.amazonaws.com`：对导出的表执行自动表维护。

Amazon Glue 写入名为 `aws-catalog` 的 Amazon 托管表存储桶。用于加密 S3 表类数据存储服务导出的 KMS 密钥不需要与用于加密静态 Data Catalog 的 KMS 密钥相同。Amazon Glue 仅支持对称 KMS 密钥。要授予这些服务主体访问权限，您可以使用以下示例密钥策略。在此策略中，向 `maintenance.s3tables.amazonaws.com` 服务主体授予使用特定 KMS 密钥对 `aws-catalog` 表存储桶中的表进行加密和解密的权限。有关 S3 表类数据存储服务维护服务主体的更多信息，请参阅 *Amazon Simple Storage Service 用户指南* 中的 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](https://docs.amazonaws.cn/AmazonS3/latest/userguide/s3-tables-kms-permissions.html)。

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowSystemTablesDescribeKey",
            "Effect": "Allow",
            "Principal": {
                "Service": "systemtables.catalog.amazonaws.com"
            },
            "Action": [
                "kms:DescribeKey"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{123456789012}}"
                }
            }
        },
        {
            "Sid": "AllowSystemTablesEncryptDecrypt",
            "Effect": "Allow",
            "Principal": {
                "Service": "systemtables.catalog.amazonaws.com"
            },
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{123456789012}}"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3tables:{{us-east-1}}:{{123456789012}}:bucket/aws-catalog/table/*",
                    "kms:ViaService": "s3.{{us-east-1}}.amazonaws.com"
                }
            }
        },
        {
            "Sid": "AllowS3TablesMaintenanceEncryptDecrypt",
            "Effect": "Allow",
            "Principal": {
                "Service": "maintenance.s3tables.amazonaws.com"
            },
            "Action": [
                "kms:GenerateDataKey",
                "kms:Decrypt"
            ],
            "Resource": "*",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{123456789012}}"
                },
                "StringLike": {
                    "kms:EncryptionContext:aws:s3:arn": "arn:aws:s3tables:{{us-east-1}}:{{123456789012}}:bucket/aws-catalog/*"
                }
            }
        }
    ]
}
```

#### 主体导出所需的 IAM 权限
<a name="export-kms-permissions-exporting"></a>

向运行导出的主体授予以下权限。以下策略授予 IAM 主体使用 `glue_catalog_id` 加密上下文（值为您的 `catalogId`）解密特定 Amazon Glue Data Catalog 的访问权限。

```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowDescribeKey",
            "Effect": "Allow",
            "Action": [
                "kms:DescribeKey"
            ],
            "Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{123456789012}}"
                }
            }
        },
        {
            "Sid": "AllowExportOfGlueDataCatalogByCatalogId",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "arn:aws:kms:{{us-east-1}}:{{123456789012}}:key/{{1234abcd-12ab-34cd-56ef-1234567890ab}}",
            "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "{{123456789012}}",
                    "kms:EncryptionContext:glue_catalog_id": "{{123456789012}}"
                }
            }
        }
    ]
}
```

### 要启用目录元数据导出
<a name="catalog-export-enable-procedure"></a>

1. 运行以下命令以启用导出：

   ```
   aws glue put-data-catalog-export-configuration \
       --export-setting ENABLED
   ```

1. 通过运行以下命令确认配置：

   ```
   aws glue get-data-catalog-export-configuration
   ```

   响应示例：

   ```
   {
       "ExportSetting": "ENABLED",
       "Status": "ENABLED",
       "S3TableBucketArn": "arn:aws:s3tables:us-east-1:111122223333:bucket/aws-catalog"
   }
   ```

   随着初始回填的进行，`Status` 字段会从 `ENABLING` 转换为 `ENABLED`。

### 要禁用目录元数据导出
<a name="catalog-export-disable-procedure"></a>

运行以下命令：

```
aws glue put-data-catalog-export-configuration \
    --export-setting DISABLED
```

## 目录系统表参考
<a name="catalog-export-system-tables-reference"></a>

所有系统表都位于 `aws-catalog` 表存储桶内的 `glue` 或 `catalog_metadata` 命名空间中。每个表都包含以下系统列：


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `ingestion_time` | timestamp | 将记录摄取到系统表的时间（UTC）。 | 
| `schema_version` | 字符串 | 表的架构版本标识符。 | 

### 表
<a name="catalog-export-ref-glue-tables"></a>

每个目录表包含一行。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `id` | 字符串 | 表的唯一标识符。 | 
| `catalog_id` | 字符串 | 目录标识符。 | 
| `catalog_name` | 字符串 | 目录名称。 | 
| `update_time` | timestamp | 上次更新时间戳。 | 
| `created_time` | timestamp | 创建时间戳。 | 
| `created_by_id` | 字符串 | 创建表的主体的标识符。 | 
| `created_by_type` | 字符串 | 创建主体的类型。 | 
| `description` | 字符串 | 表描述。 | 
| `name` | 字符串 | 表名称。 | 
| `namespace` | 字符串 | 表的命名空间。 | 
| `region_name` | 字符串 | Amazon 区域。 | 
| `tags` | map<string, string> | 资源标签。 | 
| `type` | 字符串 | 资产类型。 | 
| `updated_by_id` | 字符串 | 上次更新该表的主体的标识符。 | 
| `updated_by_type` | 字符串 | 更新主体的类型。 | 
| `database_name` | 字符串 | 包含该表的数据库。 | 
| `input_format` | 字符串 | 输入格式类。 | 
| `lake_formation_registration` | 字符串 | Amazon Lake Formation 注册状态。 | 
| `output_format` | 字符串 | 输出格式类。 | 
| `owner` | 字符串 | 表拥有者。 | 
| `retention` | int | 保留期。 | 
| `serde_library` | 字符串 | 序列化/反序列化库。 | 
| `table_data_format` | 字符串 | 数据格式。 | 
| `table_data_location` | 字符串 | 数据位置 URI。 | 
| `table_format` | 字符串 | 表格式（例如 Iceberg、Hudi）。 | 
| `table_type` | 字符串 | 表类型。 | 

### table\_columns
<a name="catalog-export-ref-glue-table-columns"></a>

目录表中每列包含一行。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `id` | 字符串 | `assetId#columnName` 格式的复合标识符。 | 
| `asset_id` | 字符串 | 父表的标识符。 | 
| `column_name` | 字符串 | 列名称。 | 
| `description` | 字符串 | 列描述。 | 
| `type` | 字符串 | 列数据类型。 | 
| `is_partition_key` | 布尔值 | 此列是否为分区键。 | 

### attachments
<a name="catalog-export-ref-attachments"></a>

包含资产级自定义表单附件（资产上的每个附件对应一行）。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `asset_id` | 字符串 | 父资产的标识符。 | 
| `attachment_name` | 字符串 | 附件名称。 | 
| `form_type_id` | 字符串 | 内容的已注册表单类型。 | 
| `content_json` | 字符串 | 以 JSON 编码字符串表示的附件内容。 | 

### item\_attachments
<a name="catalog-export-ref-item-attachments"></a>

包含可迭代表单中各项目（例如单个列）的附件。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `asset_id` | 字符串 | 父资产的标识符。 | 
| `iterable_form_name` | 字符串 | 可迭代表单的名称（例如，列）。 | 
| `item_name` | 字符串 | 项目的名称（例如，列名称）。 | 
| `attachment_name` | 字符串 | 附件名称。 | 
| `form_type_id` | 字符串 | 内容的已注册表单类型。 | 
| `content_json` | 字符串 | 以 JSON 编码字符串表示的附件内容。 | 

### 词汇表
<a name="catalog-export-ref-glossaries"></a>

每个术语表对应一行。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `id` | 字符串 | 术语表唯一标识符。 | 
| `description` | 字符串 | 术语表描述。 | 
| `name` | 字符串 | 术语表名称。 | 
| `status` | 字符串 | 状态（`ENABLED` 或 `DISABLED`）。 | 

### glossary\_terms
<a name="catalog-export-ref-glossary-terms"></a>

每个术语表术语对应一行。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `id` | 字符串 | 术语唯一标识符。 | 
| `glossary_id` | 字符串 | 父术语表的标识符。 | 
| `long_description` | 字符串 | 详细的术语描述。 | 
| `name` | 字符串 | 术语名称。 | 
| `short_description` | 字符串 | 简要术语描述。 | 
| `status` | 字符串 | 状态（`ENABLED` 或 `DISABLED`）。 | 

### associated\_glossary\_terms
<a name="catalog-export-ref-associated-glossary-terms"></a>

术语表术语与资产之间的每个关联包含一行。


| 列 | 类型 | 说明 | 
| --- | --- | --- | 
| `asset_id` | 字符串 | 术语表术语所关联资产的标识符。 | 
| `glossary_term_id` | 字符串 | 与资产关联的术语表术语的标识符。联接到 `glossary_terms` 表。 | 

## 查询目录系统表
<a name="catalog-export-querying"></a>

在使用 Amazon 分析服务（如 Amazon EMR）查询导出到 S3 表类数据存储服务的目录元数据之前，必须对 Amazon 托管的 `aws-catalog` 表存储桶启用分析集成，并配置 Amazon Lake Formation 权限。

### 先决条件
<a name="catalog-export-querying-prerequisites"></a>
+ 目录元数据导出已启用，状态为 `ENABLED`。
+ 访问或其他分析服务。
+ 启用导出后等待 5 分钟，数据即可使用。

### 集成概述
<a name="catalog-export-querying-integration"></a>

有关将 S3 表类数据存储服务与 Amazon 分析服务集成的详细信息（包括先决条件、IAM 角色配置和分步操作流程），请参阅《Amazon Simple Storage Service 用户指南》**中的[将 Amazon S3 表类数据存储服务与 Amazon 分析服务集成](https://docs.amazonaws.cn/AmazonS3/latest/userguide/s3-tables-integrating-aws.html)。

启用 S3 表类数据存储服务导出并设置分析集成后，您可以使用 Amazon 分析服务（如 Amazon Redshift 和 Amazon EMR）查询 Data Catalog 元数据。这使您能够使用标准 SQL 执行元数据审计和分析。

### 示例查询
<a name="catalog-export-querying-examples"></a>

**列出所有目录表及其数据库和格式**  


```
SELECT id, name, database_name, table_format
FROM aws_catalog.glue.tables;
```

**查找特定表中包含描述的列**  


```
SELECT column_name, type, description
FROM aws_catalog.glue.table_columns
WHERE asset_id = '{{table-id}}';
```

**将术语表术语与其父术语表联接**  


```
SELECT g.name AS glossary_name,
       t.name AS term_name,
       t.short_description
FROM aws_catalog.catalog_metadata.glossary_terms t
JOIN aws_catalog.catalog_metadata.glossaries g
    ON t.glossary_id = g.id
WHERE g.status = 'ENABLED';
```

**查找与特定术语表术语关联的表**  


```
SELECT t.name, t.database_name, gt.name AS term_name
FROM aws_catalog.glue.tables t
JOIN aws_catalog.catalog_metadata.associated_glossary_terms agt
    ON agt.asset_id = t.id
JOIN aws_catalog.catalog_metadata.glossary_terms gt
    ON gt.id = agt.glossary_term_id
WHERE gt.name = '{{term-name}}';
```

**从自定义表单附件中提取字段**  


```
SELECT asset_id,
       attachment_name,
       json_extract_scalar(content_json, '$.owner') AS data_owner
FROM aws_catalog.catalog_metadata.attachments
WHERE form_type_id = '{{your-form-type-id}}';
```