byted-bytehouse-data-asset-analyzer

Files (5)

• .gitignore
• LICENSE
• SKILL.md
• data_asset_analyzer.py · scripts/
• export_config.sh · scripts/

SKILL.md (first lines)

# ByteHouse 数据资产和血缘分析 Skill

## 描述

直接通过 `clickhouse-connect` 连接 ByteHouse（HTTPS 8123），查询 `system.tables` / `system.columns` 扫描目标数据库的所有表与字段，生成三份产物：

- **Schema 报告** — 数据库完整表结构（引擎、字段、DDL 原文等）。
- **数据资产目录** — 表总数、列总数、引擎分布、自动标签。
- **血缘分析报告** — Distributed ↔ Local 关系、跨表同名列的相似性。

**当以下情况时使用此 Skill：**

1. 需要获取 ByteHouse 数据库的表结构和字段信息。
2. 需要生成数据资产目录、盘点数据资产。
3. 需要分析表之间的血缘关系（例如 Distributed → Local）。
4. 用户提到 "数据资产"、"血缘分析"、"表结构"、"字段分析" 等关键词。

## 前置条件

- Python 3.8+
- `clickhouse-connect`（安装方式：`pip install clickhouse-connect`）
- `jq`（`export_config.sh` 依赖，解析 JSON 配置。安装方式：`brew install jq` 或 `sudo apt install jq`）
- 有效的 ByteHouse 连接信息（保存于 `~/.bytehouse_config.json`）

## 📁 文件说明

- **SKILL.md** — 本文件，技能主文档。
- **scripts/data_asset_analyzer.py** — 数据资产和血缘分析主程序。
- **scripts/export_config.sh** — 从 `~/.bytehouse_config.json` 加载配置到环境变量（依赖 `jq`）。

## 配置说明

配置保存在 `~/.bytehouse_config.json`。如果文件存在且非空，直接使用；若不存在，向用户索要连接信息（可以把 [ByteHouse 连接信息获取指引](https://www.volcengine.com/docs/6517/1121919?lang=zh) 发给用户），拿到后写入 JSON 文件，避免重复询问。

```json
{
  "BYTEHOUSE_HOST": "<ByteHouse-host>",
  "BYTEHOUSE_PORT": "8123",
  "BYTEHOUSE_USER": "bytehouse",
  "BYTEHOUSE_PASSWORD": "<ByteHouse-password>"
}
```

配置项说明：

| 配置项 | 是否必填 | 默认值 | 说明 |
|--------|----------|--------|------|
| `BYTEHOUSE_HOST` | 是 | — | ByteHouse 网关域名 |
| `BYTEHOUSE_PORT` | 否 | `8123` | HTTP(S) 端口 |
| `BYTEHOUSE_USER` | 否 | `bytehouse` | 用户名 |
| `BYTEHOUSE_PASSWORD` | 是 | — | 密码 / API Key |

加载配置：

```bash
source scripts/export_config.sh
```

## 🧭 智能体使用指引

1. **确认配置**：`source scripts/export_config.sh`，确认 `BYTEHOUSE_HOST` 等环境变量已就绪。
2. **确认要分析的数据库**：若用户未指定，主动询问（例如 `default`、`tpcds`）。
3. **执行分析**：`python3 scripts/data_asset_analyzer.py <database>`，脚本会通过 `clickhouse-connect` 查询 `system.tables` / `system.columns` 拉取元数据。
4. **展示结果**：根据 `scripts/output/` 目录里的 3 份 JSON 结果，给出总表数、总列数、引擎分布、Top 血缘关系等要点。
5. **禁止臆造**：所有资产/血缘信息一律来自脚本产物，不要凭上下文猜测。

## 🎯 功能特性

### 1. 完整 Schema 获取

- 获取指定数据库的所有表。
- 获取每张表的所有字段。
- 提取表引擎、注释等元数据。
- 保留 CREATE TABLE 语句原文。

### 2. 数据资产目录生成

- 表统计（总表数、总列数）。
- 引擎分布统计。
- 自动标签生成。
- 表资产详情（含前 10 个字段预览）。

### 3. 血缘分析

- 表关系识别（Distributed ↔ Local，基于命名模式）。
- 列相似性分析（同名列跨表出现）。

## 🚀 快速开始

```bash
# 1. 加载配置（复用 ~/.bytehouse_config.json）
source scripts/export_config.sh

# 2. 执行分析（指定库名）
python3 scripts/data_asset_analyzer.py default
python3 scripts/data_asset_analyzer.py tpcds
```

**分析内容包括：**

- 数据库完整 schema（所有表和字段）。
- 数据资产目录（表统计、引擎分布、自动标签）。
- 血缘分析（表关系、列相似性）。

**输出文件（保存在与脚本同级的 `scripts/output/` 目录）：**

1. `schema_{database}_{timestamp}.json` — 完整的数据库 schema。
2. `catalog_{database}_{timestamp}.json` — 数据资产目录。
3. `lineage_{database}_{timestamp}.json` — 血缘分析报告。

## 💻 程序化调用

`scripts/data_asset_analyzer.py` 暴露的是一个**同步函数** `analyze_database(database)`（**不是** async，也**不是**类）。它返回内存中的分析结果字典，**本身不落盘**；如需生成 JSON 文件，请直接运行脚本 `main()`（即命令行方式）。

要在其他 Python 代码里调用：

```python
import os
import sys

From bytedance/agentkit-samples, Apache-2.0.

More from bytedance/agentkit-samples