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），僅供參考