SQL Explorer

核心功能：1.选中 SQL 执行到 ByteHouse / MaxCompute，交互式看结果、表结构、画图、导出。2.并用 Analysis Canvas 把查询与结果组织成可视化分析图谱(数据血缘图/数据分析/数仓建模可视化）。3.零 Python 依赖，多连接统一管理，凭据走系统密钥库

Core：1.Run selected SQL on ByteHouse / MaxCompute. Inspect results & schemas interactively, create charts, export outputs, 2. and assemble visual analysis graphs in Analysis Canvas --（lineage diagram/visualize data‑warehouse modeling）. 3.Zero‑Python, unified multi‑connection management, system‑keychain secured credentials.

• 零 Python 依赖：MaxCompute 走纯 Node 自实现（REST + 签名），不用装 pyodps、不用配 Python 环境。
• 多数据源一个面板：ByteHouse（ClickHouse 兼容）、MaxCompute（阿里云）统一连接管理，切换即用。
• 💡 不只是查询窗口：内置表结构浏览、选区复制、筛选&排序、json 结构化、交互可视化图、CSV / Python 导出、查询历史与结果归档。
• 💡 Analysis Canvas：把查询历史与保存结果拖到画布上，用连线标注「派生 / 对比 / 校验」等关系，构建你的分析图谱/血缘关系图，分组圈定主题域，左侧 Navigator 索引结构，用 Note 记录分析思考 ➔ 从「查询 + 结果查看工具」进一步变成「数据分析过程/数仓建模的可视化工作空间」 ➔ 画布是关系视图，Detail Panel 是内容视图
• Q / R / N 三层语义：Q 查询（查了什么/数仓建设代码）→ R 证据（得到了什么/sql结果）→ N 思考（意味着什么/下一步做什么/假设/说明/备注/问题）；Group 是主题/数仓域，Edge 是关系/血缘

• Zero‑Python Dependency: Pure Node.js implementation for MaxCompute (REST + signature auth). No pyodps or Python setup.
• Unified Data‑source Panel: Manage ByteHouse (ClickHouse‑compatible) and Alibaba Cloud MaxCompute connections; switch instantly.
• 💡 Full‑featured Query Workspace: Table‑schema browsing, selection copy, filter‑sort, JSON formatting, interactive charts, CSV/Python export, query‑history & result archive.
• 💡 Analysis Canvas: Drag queries & saved results, label derivation/comparison/validation links to build analysis graphs/lineage diagram ➔ Transcending a basic query‑and‑result tool to become a visual workspace for data‑analysis and data‑warehouse modeling workflows: the canvas provides the relationship view, and the Detail Panel delivers the content view.
• Three‑layer Q/R/N Semantics: Q ‑ Query (what is being queried / data‑warehouse construction code) → R ‑ Result (what is obtained / SQL execution output) → N ‑ Note (what it implies / next‑step actions / hypotheses / explanations / comments / questions). Group - represents a theme or data‑warehouse domain. Edge - represents relationships or data lineage.

使用路径：写 SQL → 选数据源 → 执行(SELECT) → 交互表看结果 → 点表看结构 → 画图（暂未完善）/ Canvas 图谱→ 导出 CSV / Python。

30 秒上手

写 SQL/打开 .sql 文件
   ↓
选中要跑的 SQL执行（Cmd+Enter / Ctrl+Enter）（可带 -- sql-explorer-connection:xxx 指定连接）
   ↓
Query History
   ↓
Saved Result （filter/sort/hide/导出 CSV/保存结果）
   ↓
Analysis Canvas（右键 Add to Canvas 拖入分析图谱➔ 清晰构建数仓模型）
   ↓
Add Note （记录问题/ 假设/说明/备注）
   ↓
连接 Query / Result / Note
   ↓
按主题/数仓建设分域 Group
   ↓
Navigator 浏览&调整分析结构/数仓建模结构
   ↓
点击节点查看内容（单击打开，双击跳转）
   ↓
继续查询验证/数仓建模
   ↓
Copy Canvas as Image

模块关系

                        SQL Explorer
                             │
        ┌────────────────────┼────────────────────┬──────────────────┐
        ↓                    ↓                    ↓                  ↓
  Connection Manager    Result Explorer      Metadata Explorer   Analysis Canvas
        │                    │                    │                  │
   多连接 / 凭证          交互表 / 图表          表结构浏览        查询结果组织成图谱
        │                    │                    │                  │
  ByteHouse / MaxCompute  CSV / Python           点表看结构       连线标注关系/创建 group
        │                    │                    │                  │
   SecretStorage        查询历史 / 结果归档     复制表名          直线 / 弧线 / 阶梯

为什么值得装

• Canvas= 空间关系表达（可以清晰呈现表之间血缘关系，使数仓构建更清晰） Group
• Navigator= 分组结构导航(可以作为不同数据域的表示“订单域““投放域“)

🌟新建连接：每一项填什么

侧栏「Connections」右上角 ＋，弹出可视化表单。选「数据库类型」后，字段按类型切换。

ByteHouse（ClickHouse 兼容）

MaxCompute（阿里云）

所有 Credential 都走 VS Code SecretStorage（系统密钥库），不写入 settings.json / 工作区 / git。

核心能力

1. 连接管理（左侧栏）

Connections
├─ ▸ bytehouse_prod (ByteHouse)
│    └─ 展开自动加载表 → 点表名复制 / 👁 看结构
├─ ▸ test_dev (MaxCompute)
│
├─ ▸ Query History   → 每次查询的 SQL，可改名 / 点开还原→新标签
└─ ▸ Saved Results   → 保存的结果，可改名 / 点开→表格 + 来源 SQL

• 右键连接：Set Active / Test Connection / Set Default / Edit / Delete
• 视图标题栏：＋新建连接 / 过滤表名 / 刷新

2. 结果表（Result 面板 — Table 页）

• 排序 / 全局搜索 / 按列过滤（符号 + 枚举多选 + 文本）
  • 数值列（含 Nullable(UInt64) 等）默认用「≥」做数值比较，不是字符串匹配
• 隐藏列 / 拖拽列宽 / 数值格式（raw / 2 位小数 / 百分数）
• 分组累计选区：⌘+点击格↔表头↔行号多选，矩形拖拽；一键复制 TSV
• 超长 JSON 单元格 → 右键格式化弹窗
• 列宽上限可调（表格顶部 ⚙ 按钮）

3. 其它两个 Tab

4. Chart（可交互图表）

自己选列出图，不依赖自动推荐。所有选列都在 Table 页右键列名 完成。

4.1 选列规则

各图表类型需要的列：

柱状图 / 折线图（单轴）：X + Y1
柱状图 / 折线图（双轴）：X + Y1 + Y2      ← 左右两个 Y 轴，同 X 点两根柱子并排
饼图              ：X（按此分组） + Y1（数值）
任意图 + 分组     ：再加「分组列」→ 每个分组值一条系列

4.2 操作步骤

1. Table 页右键某列名 → 菜单里选 设为 X 轴 / 设为 Y1 轴（左）/ 设为 Y2 轴（右）/ 设为分组列
   • 当前角色会打 ✓（一列只能承担一个角色，设新角色会自动清掉旧角色）
   • 也可「取消该列角色」
   • 也支持 ⌥(Alt) + 点击列头 快捷设置
   • 列头会显示黄色徽章：X / Y1 / Y2 / G
2. 切到 Chart 页 → 按所选列绘图（设轴时不会自动跳转）
3. 顶部选择每轴的图形（Y1 / Y2 各自独立）：柱状 / 折线 / 平滑曲线
   • 双轴图可做「左柱右线」「双线」「双柱」等任意组合
   • 「平滑曲线」= 折线带平滑拐角（ECharts smooth）
   • 顶部还有「柱状 / 折线」按钮：在全柱 ↔ 全线间一键切换；「饼图」按钮切到饼图模式
4. 堆叠柱状（选了分组列 + 该轴为柱状时可用）：勾选「堆叠」→ 同一 X 的各分组叠成一根柱（不再并排）；Y1 / Y2 各自独立控制
5. 顶部选择聚合方式（Y1 / Y2 各自独立）：SUM 求和 / AVG 平均 / COUNT 计数 / MAX 最大 / MIN 最小
   • 同一 X 值有多行时按此聚合，例如 dt 相同多行 cost：SUM 则相加、AVG 则取平均
   • 未选分组列时，仍按聚合合并为单条线
6. 图例筛选：
   • 单击图例 → 隐藏 / 显示该系列（可多个叠加，只看其中几条）
   • ⌥ / Alt + 单击 → 只看该系列（其余全隐藏）；再 ⌥+单击同一个 → 恢复全部
7. 顶部「清除」按钮重置所有选列

排序：折线 / 柱状的 X 轴会自动按值排序（数字按数值、日期按时间、其余按字符串），保证时间序列正确显示。 hover 十字虚线：鼠标移到图上时显示十字参考线，方便同时看当前点的横纵对应位置。 双轴网格线共用：左右两个 Y 轴取相同刻度数，水平网格线重合（右轴不重复画线），不会出现两侧横线错开的情况。 数据量保护：结果超过 1000 行 时弹确认框，确认后只绘制前 1000 行并在顶部标注「已截断：仅绘制前 1000 / N 行」；取消则不绘制，避免大结果集卡顿。

4.3 配置示例

① 单轴折线：dt 为 X，cost 为 Y1，聚合 SUM
   → 每日消耗趋势

② 双轴对比：dt 为 X，cost 为 Y1（SUM，柱状），pv 为 Y2（SUM，折线）
   → 左轴消耗（柱）、右轴曝光量（线），两个量级不同的指标同图对比
   → 图形可自由搭配：左柱右线 / 左线右柱 / 双线 / 双柱 / 平滑曲线

③ 分组多线：dt 为 X，cost 为 Y1，country 为分组列
   → 每个国家一条折线，对比各国消耗走势

④ 饼图占比：country 为 X（分组），cost 为 Y1（SUM）
   → 各国消耗占比

5. 导出与归档

6. Analysis Canvas（分析画布）

把查询历史与保存结果组织成一张可视化分析地图——画布承载「关系」，分组承载「主题」，Navigator 承载「结构」：

• 侧栏 Query History / Saved Results 上右键 Add to Canvas → 加入画布（每个源只引用 sourceType+sourceId，不复制内容）
• 拖动节点在两点间直接连线（默认关系 related、默认弧线样式）
• 点击连线 → 弹框设置自定义标签文字、切换直线 / 弧线 / 阶梯样式，或删除该线
• 单击节点 → 展开右侧 Detail Panel（再点一次收起）；双击节点 → 打开原查询 / 原结果
• Detail Panel 左侧拖拽手柄可拉宽/收窄；SQL 自动格式化展示
• 按钮为图标样式，hover 显示文字提示
• 多选：拖框或 ⌘/Ctrl 点选多个节点，Delete 一次删除
• 画布保存到 .bytequery/canvas/c_<id>.json，侧栏 Canvas 视图管理（新建 / 重命名 / 删除 / 打开）
• 支持撤销 / 重做（⌘Z / ⇧⌘Z）与键盘删除选中节点

6.1 分组（Group）：按分析主题组织节点

• 建组：拖框 / ⌘点选多个节点 → 工具栏「创建分组」或 ⌘G → 自动按包围盒生成带内边距的组框
• 多组归属：一个节点可同时属于多个分组（组内自动去重）——适合「同一张表既用于增长分析、也用于付费分析」
• 拖放：节点拖入组框即加入该组；拖出组边界即从该组移出（按节点中心点判定）
• 右键节点 → 勾选式菜单精确设置归属（可多选），或「移出所有分组」
• 移动组：拖动组框，组内所有成员节点跟随移动
• 调整边框大小：拖组右下角手柄 → 只改变框的长宽，不移动组、不挪动内部节点（区别于拖动框体=移动整组）
• 重命名：双击组 → 右侧面板直接编辑；或右键组 → 重命名
• 删除组：右键组 → 删除分组；只删组、不删节点，成员自动释放为 Ungrouped
• 空组自动清理；颜色循环取自预置调色板

6.2 Navigator：当前画布的结构目录

左侧栏实时展示 分组 → 成员 与 Ungrouped：

• 点击组名 → 画布定位到该组；点击节点 → 定位并高亮、刷新 Detail
• 折叠/展开只影响 Navigator，不影响画布上的组框
• 宽度可拖拽；可整个收起为窄条（左侧与右侧面板均支持收起）
• 与画布双向同步：建组 / 改名 / 增删成员 / 删除节点 / 源缺失都会实时反映

6.3 Note（思考层）：记录分析中的问题 / 假设 / 结论

Note 是独立的 Canvas Node Type，与 Q/R 平级——可以移动、选中、多选、分组、连线、导出，但不依赖 Query History / Saved Results，内容自身持久化在画布 JSON 里。

• 创建：工具栏「＋」→ Note；或右键画布空白处 → Note（新建后自动进入编辑）
• 编辑：双击 Note 进入 inline 编辑（标题 input + 正文 textarea）
  • Cmd/Ctrl + Enter 或点卡片右上 ✓ 保存；Esc 取消
  • 标题上限 100 字，正文 5000 字；正文超出可滚动查看
  • 编辑时 Cmd/Ctrl + A 全选 / C 复制 / X 剪切 / V 粘贴（webview 内剪贴板走 Extension Host 桥接）
• 字号：工具栏「A」设全局默认，卡片「•••」可给单个 Note 单独设；优先级 单 Note > 全局 > 默认 13px（档位 11~18px）
• 颜色：6 种低饱和马卡龙预设（米黄 / 莫兰迪绿 / 蜜桃 / 蓝 / 紫 / 粉），卡片「•••」或右侧 Detail 切换，不支持自由调色
• Detail 面板：点 Edit 可在右侧面板内直接改标题 / 正文 / 颜色
• 纯文本：不做 Markdown / 富文本；内容经 React 转义渲染，输入 <script> 只显示为文本

6.4 节点语义与交互对照

Q = 查询（我查了什么/数仓建设代码）
R = 证据（我得到了什么/数仓建设结果）
N = 思考（我认为这意味着什么 / 接下来做什么）
Group = 主题/数仓建设分域
Edge  = 关系/血缘

6.5 导出为 PNG

工具栏「导出图片」→ 直接把整张画布（含组框、组标签、Q/R/N 节点、连线、箭头、连线标签）导出为高清 PNG，文件名默认取画布名：

• 全内容范围：导出的是所有内容的包围盒，不受当前视口限制
• 高清：2x 倍率绘制，适合贴进 PPT / 文档 / 飞书 / Slack
• 纯色背景：不包含 Navigator / Detail / 工具栏 / 网格，非编辑器截图观感
• 导出为独立 canvas 2D 重绘（非 DOM 截图），保证连线、箭头、标签完整可见

快捷键

两条绑定的是同一个 Run Selected SQL 命令，按你当前操作系统自动生效。

配置

🌟 常见问题

1. Chart 怎么配置？（选列速查）

Table 页右键列名 → 选角色，列头会出现 X / Y1 / Y2 / G 徽章；然后切到 Chart 页看图。

• 非双轴图只选 Y1；饼图只选 X（分组）和 Y1（数值）
• 同一 X 值有多行 → 用顶部「聚合」下拉选择 SUM / AVG / COUNT / MAX / MIN（Y1、Y2 各自独立）
• 未选分组列时，同一 X 的多行按聚合合并为单条线
• X 轴自动排序（数字按数值、日期按时间）
• 每轴图形可分别选柱状 / 折线 / 平滑曲线（Y1、Y2 下拉各自独立），双轴图可做左柱右线等组合

示例

每日消耗趋势        ：X=dt,      Y1=cost(SUM)
消耗 vs 曝光双轴    ：X=dt,      Y1=cost(SUM), Y2=pv(SUM)
各国消耗对比多线    ：X=dt,      Y1=cost(SUM), 分组=country
各国消耗占比饼图    ：X=country, Y1=cost(SUM)

2. 图表系列太多，怎么只看其中一条？

图例（图表顶部）支持筛选：

单击图例         → 隐藏 / 显示该系列（可叠加多个，做反选组合）
⌥ / Alt + 单击 A → 只看 A（其余全部隐藏）
再 ⌥ + 单击 A    → 恢复全部显示

选中「只看 A」后，同一操作再点一次即可还原；切换图表类型或重新选列也会自动重置。

3. 找不到之前保存的数据 / 画板怎么办？

数据保存在工作区根目录下的 .bytequery/（查询历史、保存结果、分析画布都在这里），换工作区后就看不到了。

解决：命令面板（Cmd+Shift+P）搜 「SQL Explorer: 切换数据目录」 → 选一个文件夹 → 之后所有历史 / 结果 / 画板都读写这个目录，且会被记住。也可用 「查看当前数据目录」 确认当前位置。

数据目录归属规则

• 默认跟随 SQL 文件所属的工作区根 —— 多项目隔离更干净，各项目一份 .bytequery/
• 多根工作区下，在哪个文件夹里写 SQL，数据就存在那个文件夹根下
• 同一工作区内在不同根之间切换文件时，数据目录也会跟着切（各自一份 .bytequery/）
• 手动「切换数据目录」的指定优先级最高，会覆盖上述自动规则

支持的数据源与限制

Local-first：凭据只存本地 SecretStorage，结果/历史存工作区 .bytequery/。

Feedback

发现 Bug 或者有功能建议？请到插件代码仓库提交 Issue，也可以添加我的微信（Yvonne1ru，好友申请验证信息请写明你的问题）

Found a bug or have a feature request? Open an issue in the extension repository, or reach me via WeChat (Yvonne1ru, please state your issue in the verification message).