databricks

Databricks 专家工程师技能

本技能提供 Databricks 开发的综合指南。

1. Databricks CLI 用法

1.1. 关于 warehouse_id

• 查找并选择一个无服务器 SQL 仓库作为 warehouse_id
• 注意：databricks CLI 不会自动从配置文件中读取 warehouse_id，因此每次都要在 JSON 中明确指定

1.2. 身份验证

• 当 profile 中的 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：实际数据（二维数组）
   • 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. 对象模型

三级命名空间：catalog.schema.table

1. Catalog 层：数据隔离单元（按部门等划分）
2. Schema 层：包含表、视图和卷的逻辑分组
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 格式，由系统进行完整生命周期管理）
• 可以在不同工作区之间隔离 Catalog
• 建议为每个 Catalog 设置独立的托管存储位置

4. 数据工程

4.1. Lakeflow 解决方案

统一数据摄取、转换和编排。

• Lakeflow Connect：简化数据摄取
• Lakeflow Spark Declarative Pipelines (SDP)：声明式管道框架
• Lakeflow Jobs：工作流自动化

4.2. Delta Lake

• Parquet 数据文件，配合基于文件的事务日志
• ACID 事务
• 时间旅行功能
• 优化：液态集群、数据跳过、 文件布局优化、vacuum

4.3. Lakeflow Jobs

任务类型：

• Notebook 任务
• Pipeline 任务
• Python 脚本任务

触发器：

• 基于时间（例如，每天凌晨 2 点）
• 基于事件（有新数据到达时）

限制：

• 工作区：最多 2000 个并发任务执行
• 已保存的作业：最多 12000 个
• 每个作业的任务数：最多 1000 个

5. 机器学习基础设施

5.1. MLflow

• 用于实验跟踪和模型管理的核心工具
• 为 GenAI 提供专用功能

5.2. 特征存储

• 特征管理系统
• 自动化数据管道和特征发现

5.3. 模型服务

• 将自定义模型和大模型部署为 REST 端点
• 自动扩缩容和 GPU 支持

6. 安全性

6.1. 身份验证和访问控制

• SSO 配置
• 多因素身份验证
• 访问控制列表

6.2. 网络安全

• 私有连接
• 无服务器出站流量控制
• 防火墙设置
• VPC 管理

6.3. 数据加密

• 静态数据和传输中数据加密
• 客户管理的密钥
• 集群间通信加密
• 自动凭据遮蔽

7. SQL 仓库

7.1. 无服务器 SQL 仓库的优势

• 即时且弹性的计算能力
• 自动扩缩容
• 最少的管理工作（Databricks 负责处理容量）
• 较低的总拥有成本

8. 架构发现与验证

8.1. 查询前验证规则

• 必须：对不熟悉的表执行 SELECT 前，先运行 DESCRIBE
• 必须：编写查询前，确认列名及其大小写准确无误

-- 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. 架构发现命令

-- 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. 常见问题

问题	原因	预防措施
列名大小写	Databricks 保留大小写	查询前使用 DESCRIBE
数据类型不匹配	隐式转换失败	显式检查列类型
NULL 处理	聚合中出现意外的 NULL	使用 COALESCE 或筛除 NULL
时间戳精度	TIMESTAMP 与 TIMESTAMP_NTZ	比较前验证类型

8.4. 知识积累

遇到与架构相关的问题时，请使用以下内容更新此技能：

• 通用模式（大小写敏感性、类型强制转换规则）
• Unity Catalog 中常见的列命名约定
• Databricks 特有的 SQL 行为

注意：不要包含项目专用的表名或业务逻辑。 条目应能适用于不同环境。

9. VARIANT 类型和 JSON 操作

9.1. VARIANT 类型（Runtime 15.3+）

优势：

• 比 JSON 字符串快 10–30 倍
• 无需手动更新即可演进架构
• 无需预定义架构

基本用法：

-- 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 访问模式

冒号表示法（推荐）：

-- 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() 函数：

-- 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() 函数：

-- 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;

重要说明：

• JSON 中不保证对象字段的顺序
• 保证数组顺序
• 冒号表示法支持类型转换：json_data:age::INT
• 通配符 [*] 仅适用于冒号表示法（不适用于 get_json_object）

10. 仪表板 API（Lakeview）

10.1. 重要变更（2026 年）

• 旧版仪表板 API：已弃用（2026-01-12 禁用访问）
• 迁移截止日期：2026-03-02
• 新 API：Lakeview API（/api/2.0/lakeview/dashboards）

10.2. 仪表板可视化限制

AI/BI 仪表板（Lakeview）：

• ❌ 不支持自定义 HTML/JavaScript
• ❌ 不支持客户端 JSON 解析
• ✅ 提供 20 多种预定义可视化类型
• ✅ 支持用于交互的查询参数

**建议：**在可视化之前于 SQL 中解析 JSON（服务端）

11. dbt 集成模式

11.1. 使用 Jinja 自动演进架构

动态 JSON 展开宏：

-- 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 模型：

-- 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') }}

优势：

• 在 dbt run 时自动检测新的 JSON 字段
• 无需手动更新模型
• 适用于 VARIANT 或 JSON 字符串列

11.2. 推荐架构

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

• Bronze：以 VARIANT 类型存储原始 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/