Java 如何实现自然语言查询数据库：LangChain4j SQL 模块入门指南-平芜编程栈

Java 如何实现自然语言查询数据库：LangChain4j SQL 模块入门指南

【免费下载链接】langchain4jLangChain4j is an idiomatic, open-source Java library for building LLM-powered applications on the JVM. It offers a unified API over popular LLM providers and vector stores, and makes implementing tool calling (including MCP support), agents and RAG easy. It integrates seamlessly with enterprise Java frameworks like Quarkus and Spring Boot.项目地址: https://gitcode.com/GitHub_Trending/la/langchain4j

LangChain4j 是一个把大语言模型（LLM）接入 Java 应用的开源库，它的实验性 SQL 模块支持自然语言查询数据库：问一句"上个月有多少订单"，它会把问题翻译成 SQL、执行并返回结果。这篇文章讲清它能干什么、怎么接入、哪里要留意。

被催着查数时，别再手写 SQL 了

做数据相关的工作，大概率遇到过这种场景：业务方丢来一个问题，你得打开数据库、想清楚要 join 哪几张表、写好查询、跑出来再截图发过去。问题一变，SQL 又得从头写。写 SQL 本身不难，难在它成了瓶颈。LangChain4j SQL 模块做的事就是"自然语言转 SQL"（NL2SQL）：让模型写 SQL，系统负责执行并把结果拿回来。

它能干什么：元数据 + 提示词 + 校验 + 重试

它的定位是一句话：RAG（检索增强生成）流程里的一个内容检索器（ContentRetriever），只是检索对象不是向量库，而是数据库。核心类是SqlDatabaseContentRetriever，位于 experimental/langchain4j-experimental-sql 模块。

它能跑通，靠四件事配合：

元数据自动采集：从 DataSource（统一的数据库连接抽象）里读出表结构、列类型、主外键、表和列的注释，拼成 CREATE TABLE 语句喂给模型。
提示词模板：把方言和表结构告诉模型，并要求它只输出一条 SQL，别的话都不许说。
JSqlParser 校验：JSqlParser 是一个解析和校验 SQL 语句的库，用它确认模型生成的确实是一条 SELECT，不是就直接丢弃。
重试修正：执行失败时把报错信息回传给模型，让它修改 SQL，最多进行 maxRetries 次。

3 步接入 SQL 问答

第一步，克隆仓库：git clone https://gitcode.com/GitHub_Trending/la/langchain4j。

第二步，在工程里加上该模块的依赖，版本与依赖明细见 experimental/langchain4j-experimental-sql/pom.xml：

<dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-experimental-sql</artifactId> </dependency>

第三步，创建检索器。关键参数有四个：dataSource（数据库连接）、chatModel（生成 SQL 的模型）、sqlDialect（方言名，如 MySQL、PostgreSQL，不填时会从连接自动探测）、maxRetries（执行失败后的重试次数，默认 0）。Builder 还提供databaseStructure（手写的表结构 DDL）和promptTemplate（自定义提示词）两项可选配置。最小示例：

SqlDatabaseContentRetriever retriever = SqlDatabaseContentRetriever.builder() .dataSource(dataSource) .chatModel(chatModel) .maxRetries(2) .build();

之后传入每个自然语言问题，都会得到一份包含 SQL 和执行数据的结果。

幕后：一次提问在系统里经历什么

以"上个月有多少订单"为例：系统先把方言和表结构拼进系统提示，连同问题一起发给模型，拿到 SQL；然后剥掉模型可能附带的 Markdown 代码标记；接着 JSqlParser 解析这条 SQL，不是 SELECT 就直接返回空，不碰数据库。执行成功，结果按 CSV 格式连同 SQL 一起返回；执行失败，就把错误信息接回对话再问一次，直到成功或重试次数用尽。

只读权限为什么必须开

这个类的 Javadoc 开头就写着警告：使用的数据库用户必须是只读权限。原因很直接——模型的输出无法百分之百信任。SELECT 校验能挡住大部分明显的危险，但"执行的是 SELECT"不等于"结果无害"，模型可能用一条合法查询把整张表或大量数据捞出来。数据库层面的权限限制是最后防线，代码里的校验只是第一道门。源码注释里也明说了：它不保证生成的 SQL 无害。