databricks-unity-catalog

Unity Catalog

Unity Catalog のガバナンス（アクセス制御、権限モデル、外部ロケーション、セキュリティ保護可能なオブジェクトの DDL、きめ細かなアクセス制御）に加え、システムテーブルとボリュームのファイル操作に関するガイダンスです。

databricks CLI コマンドを実行する前に、CLI とサブコマンドが存在することを確認してください。 databricks --version を実行してください。このスキルは統合 CLI（≥ v1.0.0）を前提としています。ここに示すいくつかのサブコマンド（experimental aitools、system-schemas、external-lineage、grants）は、バージョンやワークスペースでの利用可否によって異なります。サブコマンドが見つからない場合やフラグが拒否された場合は、推測せずに SQL 形式または Python SDK を使用してください。該当する場合は、各リファレンスに必要な最低バージョンが記載されています。

このスキルを使用する場面

次の場合にこのスキルを使用します。

ガバナンスとアクセス制御（ここから始めます）：

• アクセスの許可または取り消し — GRANT／REVOKE、UC 権限モデル、所有権（ALTER … OWNER TO）、SHOW GRANTS、「このテーブルを読み取り／書き込みできるのは誰か？」
• 行レベルおよび列レベルのセキュリティ — 行フィルター、列マスク、current_user()／is_account_group_member() を使用する動的ビュー
• 外部ロケーションとストレージ認証情報 — CREATE STORAGE CREDENTIAL、CREATE EXTERNAL LOCATION、基盤となる外部テーブル／ボリューム
• セキュリティ保護可能なオブジェクトの DDL とメタデータ — カタログ、スキーマ、マネージドテーブルと外部テーブル、ビューの作成／変更、コメント、タグ、テーブルプロパティ、所有権

オブザーバビリティとファイル：

• ボリュームの操作（/Volumes/ 内のファイルのアップロード、ダウンロード、一覧表示）
• リネージのクエリ（テーブルの依存関係、列レベルのリネージ）
• 監査ログの分析（誰が何にアクセスしたか、権限の変更）
• 請求と使用量の監視（DBU 消費量、コスト分析）
• コンピュートリソースの追跡（クラスター使用量、ウェアハウスメトリクス）
• ジョブの実行状況の確認（実行履歴、成功率、失敗）
• クエリパフォーマンスの分析（低速クエリ、ウェアハウスの利用率）
• データ品質のプロファイリング（データプロファイリング、ドリフト検出、メトリクステーブル）

リファレンスファイル

トピック	ファイル	説明
アクセス制御	references/1-access-control.md	権限モデル、セキュリティ保護可能なオブジェクトの階層、GRANT/REVOKE、所有権、継承、SHOW GRANTS
外部ロケーション	references/2-external-locations.md	ストレージ認証情報（AWS/Azure/GCP）、外部ロケーション、検証
セキュリティ保護可能なオブジェクトの DDL	references/3-securables-ddl.md	カタログ／スキーマ／テーブル／ビューの CREATE/ALTER/DROP、コメント、タグ、所有権
きめ細かなアクセス制御	references/4-fine-grained-access.md	行フィルター、列マスク、動的ビュー
システムテーブル	references/5-system-tables.md	リネージ、監査、請求、コンピュート、ジョブ、クエリ履歴
ボリューム	references/6-volumes.md	ボリュームのファイル操作、権限、ベストプラクティス
データプロファイリング	references/7-data-profiling.md	データプロファイリング、ドリフト検出、プロファイルメトリクス

クイックスタート

Unity Catalog オブジェクトの作成（CLI）

create コマンドでは --json を使用してください。 位置引数の順序はコマンドごとに異なり、 CLI のバージョン間で変更されているため、このスキル全体で示している --json が、順序に依存せず バージョン間で安定した方法です。

# Create a catalog
databricks catalogs create --json '{"name": "my_catalog"}'

# Create a schema
databricks schemas create --json '{"name": "my_schema", "catalog_name": "my_catalog"}'

# Create a managed volume
databricks volumes create --json '{
  "catalog_name": "my_catalog",
  "schema_name": "my_schema",
  "name": "my_volume",
  "volume_type": "MANAGED"
}'

# List catalogs, schemas, volumes (read commands take simple positional args)
databricks catalogs list
databricks schemas list my_catalog
databricks volumes list my_catalog.my_schema

位置引数による create も使用できますが、コマンド間で順序が統一されていません。コマンドごとの順序は次のとおりです（--json を推奨する理由でもあります）。

コマンド	位置引数による create の順序
databricks catalogs create	NAME
databricks schemas create	NAME CATALOG_NAME
databricks volumes create	CATALOG_NAME SCHEMA_NAME NAME VOLUME_TYPE

CLI の仕様はバージョンによって異なります。 インストール環境で databricks のサブコマンドまたは位置引数のシグネチャが使えない場合は、フラグを推測せず、--json、SQL 形式、または Python SDK を使用してください。

ボリュームのファイル操作（CLI）

databricks fs では、UC ボリュームのパスでも dbfs: スキームのプレフィックスが必要です。これがないと、CLI はパスをローカルファイルシステムとして扱い、no such directory エラーになります。

# List files in a volume
databricks fs ls dbfs:/Volumes/catalog/schema/volume/path/

# Upload a directory's contents to a volume (-r copies contents, not the directory itself)
databricks fs cp -r --overwrite /tmp/data dbfs:/Volumes/catalog/schema/volume/dest

# Download a file from a volume
databricks fs cp dbfs:/Volumes/catalog/schema/volume/file.csv /tmp/file.csv

# Create a directory in a volume
databricks fs mkdirs dbfs:/Volumes/catalog/schema/volume/new_folder

アクセス権の付与と取り消し

GRANT／REVOKE は、ガバナンスの中核となる操作です。権限モデルの詳細は、references/1-access-control.md を参照してください。

-- Grant read access on a schema to a group
GRANT USE CATALOG ON CATALOG analytics TO `data_readers`;
GRANT USE SCHEMA ON SCHEMA analytics.gold TO `data_readers`;
GRANT SELECT ON SCHEMA analytics.gold TO `data_readers`;

-- Who can access this table?
SHOW GRANTS ON TABLE analytics.gold.customers;

-- Revoke
REVOKE SELECT ON SCHEMA analytics.gold FROM `data_readers`;

システムテーブルへのアクセスを有効にする

-- Grant access to system tables
GRANT USE CATALOG ON CATALOG system TO `data_engineers`;
GRANT USE SCHEMA ON SCHEMA system.access TO `data_engineers`;
GRANT SELECT ON SCHEMA system.access TO `data_engineers`;

よく使うクエリ

-- Table lineage: What tables feed into this table?
SELECT source_table_full_name, source_column_name
FROM system.access.table_lineage
WHERE target_table_full_name = 'catalog.schema.table'
  AND event_date >= current_date() - 7;

-- Audit: Recent permission changes
SELECT event_time, user_identity.email, action_name, request_params
FROM system.access.audit
WHERE action_name LIKE '%GRANT%' OR action_name LIKE '%REVOKE%'
ORDER BY event_time DESC
LIMIT 100;

-- Billing: DBU usage by workspace
SELECT workspace_id, sku_name, SUM(usage_quantity) AS total_dbus
FROM system.billing.usage
WHERE usage_date >= current_date() - 30
GROUP BY workspace_id, sku_name;

CLI から SQL を実行する

databricks experimental aitools tools query は実験的なコマンドです。 experimental 名前空間は CLI のバージョン間で安定している保証がなく、インストール環境で利用できない場合があります。システムテーブルの SQL は、SQL ウェアハウス（SQL エディター、スケジュール済みクエリ）、Python SDK（w.statement_execution.execute_statement）、またはノートブックで実行することをおすすめします。実験的な CLI は、手早いアドホックチェックに限って使用してください。

これらの例で使用する ID の取得方法。 WAREHOUSE_ID は databricks warehouses list を実行して取得します（または、UI の SQL ウェアハウスの 接続の詳細 からコピーします）。METASTORE_ID（references/5-system-tables.md で使用）は、SDK の w.metastores.current().metastore_id から取得するか、Catalog UI → メタストアの詳細から確認できます。

実験的な CLI 形式（利便性のためのみ）：

databricks experimental aitools tools query --warehouse WAREHOUSE_ID "
  SELECT source_table_full_name, target_table_full_name
  FROM system.access.table_lineage
  WHERE event_date >= current_date() - 7
"

安定した SDK の代替手段（どの CLI バージョンでも動作）：

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
resp = w.statement_execution.execute_statement(
    warehouse_id="WAREHOUSE_ID",
    statement="""
        SELECT source_table_full_name, target_table_full_name
        FROM system.access.table_lineage
        WHERE event_date >= current_date() - 7
        LIMIT 100
    """,
)
for row in resp.result.data_array or []:
    print(row)

CLI の仕様はバージョンによって異なります。 databricks のサブコマンド（experimental のツール、system-schemas、external-lineage など）が使えない場合は、フラグを推測せず、上記の SQL ウェアハウスまたは Python SDK を使用してください。

ベストプラクティス

1. 必要最小限のアクセス権を付与する - 最小権限の原則に従い、機能する範囲で最も限定されたセキュリティ保護可能オブジェクトに権限を付与します
2. 日付で絞り込む - システムテーブルは大きくなる場合があるため、必ず日付フィルターを使用します
3. 適切な保持期間を設定する - ワークスペースの保持設定を確認します
4. レポートをスケジュールする - 定期的な監視用にスケジュール済みクエリを作成します
5. 実験的な CLI より SQL／SDK を優先する - 手早いチェック以外の用途ではこちらを使用します

関連スキル

このスキルでは、Unity Catalog のガバナンス、すなわちアクセス制御、権限モデル、外部ロケーション／ストレージ認証情報、セキュラブルの DDL、きめ細かなアクセス制御、システムテーブル、ボリュームを扱います。隣接する領域については、代わりに以下の関連スキルを使用してください。

• databricks-core（宣言上の親）— 認証、プロファイル選択、汎用 CLI、カタログ／テーブルの探索
• databricks-metric-views — メトリックビューの定義／DDL（WITH METRICS LANGUAGE YAML）
• databricks-iceberg — Managed Iceberg、External Iceberg Reads（旧 Uniform）、および外部エンジン向けのIceberg REST Catalog（IRC）認証情報の払い出し — UC ストレージ認証情報とは異なります（references/2-external-locations.md を参照）
• databricks-ml-training — UC モデルの登録と @prod／@challenger エイリアス
• databricks-vector-search — Vector Search インデックス
• databricks-pipelines、databricks-jobs、databricks-lakeflow-connect — パイプライン／ジョブ／マネージド取り込みによるテーブルの生成
• databricks-lakebase — Lakebase／同期テーブル（OLTP）
• databricks-ai-functions — ai_mask／ai_classify などの AI 関数（AI の変換であり、アクセス制御ではありません。references/4-fine-grained-access.md を参照）
• databricks-aibi-dashboards — UC データ上の AI/BI ダッシュボード
• databricks-synthetic-data-gen — UC ボリュームに保存するデータの生成

ロードマップ（未対応 — 後のバージョンに延期）

以下のガバナンス領域は、意図的にv0.3.0 の対象外としており、後のバージョンでの対応を予定しています。

• Delta Sharing／Marketplace／Clean Rooms
• Lakehouse Federation（接続と外部カタログ）
• ABAC／ポリシーとしてのガバナンスタグ

リソース

• Unity Catalog の権限とセキュラブルオブジェクト
• Unity Catalog システムテーブル
• 監査ログリファレンス
• 外部ロケーションとストレージ認証情報の管理