# 智能查数

「智能查数」让你用**自然语言**直接查询账本，由 AI 生成一条**只读 SQL** 并执行，结果以统计卡片、表格或图表展示，无需自己拼筛选条件。

> 这是与[统计面板的「AI 搜索」](/guide/dashboard#ai-搜索)不同的能力：AI 搜索是「自然语言 → 统计面板筛选条件」，智能查数则是「自然语言 → SQL 查询」，适合更自由、更灵活的问答。

## 入口与前提

- 先在[设置](/guide/settings#ai-模型配置)中**启用 AI** 并配置 API Key。
- 启用后，左侧菜单会出现「**智能查数**」（未启用时不显示）。
- 直接访问路由 `/smart-query` 也可进入。

![智能查数](https://adcarac.oss-cn-beijing.aliyuncs.com/finance-app-docs/screenshots/sql-query.png)

## 提问

在页面顶部的输入框用一句自然语言描述想查的内容，例如：

- 上个月一共花了多少钱
- 按分类统计今年的支出
- 今年收入最高的一个月
- 各渠道的支出占比
- 本月支出最高的 5 笔

输入框支持多行（自动增高），点击「查询」或按 `Ctrl + Enter`（Mac 为 `⌘ + Enter`）提交；页面也会给出示例问题，点击即可直接查询。

## 结果展示

系统会根据查询结果自动选择展示方式：

| 结果形态 | 展示 |
|---|---|
| 只有一行 | **统计卡片**，逐项展示各列的数值 |
| 多行且含数值列 | **动态表格**，可切换为**柱状图**或**饼图** |
| 多行但无数值列 | 表格 |

- 结果中的**渠道**列会自动显示渠道名称（含自定义渠道），而不是内部编码。
- 结果最多返回 **1000 行**；超过时会提示「仅展示前 1000 行」。
- 无结果的查询会显示空态提示。

## 生成的 SQL

查询结果上方会给出 AI 生成的 SQL，默认折叠：

- 使用 `sql-formatter` 缩进、`highlight.js` 语法高亮，便于阅读。
- 可点「复制 SQL」把格式化后的语句复制到剪贴板。
- 同时展示对查询意图的简要说明。

## 历史提问

页面下方是**历史提问**折叠面板，按账号在服务端持久化：

- 展示提问内容与时间（精确到分钟），默认展示最近若干条。
- 支持按关键字**搜索**历史。
- 点击某条历史可**回填并立即重新查询**；也可复制该次提问。
- 可一键**清空历史**。

> 当前会话内的提问与结果会缓存在浏览器会话中，切换账号时自动清除；结果超过 500 行时只缓存提问与视图，避免占用过多空间。

## 安全与隐私

智能查数始终以**只读**方式访问你自己的数据：

- 仅允许**单条 `SELECT`** 查询，拒绝任何写操作、DDL、多语句、`SELECT INTO`、`FOR UPDATE` 与危险函数。
- 只能查询**系统白名单内的数据表**，且每张表都会被强制注入当前用户的隔离条件，**只能看到本人数据**。
- 查询**不返回原始数据（`rawData`）与交易号**等敏感字段。
- 生成的 SQL 会经过安全网关校验后才执行，并限制执行时间与返回行数。

AI 本身收到的信息仅为你的自然语言提问与可查询的表结构说明，不包含账单原始字段。

## 相关

- [AI 能力](/guide/ai)：系统全部 AI 功能一览。
- [统计面板](/guide/dashboard)：固定的统计汇总与图表。