querying-aws-sagemaker-catalog

查询 AWS SageMaker 目录系统表

概述

建议与 AWS MCP 服务 搭配使用，以便在沙盒中执行并进行审计日志记录。以下所有命令均使用 AWS CLI，可在任何已配置 AWS 凭证的环境中运行。

Amazon SageMaker Unified Studio（其目录功能在下文中称为 SageMaker Catalog）会将资产元数据导出为 AWS 托管的 aws-sagemaker-catalog 表存储桶中的 Apache Iceberg 每日快照表。这样无需构建自定义 ETL，即可通过 SQL 查询整个数据目录中的资产清单，包括资产数量、治理缺口、所有权审计和历史对比。

数据按 snapshot_time 分区，每天导出一次（约在各区域的午夜）。该表为只读。

决策树

用户意图	使用此技能？	替代方案
对目录状态进行 SQL 分析（数量、治理、趋势）	是	—
历史对比（“目录上周有哪些变化”）	是 — 通过 snapshot_time 进行时间点查询	—
查找没有所有者或描述的资产	是	—
按名称或概念查找特定表	否	finding-data-lake-assets 或 Glue Discovery search
交互式浏览／枚举目录	否	exploring-data-catalog
对某个表中的数据运行查询	否	querying-data-lake
管理目录元数据（添加描述、标签）	否	Glue Discovery put-form-type / associate-glossary-terms

常见任务

1. 检查是否已配置

aws datazone get-data-export-configuration \
  --domain-identifier <DOMAIN_ID> \
  --region <REGION>

• 如果不存在域：aws datazone list-domains --region <REGION>
• 如果未启用导出：引导用户启用。
• 每个账户的每个区域只能有一个域。

验证表存储桶是否存在：

aws s3tables list-table-buckets --region <REGION> \
  --query "tableBuckets[?name=='aws-sagemaker-catalog']"

2. 启用

使用 KMS 加密（生产环境推荐）：

aws datazone put-data-export-configuration \
  --domain-identifier <DOMAIN_ID> \
  --region <REGION> \
  --enable-export \
  --encryption-configuration kmsKeyArn=<KMS_KEY_ARN>,sseAlgorithm=aws:kms

注意：创建后无法更改加密方式。对于敏感目录数据，始终指定 KMS。

不使用加密（仅用于快速测试）：

aws datazone put-data-export-configuration \
  --domain-identifier <DOMAIN_ID> \
  --region <REGION> \
  --enable-export

24 小时内即可获取首批数据。请参阅： 导出资产元数据

3. 验证查询权限

需要：

• 在 Glue 中注册 S3 Tables 联合目录（s3tablescatalog）
• 在该表上授予 Lake Formation SELECT + DESCRIBE 权限

授予访问权限：

aws lakeformation grant-permissions \
  --principal DataLakePrincipalIdentifier=<ROLE_ARN> \
  --resource '{"Table": {"CatalogId": "<ACCOUNT>:s3tablescatalog/aws-sagemaker-catalog", "DatabaseName": "asset_metadata", "Name": "asset"}}' \
  --permissions DESCRIBE SELECT \
  --region <REGION>

4. 查询

查询语法：

"s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"

限制：

• 必须始终按 snapshot_time 进行筛选 — 否则查询会扫描所有历史快照并返回重复项

• 执行前必须确认工作组和输出位置

• 查询当前状态时，默认使用 DATE(snapshot_time) = CURRENT_DATE

• 应使用此技能中记录的关键列来构建查询。如果需要完整架构，请运行一次 get-tables：

  aws glue get-tables --catalog-id "<ACCOUNT>:s3tablescatalog/aws-sagemaker-catalog" --database-name "asset_metadata" --region <REGION>
  

关键列：

列	内容	用途
snapshot_time	分区键 — 每日快照时间戳	始终按此列筛选
asset_id	唯一的目录资产标识符	查找时使用的主键
resource_type_enum	GlueTable、RedshiftTable、S3Collection 等	按资产类型筛选
resource_id	ARN 或原生标识符	与源系统交叉引用
asset_name	便于业务理解的名称	显示、搜索
resource_name	技术名称（表名、前缀）	筛选
business_description	业务背景（未提供时为 NULL）	治理缺口
extended_metadata	map<string,string> — 灵活的键值属性	使用方括号表示法：extended_metadata['owningEntityId']
asset_created_time	资产首次出现在目录中的时间	增长分析
asset_updated_time	上次修改时间	时效性检查

当前目录状态：

SELECT resource_type_enum, COUNT(*) as count
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"
WHERE DATE(snapshot_time) = CURRENT_DATE
GROUP BY resource_type_enum
ORDER BY count DESC;

没有业务描述的资产：

SELECT asset_name, resource_name, resource_type_enum, account_id
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"
WHERE DATE(snapshot_time) = CURRENT_DATE
  AND business_description IS NULL;

过去 30 天的资产增长情况：

SELECT DATE(snapshot_time) as date, COUNT(*) as total_assets
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"
WHERE DATE(snapshot_time) >= CURRENT_DATE - INTERVAL '30' DAY
GROUP BY DATE(snapshot_time)
ORDER BY date DESC;

时间旅行 — 对比当前与 7 天前的状态（新增的描述）：

SELECT t.asset_id, t.resource_name,
       p.business_description as before,
       t.business_description as now
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset" t
JOIN "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset" p
  ON t.asset_id = p.asset_id
WHERE DATE(t.snapshot_time) = CURRENT_DATE
  AND DATE(p.snapshot_time) = CURRENT_DATE - INTERVAL '7' DAY
  AND p.business_description IS NULL
  AND t.business_description IS NOT NULL;

按所有者查看资产：

SELECT extended_metadata['owningEntityId'] as owner, COUNT(*) as count
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"
WHERE DATE(snapshot_time) = CURRENT_DATE
  AND extended_metadata['owningEntityId'] IS NOT NULL
GROUP BY extended_metadata['owningEntityId']
ORDER BY count DESC;

按元数据表单字段筛选：

SELECT *
FROM "s3tablescatalog/aws-sagemaker-catalog"."asset_metadata"."asset"
WHERE DATE(snapshot_time) = CURRENT_DATE
  AND extended_metadata['<metadata-form-name>.<field-name>'] = '<field-value>';

关键行为

• 每日快照 — 按区域在午夜前后导出
• 始终按 snapshot_time 筛选 — 否则会获取所有历史记录（产生重复项且速度缓慢）
• 每个账户和区域仅限一个域 — 如需切换域，先删除配置
• 不收取额外费用，仅需支付 S3 Tables 存储和 Athena 查询费用
• 只读 — 如需更新资产元数据，请使用 Glue Discovery API 或 SageMaker Unified Studio

故障排除

错误	原因	解决方法
找不到 aws-sagemaker-catalog 存储桶	未启用导出	运行 put-data-export-configuration --enable-export
使用 CURRENT_DATE 时结果为空	首次导出尚未运行（最多需要 24 小时）	请等待；尝试使用昨天的日期
查询时出现 AccessDenied	缺少 Lake Formation 授权	授予表的 SELECT + DESCRIBE 权限
CATALOG_NOT_FOUND	S3 Tables 尚未在 Glue 中注册	启用集成：S3 控制台 > 表存储桶 > 启用集成
结果中有重复行	缺少 snapshot_time 筛选条件	添加 WHERE DATE(snapshot_time) = CURRENT_DATE
extended_metadata 键返回 NULL	该资产不存在此键	检查可用键：SELECT DISTINCT key FROM ... CROSS JOIN UNNEST(map_keys(extended_metadata)) AS t(key) WHERE DATE(snapshot_time) = CURRENT_DATE
无法更新导出加密设置	仅能在创建时设置加密	删除并重新创建导出配置

安全注意事项

数据敏感性：目录元数据会暴露组织结构，包括资产名称、所有者、账户 ID、命名约定和内部资源标识符。默认情况下，请将查询结果视为敏感信息。

静态加密：创建导出配置时，务必启用 KMS 加密。创建后无法更改加密设置。此外，请在 Athena 工作组的输出存储桶上配置 SSE-KMS。

最小权限访问：仅向需要目录分析的角色授予特定 asset_metadata.asset 表的 Lake Formation SELECT + DESCRIBE 权限。避免授予对整个 aws-sagemaker-catalog 存储桶的访问权限。

审计跟踪：启用 CloudTrail 日志记录，以跟踪谁在查询目录元数据。需记录 DataZone（PutDataExportConfiguration、GetDataExportConfiguration）、Athena（StartQueryExecution、GetQueryResults）和 S3 Tables API 调用。

凭证卫生：使用带有临时凭证的 IAM 角色进行查询。避免为访问目录元数据的用户使用长期访问密钥。不再需要访问权限时，请缩小主体的权限范围或轮换主体。

其他资源

• 导出资产元数据
• 资产表架构
• 将 S3 Tables 与分析服务集成
• Lake Formation 权限