querying-aws-sagemaker-catalog

AWS SageMaker Catalog システムテーブルをクエリする

概要

サンドボックス実行と監査ログ記録には、AWS MCP サーバーとの併用が最適です。以下のコマンドはすべて AWS CLI を使用しており、AWS 認証情報が設定された任意の環境で動作します。

Amazon SageMaker Unified Studio（以下ではカタログ機能を SageMaker Catalog と呼びます）は、アセットのメタデータを、AWS が管理する aws-sagemaker-catalog テーブルバケット内の Apache Iceberg テーブルに日次スナップショットとしてエクスポートします。これにより、カスタム ETL を構築することなく、データカタログ全体のインベントリに対して SQL クエリを実行できます。アセット数、ガバナンスの不備、所有者の監査、履歴の比較などが可能です。

データは snapshot_time でパーティション分割され、リージョンごとに毎日 1 回（深夜頃）エクスポートされます。このテーブルは読み取り専用です。

判断フローチャート

ユーザーの目的	このスキルを使用しますか？	代替手段
カタログの状態に関する 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>
• エクスポートが有効でない場合：有効にするようユーザーに案内します。
• アカウントおよびリージョンごとにドメインは 1 つです。

テーブルバケットが存在することを確認します。

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 でフィルターする — 指定しない場合はすべての履歴が返されます（重複が発生し、処理も遅くなります）
• アカウントとリージョンごとに1つのドメイン — ドメインを切り替えるには、先に設定を削除してください
• 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 コンソール > Table buckets > Enable integration
結果に重複行がある	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 テーブルに対する SELECT + DESCRIBE のみを付与してください。aws-sagemaker-catalog バケット全体へのアクセス許可は避けてください。

監査証跡：DataZone（PutDataExportConfiguration、GetDataExportConfiguration）、Athena（StartQueryExecution、GetQueryResults）、および S3 Tables API の呼び出しについて CloudTrail ログを有効にし、誰がカタログのメタデータをクエリしているか追跡してください。

認証情報の管理：クエリには、一時的な認証情報を使用する IAM ロールを利用してください。カタログのメタデータにアクセスするユーザーに、長期間有効なアクセスキーを使用することは避けてください。アクセスが不要になった場合は、プリンシパルの権限を縮小するか、ローテーションしてください。

追加リソース

• アセットのメタデータのエクスポート
• アセットテーブルのスキーマ
• S3 Tables と分析サービスの統合
• Lake Formation のアクセス許可