databricks

Databricks エキスパートエンジニアスキル

このスキルでは、Databricks 開発に関する包括的なガイドを提供します。

1. Databricks CLI の使用方法

1.1. warehouse_id について

• warehouse_id として、Serverless SQL Warehouse を 1 つ見つけて選択します
• 注意：databricks CLI は設定ファイルから warehouse_id を自動的に読み込まないため、毎回 JSON に明示的に含めてください

1.2. 認証

• プロファイルで auth_type=databricks-cli が設定されている場合は、まず U2M 認証を実行します

  databricks auth login --host https://xxx.cloud.databricks.com --profile PROFILE_NAME
  

• 認証状態を確認します

  databricks auth profiles
  

1.3. 基本的な使い方

Statements API（クエリの実行）

# Execute query
databricks api post /api/2.0/sql/statements --profile "DEFAULT" --json '{
  "warehouse_id": "xxxxxxxxxx",
  "catalog": "catalog_name",
  "schema": "schema_name",
  "statement": "select * from table_name limit 10"
}'

# Get results (statement_id is returned from execution)
databricks api get /api/2.0/sql/statements/{statement_id} --profile "DEFAULT"

Queries API（クエリオブジェクトの管理）

# Create query object (for dashboards, saved queries)
# IMPORTANT: Use warehouse_id, query_text, display_name (NOT data_source_id, query, name)
databricks api post /api/2.0/sql/queries --profile "DEFAULT" --json '{
  "warehouse_id": "xxxxxxxxxx",
  "display_name": "My Query",
  "query_text": "SELECT * FROM table_name LIMIT 10",
  "description": "Optional description"
}'

# List queries
databricks api get /api/2.0/sql/queries --profile "DEFAULT"

# Get query by ID
databricks api get /api/2.0/sql/queries/{query_id} --profile "DEFAULT"

よくある間違い：

• ❌ data_source_id → ✅ warehouse_id
• ❌ query → ✅ query_text
• ❌ name → ✅ display_name

1.4. コマンドのヒント

1. クエリの実行フロー

   • post でクエリを実行すると、statement_id が返されます
   • get で結果を取得します（state が SUCCEEDED になるまで待機します）
   • 長時間かかるクエリでは、sleep を追加して再試行します

2. エラー処理

   • state: CLOSED：結果の取得に時間がかかりすぎました。早めに取得してください
   • state: FAILED：SQL エラーです。error_message を確認してください
   • state: RUNNING：実行中です。待機して get を再試行してください
   • タイムアウト：大規模なデータでは、確認に limit を使用します

3. 結果の読み取り

   • data_array：実際のデータ（2 次元配列）
   • schema.columns：列名と型情報
   • total_row_count：合計件数（limit を指定した場合も表示されます）
   • state：クエリの実行状態

4. パラメーター化クエリ

databricks api post /api/2.0/sql/statements --profile "DEFAULT" --json '{
  "warehouse_id": "xxxxxxxxxx",
  "statement": "select * from table where date >= :start_date",
  "parameters": [{"name": "start_date", "value": "2025-01-01", "type": "DATE"}]
}'

2. Well-Architected Lakehouse Framework

7 つの柱で構成されています。

2.1. データと AI のガバナンス

データと AI 資産を安全に管理するためのポリシーとプラクティスです。 統合ガバナンスソリューションにより、データのコピーを最小限に抑えます。

2.2. 相互運用性と使いやすさ

一貫したユーザーエクスペリエンスと、外部システムとのシームレスな統合を実現します。

2.3. オペレーショナルエクセレンス

本番環境での継続的な運用を支えるプロセスです。

2.4. セキュリティ、プライバシー、コンプライアンス

脅威に対する保護策を実装します。

2.5. 信頼性

災害復旧機能を確保します。

2.6. パフォーマンス効率

ワークロードの変化に適応します。

2.7. コスト最適化

価値の提供を最大化するためにコストを管理します。

3. Unity Catalog

3.1. 基本概念

• 「一度定義すれば、あらゆる場所で保護する」アプローチ
• 複数のワークスペースにまたがる統合アクセス制御ポリシー
• ANSI SQL に準拠した権限管理

3.2. オブジェクトモデル

3 階層の名前空間：catalog.schema.table

1. カタログ層：データの分離単位（部門別など）
2. スキーマ層：テーブル、ビュー、ボリュームを含む論理グループ
3. オブジェクト層：テーブル、ビュー、ボリューム、関数、モデル

3.3. 権限管理

• ユーザーはデフォルトでデータにアクセスできません
• 明示的な権限付与が必要です
• 権限は親から子へ継承されます（catalog -> schema -> table）

-- Check permissions
SHOW GRANTS ON SCHEMA main.default;

-- Grant permissions
GRANT CREATE TABLE ON SCHEMA main.default TO `finance-team`;

-- Revoke permissions
REVOKE CREATE TABLE ON SCHEMA main.default FROM `finance-team`;

3.4. ベストプラクティス

• マネージドテーブル／ボリュームを推奨します （Delta Lake 形式、ライフサイクル全体の管理）
• ワークスペース間でカタログを分離できます
• カタログごとに独立したマネージドストレージの場所を設定することを推奨します

4. データエンジニアリング

4.1. Lakeflow ソリューション

データの取り込み、変換、オーケストレーションを統合します。

• Lakeflow Connect：データの取り込みを簡素化します
• Lakeflow Spark Declarative Pipelines (SDP)：宣言型パイプラインフレームワーク
• Lakeflow Jobs：ワークフローの自動化

4.2. Delta Lake

• ファイルベースのトランザクションログを備えた Parquet データファイル
• ACID トランザクション
• タイムトラベル機能
• 最適化：リキッドクラスタリング、データスキッピング、 ファイルレイアウトの最適化、vacuum

4.3. Lakeflow Jobs

タスクの種類：

• ノートブックタスク
• パイプラインタスク
• Python スクリプトタスク

トリガー：

• 時刻ベース（例：毎日午前 2 時）
• イベントベース（新しいデータの到着時）

制限：

• ワークスペース：同時に実行できるタスクは最大 2000 件
• 保存済みジョブ：最大 12000 件
• ジョブあたりのタスク数：最大 1000 件

5. 機械学習インフラストラクチャ

5.1. MLflow

• 実験の追跡とモデル管理の中核となるツール
• GenAI 専用の機能

5.2. Feature Store

• Feature management system
• Automatic data pipelines and feature discovery

5.3. Model Serving

• Deploy custom models and LLMs as REST endpoints
• Auto-scaling and GPU support

6. Security

6.1. Authentication and Access Control

• SSO configuration
• Multi-factor authentication
• Access control lists

6.2. Network Security

• Private connectivity
• Serverless egress control
• Firewall settings
• VPC management

6.3. Data Encryption

• Encryption at rest and in transit
• Customer-managed keys
• Inter-cluster communication encryption
• Automatic credential masking

7. SQL Warehouse

7.1. Serverless SQL Warehouse Benefits

• Instant and elastic compute
• Auto-scaling
• Minimal management (Databricks handles capacity)
• Low total cost of ownership

8. Schema Discovery and Validation

8.1. Pre-Query Validation Rule

• YOU MUST: Run DESCRIBE before executing SELECT on unfamiliar tables
• YOU MUST: Verify exact column names and case before writing queries

-- Check table columns first
DESCRIBE TABLE catalog.schema.table_name;

-- Then write your query using verified column names
SELECT column_name FROM catalog.schema.table_name;

8.2. Schema Discovery Commands

-- Basic column info
DESCRIBE TABLE catalog.schema.table_name;

-- Extended info (types, nullability, comments)
DESCRIBE EXTENDED catalog.schema.table_name;

-- List tables in schema
SHOW TABLES IN catalog.schema;

-- Table properties and metadata
DESCRIBE DETAIL catalog.schema.table_name;

8.3. Common Gotchas

Issue	Cause	Prevention
Column name case	Databricks preserves case	Use DESCRIBE before query
Data type mismatch	Implicit conversion fails	Check column types explicitly
NULL handling	Unexpected NULL in aggregation	Use COALESCE or filter NULLs
Timestamp precision	TIMESTAMP vs TIMESTAMP_NTZ	Verify type before comparison

8.4. Knowledge Accumulation

When encountering schema-related issues, update this skill with:

• Universal patterns (case sensitivity, type coercion rules)
• Common column naming conventions in Unity Catalog
• Databricks-specific SQL behaviors

NOTE: Do not include project-specific table names or business logic. Keep entries generalizable across environments.

9. VARIANT Type and JSON Operations

9.1. VARIANT Type (Runtime 15.3+)

Benefits:

• 10-30x faster than JSON strings
• Schema evolution without manual updates
• No predefined schema required

Basic Usage:

-- Create table with VARIANT
CREATE TABLE events (
  id BIGINT,
  data VARIANT
);

-- Insert JSON data
INSERT INTO events VALUES
  (1, parse_json('{"name":"太郎","age":25}')),
  (2, parse_json('{"name":"花子","age":30,"new_field":"value"}'));

-- Query with colon notation
SELECT
  data:name::STRING AS name,
  data:age::INT AS age,
  data:new_field::STRING AS new_field  -- Auto-recognized
FROM events;

9.2. JSON Access Patterns

Colon Notation (Recommended):

-- Object fields
json_data:name
json_data:metadata.status

-- Array elements
json_data:tags[0]
json_data:tags[1]

-- Wildcards (all elements)
json_data:tags[*]  -- Returns array

-- Nested arrays
json_data:basket[*][0]  -- First element of each sub-array
json_data:basket[0][*]  -- All elements of first array

get_json_object() Function:

-- Basic usage
get_json_object(json_data, '$.name')
get_json_object(json_data, '$.tags[0]')
get_json_object(json_data, '$.metadata.status')

-- Limitation: Path must be STRING literal (no variables)

json_object_keys() Function:

-- Get all keys as array
SELECT json_object_keys(json_data) FROM table_name;
-- Result: ["name", "age", "tags", "metadata"]

-- Access by index (order not guaranteed)
SELECT
  json_object_keys(json_data)[0] AS first_key,
  get_json_object(json_data, '$.' || json_object_keys(json_data)[0]) AS first_value
FROM table_name;

Important Notes:

• Object field order is NOT guaranteed in JSON
• Array order IS guaranteed
• Colon notation supports type casting: json_data:age::INT
• Wildcards [*] only work with colon notation (not get_json_object)

10. Dashboard API (Lakeview)

10.1. Important Changes (2026)

• Legacy Dashboard API: Deprecated (access disabled 2026-01-12)
• Migration deadline: 2026-03-02
• New API: Lakeview API (/api/2.0/lakeview/dashboards)

10.2. Dashboard Visualization Limitations

AI/BI Dashboard (Lakeview):

• ❌ No custom HTML/JavaScript
• ❌ No client-side JSON parsing
• ✅ 20+ predefined visualization types
• ✅ Query parameters for interactivity

Recommendation: Parse JSON in SQL (server-side) before visualization

11. dbt Integration Patterns

11.1. Auto-Schema Evolution with Jinja

Macro for Dynamic JSON Expansion:

-- macros/get_json_keys.sql
{% macro get_json_keys(table_ref, json_column) %}
  {% set query %}
    SELECT DISTINCT key
    FROM {{ table_ref }},
    LATERAL variant_explode({{ json_column }})
    ORDER BY key
  {% endset %}

  {% if execute %}
    {% set results = run_query(query) %}
    {% set keys = results.columns[0].values() %}
    {{ return(keys) }}
  {% else %}
    {{ return([]) }}
  {% endif %}
{% endmacro %}

dbt Model:

-- models/staging/stg_events.sql
{% set json_keys = get_json_keys(source('bronze', 'events'), 'json_data') %}

SELECT
  id,
  {% for key in json_keys %}
  json_data:{{ key }}::STRING AS {{ key | lower }}
  {%- if not loop.last %},{% endif %}
  {% endfor %}
FROM {{ source('bronze', 'events') }}

Benefits:

• New JSON fields auto-detected on dbt run
• No manual model updates required
• Works with VARIANT or JSON string columns

11.2. Recommended Architecture

Source → Bronze (VARIANT) → Silver (dbt expand) → Gold (business logic)

• Bronze: VARIANT型でRaw JSON保存
• Silver: dbt Jinjaマクロで必要なフィールドを展開
• Gold: ビジネスロジック、アグリゲーション

12. Reference Links

• Official docs: https://docs.databricks.com/
• Unity Catalog: https://docs.databricks.com/en/data-governance/unity-catalog/
• Lakeflow Jobs: https://docs.databricks.com/en/jobs/
• MLflow: https://docs.databricks.com/en/mlflow/
• Delta Lake: https://docs.databricks.com/en/delta/
• Security: https://docs.databricks.com/en/security/
• VARIANT Type: https://docs.databricks.com/aws/en/semi-structured/variant.html
• JSON Operations: https://docs.databricks.com/aws/en/semi-structured/json.html
• Colon Notation: https://docs.databricks.com/aws/en/sql/language-manual/functions/colonsign.html
• Queries API: https://docs.databricks.com/api/workspace/queries
• Lakeview Dashboards: https://docs.databricks.com/aws/en/dashboards/
• dbt Documentation: https://docs.getdbt.com/