[English](../en/data-sources.md) | 简体中文 # 数据源与表格导入这篇讲怎么接入数据库、上传表格，以及 AgentLab 怎么保证查询只读。给搭建者和管理员看。数据目录（给表和字段记业务含义）见[数据目录](data-catalog.md)。 ## 接入数据库数据源可以是业务库（MySQL / MariaDB、PostgreSQL、Oracle，驱动在 `[db]` 额外依赖里）、上传的表格，或手工登记的 SQLite 文件。 - 接入后点「探查结构」：读表、列、注释、外键和唯一约束。列类型存各数据库的完整写法，例如 `VARCHAR2(20 CHAR)`、`ENUM('a','b')`。 - 探查是后台任务，和同一个数据源的起草、剖析排队。几千张表的大库先建对象索引，再按探查范围读（见[数据目录](data-catalog.md#大库探查范围与按需加入)）。 - 一个数据源对应一个 schema。正式探查不接受 `?schema=` 临时换 schema，预览可以。 - 每个数据源有查询工具 `db_query__<源>`；运行时 agent 用 `db_schema__` 查表结构。 - 数据源卡片的地址是 `/data/databases#source-`。 - AgentLab 自己的库文件（例如换成 PostgreSQL 后留在数据目录里的 `agentlab.db`）不能登记成数据源。探查失败和「尚未探查」是两种状态。失败时点按钮解决不了，要先处理超时或更换 schema。数据源卡片会显示失败原因和该服务器上可选的库；agent 也会收到实情，并被告知可以直接查 `information_schema` 自己确认表结构。 ## 只读保证 - SQL 守卫：白名单动词判定、正文扫描、多语句拦截、结果集上限。 - `DROP` / `TRUNCATE` / `GRANT` 等在可写数据源上也一律拒绝。 - 以查询开头却会写的语句按写操作处理：`WITH … DELETE`、`SELECT … INTO`、`EXPLAIN ANALYZE`、`PRAGMA … =`、`set_config()` 等。 - 只读数据源在连接层也只读，不只靠守卫：SQLite 以 `mode=ro` 打开，PostgreSQL / MySQL 的会话事务只读。 - **Oracle 没有会话级只读开关**，只剩守卫一道。只读的 Oracle 数据源请配只读账号。 - 可写数据源上，同一个 `db_query__<源>`：查询直接执行，写操作要先确认，确认后才提交。能力登记里的声明不能让写语句免审批。 - 使用者的问数据和个人应用里，数据源一律只读（见[身份、权限与安全](identity-and-security.md#使用者的问数据)）。 ## 上传表格 Excel / CSV 上传后落成一个 SQLite 文件，注册为 `kind=sqlite` 的数据源，并自动生成 `db_query__` 工具。数字由 SQL 算出来，不靠模型从文本片段里读。 - 列类型逐列推断（INTEGER / REAL / TEXT），空单元格存为 NULL。整数列如果落成 TEXT，`ORDER BY` 会退化为字典序（`'10' < '9'`），而且不报错。 - 为什么不放进知识库：放进去只能被切块检索，数字就成了模型从片段里「读」出来的。产出复核拦得住凭空出现的数字，拦不住「从一堆片段里读错了一格」。 - 导入表格的数据源，系统按核对结果生成说明；数据目录不重复、也不改写这些说明。 - 报告里引用的上传表格单元格，可以追到原表的格子（推断的来源）。 ### 复杂报表用取数配方 - 复杂报表按取数配方导入，CSV 同样可以。夹在明细中间的小计，核对后不进数据。 - 配方的 AI 起草用「设置 → 偏好设置」里选的「起草模型」；空着时跟随助手的模型。 ### 按期累积 - 每月一份的明细可以按期累积成一张表。新的一期可以触发定时任务（见[事件触发](schedules.md#事件触发)）。 - 每个历史版本是一份完整副本，磁盘占用随期数和被引用的版本数增长。 - 除当前版本和被运行引用的版本外，每个数据源再保留最近启用过的 3 个版本；其余的会被回收，无法再启用。 ## 跨库合并跨库的问题不做联邦查询。各库先聚合到同一个键，再用合并查询节点（`merge`）在库外按键合并（内存 SQLite，同一套只读守卫）。 - 被截断的输入拒收。 - 键类型不一致、合并后行数变多，都会提醒。 - 报告里的数能一路追到两边的原始查询。 ## 遮罩列在数据源设置里列出要遮罩的列（`mask_columns`），按列名作用于整个数据源。 - 遮罩列只把列名和类型交给模型：它的注释、目录里这一列的中文名、码值和说明都不给。 - 剖析不对遮罩列取样，也不观察它的取值。 - 对开了登录的使用者，遮罩是边界；对搭建者、管理员和未开启登录时的所有人，遮罩只减少暴露（见[哪些角色看得到原值](identity-and-security.md#哪些角色看得到原值)）。