DB-GPT 资源工具指南深入解析 sql_query 只读 SQL 查询工具【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT导读sql_query是 DB-GPT 资源Resource模块中用于对用户所选数据库执行只读 SQL 查询的内置工具其唯一职责是以安全可控的方式从结构化数据源中取数并以 Markdown 表格形式返回结果供 Agent 在深入分析之前快速探查表结构、抽样数据或回答业务问题。本文以该工具的使用文档为骨架结合仓库中的真实实现源码完整讲解其参数格式、安全机制、输出行为、50 行截断与字符上限等细节并给出可直接复制的调用示例帮助你理解 Agent 在对话应用中是如何通过该工具安全地访问数据库的。工具概览Overviewsql_query对用户选定的数据库执行只读 SQL 查询。它是数据探查路径上的第一站在复杂的 Python 分析或可视化之前用它快速验证数据结构、字段含义与数据量是成本最低、速度最快的结构化数据检视方式。从源码看该工具属于资源工具Resource Tool体系在 Agent 的 React 工具注册表中以sql_query为名登记见 react_tools.py同时也有独立实现文件 sql_query.py。工具函数通过dbgpt.agent.resource.tool.base中的tool装饰器定义声明了供 LLM 理解使用的description对用户选择的数据库执行 SQL 查询仅支持 SELECT。参数格式Parameterssql_query只接收一个参数sql类型为字符串值为完整的 SELECT 语句。工具注册的 JSON Schema 如下{ sql: SELECT statement }在源码实现中参数会被做如下预处理见 sql_query.pysql.strip()去除首尾空白rstrip(;)去除末尾的分号避免分号引发语句解析差异upper().lstrip()转大写并去左侧空白用于后续关键字匹配。工具执行依赖一个database_connector数据源连接器。若 Agent 尚未在左侧面板选择数据源连接器为None工具会直接返回提示文本未选择数据库请先在左侧面板选择一个数据源。而不是抛出异常。工具行为What it does结合文档描述与源码实现sql_query的执行流程可以归纳为三步1. 安全校验只读约束。工具维护一份禁止关键字列表见 sql_query.pyforbidden [ INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, ]对预处理后的语句若其开头命中任一关键字立即返回安全限制提示安全限制: 不允许执行 X 语句仅支持 SELECT 查询。语句不会被提交到数据库。也就是说sql_query在应用层就以语句白名单前缀的方式实现了只读保障文档中列出的INSERT、UPDATE、DELETE、DROP、ALTER、CREATE全部在拦截范围之内此外还额外覆盖了TRUNCATE、GRANT、REVOKE三个危险或权限类操作。2. 执行查询并格式化。通过database_connector.run(sql_stripped)执行语句。结果首行为列名其余为数据行。工具将列名与每一行数据拼接为 Markdown 表格首行为表头第二行为分隔行---之后为数据行见 sql_query.py。3. 输出裁剪与包装。查询结果以 JSON 结构返回其中output_type为markdown或text统一放在chunks列表中例如{ chunks: [ { output_type: markdown, content: | product_category | total_revenue |\n| --- | --- |\n| ... | ... | } ] }空结果与异常处理查询返回空结果时输出查询返回空结果。执行过程中抛出异常时输出SQL 执行失败: {str(e)}保证工具失败时 Agent 能拿到可读的错误信息继续决策。何时使用When to use itsql_query适用于以下三类典型场景探查表结构与抽样数据在深入分析前用SELECT * FROM table LIMIT 10或查询information_schema类元数据确认字段名称、类型与取值分布从结构化数据回答业务问题如按品类聚合销售额、统计订单量等可以直接用 SQL 表达的聚合类问题为 Python 分析准备数据先取数确认口径再交给代码解释器code-interpreter等工具做进一步计算与可视化。需要注意的是它定位于检索而非变更与文档目录中的其他资源工具如 code-interpreter、shell-interpreter分工不同前者负责数据获取后者负责计算与执行环境操作。示例Example文档给出的典型示例是按产品品类聚合销售额并按降序排序{ sql: SELECT product_category, SUM(revenue) AS total_revenue FROM sales GROUP BY product_category ORDER BY total_revenue DESC }对应返回的 Markdown 表格大致形如product_categorytotal_revenueElectronics125000Apparel78000......结果裁剪50 行截断与字符上限文档明确指出将较大结果截断为前 50 行。源码中这一行为体现在两处见 sql_query.py行数截断只渲染rows[:50]若总行数超过 50在表格末尾追加说明仅显示前 50 行共 N 行字符截断MAX_SQL_OUTPUT_CHARS 20_000当渲染后的表格超过 2 万字符时截断到该上限并追加提示Output truncated at 20000 chars。这种双层截断是为了防止单条宽表查询把 LLM 上下文窗口撑爆。从更宏观的视角看sql_query的输出裁剪只是 DB-GPT Agent 上下文防溢出三层防线中的第一层工具内预截断后两层由 storage.py 中的结果持久化机制承担工具内输出上限per-tool output cap即上述 50 行与 20000 字符的裁剪这是工具作者能直接控制的防线该文件的文档注释明确以sql_query、kb_cat为例单结果持久化maybe_persist工具返回后若输出超过该工具注册的阈值默认DEFAULT_RESULT_SIZE_CHARS 100_000字符完整输出被写入persisted_results/{conv_id}/目录上下文内仅保留 1500 字符预览与文件路径引用模型可用read_file工具按需读取单轮总预算enforce_turn_budget一个 assistant 轮次内所有工具结果合计超过turn_budget默认 200K 字符时将最大的未持久化结果继续落盘直至总额收敛。因此sql_query的大结果不会永久丢失前 50 行与 2 万字符保证即时可用完整数据仍可通过持久化层按需获取。使用注意事项Notes只读是硬约束工具在应用层拦截以INSERT、UPDATE、DELETE、DROP、ALTER、CREATE以及TRUNCATE、GRANT、REVOKE开头的语句任何变更类操作在到达数据库前即被拒绝检索优先禁止变更该工具只用于取数retrieval绝不用于写操作mutation依赖已选数据源使用前必须在界面左侧面板选中目标数据源否则连接器为空并返回提示文本返回格式固定成功时返回output_type: markdown的表格块失败或空结果返回output_type: text的提示文本Agent 与上层应用可直接按chunks结构消费。小结sql_query是 DB-GPT 资源工具中数据探查环节的标准件参数极简单个sql字段、约束严格只读白名单前缀校验、输出可控50 行 2 万字符双层裁剪 持久化兜底。理解它的参数契约、安全边界与输出裁剪策略是正确编排数据类 Agent 应用、避免写操作风险与上下文溢出的前提。如需查看完整实现可直接阅读 sql_query.py 与 react_tools.py其姊妹工具文档见 docs/docs/agents/modules/resource/tools/。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DB-GPT 资源工具指南：深入解析 sql_query 只读 SQL 查询工具
DB-GPT 资源工具指南深入解析 sql_query 只读 SQL 查询工具【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT导读sql_query是 DB-GPT 资源Resource模块中用于对用户所选数据库执行只读 SQL 查询的内置工具其唯一职责是以安全可控的方式从结构化数据源中取数并以 Markdown 表格形式返回结果供 Agent 在深入分析之前快速探查表结构、抽样数据或回答业务问题。本文以该工具的使用文档为骨架结合仓库中的真实实现源码完整讲解其参数格式、安全机制、输出行为、50 行截断与字符上限等细节并给出可直接复制的调用示例帮助你理解 Agent 在对话应用中是如何通过该工具安全地访问数据库的。工具概览Overviewsql_query对用户选定的数据库执行只读 SQL 查询。它是数据探查路径上的第一站在复杂的 Python 分析或可视化之前用它快速验证数据结构、字段含义与数据量是成本最低、速度最快的结构化数据检视方式。从源码看该工具属于资源工具Resource Tool体系在 Agent 的 React 工具注册表中以sql_query为名登记见 react_tools.py同时也有独立实现文件 sql_query.py。工具函数通过dbgpt.agent.resource.tool.base中的tool装饰器定义声明了供 LLM 理解使用的description对用户选择的数据库执行 SQL 查询仅支持 SELECT。参数格式Parameterssql_query只接收一个参数sql类型为字符串值为完整的 SELECT 语句。工具注册的 JSON Schema 如下{ sql: SELECT statement }在源码实现中参数会被做如下预处理见 sql_query.pysql.strip()去除首尾空白rstrip(;)去除末尾的分号避免分号引发语句解析差异upper().lstrip()转大写并去左侧空白用于后续关键字匹配。工具执行依赖一个database_connector数据源连接器。若 Agent 尚未在左侧面板选择数据源连接器为None工具会直接返回提示文本未选择数据库请先在左侧面板选择一个数据源。而不是抛出异常。工具行为What it does结合文档描述与源码实现sql_query的执行流程可以归纳为三步1. 安全校验只读约束。工具维护一份禁止关键字列表见 sql_query.pyforbidden [ INSERT, UPDATE, DELETE, DROP, ALTER, TRUNCATE, CREATE, GRANT, REVOKE, ]对预处理后的语句若其开头命中任一关键字立即返回安全限制提示安全限制: 不允许执行 X 语句仅支持 SELECT 查询。语句不会被提交到数据库。也就是说sql_query在应用层就以语句白名单前缀的方式实现了只读保障文档中列出的INSERT、UPDATE、DELETE、DROP、ALTER、CREATE全部在拦截范围之内此外还额外覆盖了TRUNCATE、GRANT、REVOKE三个危险或权限类操作。2. 执行查询并格式化。通过database_connector.run(sql_stripped)执行语句。结果首行为列名其余为数据行。工具将列名与每一行数据拼接为 Markdown 表格首行为表头第二行为分隔行---之后为数据行见 sql_query.py。3. 输出裁剪与包装。查询结果以 JSON 结构返回其中output_type为markdown或text统一放在chunks列表中例如{ chunks: [ { output_type: markdown, content: | product_category | total_revenue |\n| --- | --- |\n| ... | ... | } ] }空结果与异常处理查询返回空结果时输出查询返回空结果。执行过程中抛出异常时输出SQL 执行失败: {str(e)}保证工具失败时 Agent 能拿到可读的错误信息继续决策。何时使用When to use itsql_query适用于以下三类典型场景探查表结构与抽样数据在深入分析前用SELECT * FROM table LIMIT 10或查询information_schema类元数据确认字段名称、类型与取值分布从结构化数据回答业务问题如按品类聚合销售额、统计订单量等可以直接用 SQL 表达的聚合类问题为 Python 分析准备数据先取数确认口径再交给代码解释器code-interpreter等工具做进一步计算与可视化。需要注意的是它定位于检索而非变更与文档目录中的其他资源工具如 code-interpreter、shell-interpreter分工不同前者负责数据获取后者负责计算与执行环境操作。示例Example文档给出的典型示例是按产品品类聚合销售额并按降序排序{ sql: SELECT product_category, SUM(revenue) AS total_revenue FROM sales GROUP BY product_category ORDER BY total_revenue DESC }对应返回的 Markdown 表格大致形如product_categorytotal_revenueElectronics125000Apparel78000......结果裁剪50 行截断与字符上限文档明确指出将较大结果截断为前 50 行。源码中这一行为体现在两处见 sql_query.py行数截断只渲染rows[:50]若总行数超过 50在表格末尾追加说明仅显示前 50 行共 N 行字符截断MAX_SQL_OUTPUT_CHARS 20_000当渲染后的表格超过 2 万字符时截断到该上限并追加提示Output truncated at 20000 chars。这种双层截断是为了防止单条宽表查询把 LLM 上下文窗口撑爆。从更宏观的视角看sql_query的输出裁剪只是 DB-GPT Agent 上下文防溢出三层防线中的第一层工具内预截断后两层由 storage.py 中的结果持久化机制承担工具内输出上限per-tool output cap即上述 50 行与 20000 字符的裁剪这是工具作者能直接控制的防线该文件的文档注释明确以sql_query、kb_cat为例单结果持久化maybe_persist工具返回后若输出超过该工具注册的阈值默认DEFAULT_RESULT_SIZE_CHARS 100_000字符完整输出被写入persisted_results/{conv_id}/目录上下文内仅保留 1500 字符预览与文件路径引用模型可用read_file工具按需读取单轮总预算enforce_turn_budget一个 assistant 轮次内所有工具结果合计超过turn_budget默认 200K 字符时将最大的未持久化结果继续落盘直至总额收敛。因此sql_query的大结果不会永久丢失前 50 行与 2 万字符保证即时可用完整数据仍可通过持久化层按需获取。使用注意事项Notes只读是硬约束工具在应用层拦截以INSERT、UPDATE、DELETE、DROP、ALTER、CREATE以及TRUNCATE、GRANT、REVOKE开头的语句任何变更类操作在到达数据库前即被拒绝检索优先禁止变更该工具只用于取数retrieval绝不用于写操作mutation依赖已选数据源使用前必须在界面左侧面板选中目标数据源否则连接器为空并返回提示文本返回格式固定成功时返回output_type: markdown的表格块失败或空结果返回output_type: text的提示文本Agent 与上层应用可直接按chunks结构消费。小结sql_query是 DB-GPT 资源工具中数据探查环节的标准件参数极简单个sql字段、约束严格只读白名单前缀校验、输出可控50 行 2 万字符双层裁剪 持久化兜底。理解它的参数契约、安全边界与输出裁剪策略是正确编排数据类 Agent 应用、避免写操作风险与上下文溢出的前提。如需查看完整实现可直接阅读 sql_query.py 与 react_tools.py其姊妹工具文档见 docs/docs/agents/modules/resource/tools/。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考