基础用法

本指南将介绍 SuperSQL 的基础用法，帮助你快速上手。

Text to SQL 基本用法

SuperSQL 的核心功能是将自然语言转换为 SQL 查询。以下是最简单的使用方式：

@RestController
public class QueryController {

    private final SpringSqlEngine sqlEngine;
    private final ChatModel chatModel;

    public QueryController(SpringSqlEngine sqlEngine, ChatModel chatModel) {
        this.sqlEngine = sqlEngine;
        this.chatModel = chatModel;
    }

    @GetMapping("/query")
    public Object query(@RequestParam String question) {
        String sql = sqlEngine.setChatModel(chatModel)
                .generateSql(question);
        Object result = sqlEngine.executeSql(sql);
        return result;
    }
}

训练数据库

在使用 SuperSQL 之前，需要先训练数据库表结构，让模型了解你的数据模型。

自动训练

在配置文件中设置 init-train: true，应用启动时会自动训练：

super-sql:
  init-train: true

手动训练 DDL

@GetMapping("/train-ddl")
public String trainDdl() {
    String ddl = """
        CREATE TABLE `user` (
            `id` BIGINT NOT NULL COMMENT '主键',
            `name` VARCHAR(50) NOT NULL COMMENT '用户名',
            `email` VARCHAR(100) NOT NULL COMMENT '邮箱',
            `age` INT COMMENT '年龄',
            `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
            PRIMARY KEY (`id`)
        ) ENGINE=INNODB DEFAULT CHARSET=utf8mb4 COMMENT='用户表';
    """;
    
    sqlEngine.setChatModel(chatModel)
            .train(TrainBuilder.builder()
                    .content(ddl)
                    .policy(TrainPolicyType.DDL)
                    .build());
    
    return "Training completed successfully";
}

手动训练 SQL 示例

@GetMapping("/train-sql")
public String trainSql() {
    String sql = "SELECT * FROM user WHERE age > 18;";
    String question = "查询所有成年用户";
    
    sqlEngine.setChatModel(chatModel)
            .train(TrainBuilder.builder()
                    .content(sql)
                    .question(question)
                    .policy(TrainPolicyType.SQL)
                    .build());
    
    return "Training completed successfully";
}

执行 SQL

基本查询

@GetMapping("/simple-query")
public Object simpleQuery() {
    String question = "查询所有用户";
    String sql = sqlEngine.setChatModel(chatModel)
            .generateSql(question);
    
    return sqlEngine.executeSql(sql);
}

条件查询

@GetMapping("/conditional-query")
public Object conditionalQuery(@RequestParam String condition) {
    String question = "查询年龄大于" + condition + "的用户";
    String sql = sqlEngine.setChatModel(chatModel)
            .generateSql(question);
    
    return sqlEngine.executeSql(sql);
}

聚合查询

@GetMapping("/aggregate-query")
public Object aggregateQuery() {
    String question = "统计每个年龄段的用户数量";
    String sql = sqlEngine.setChatModel(chat)Model)
            .generateSql(question);
    
    return sqlEngine.executeSql(sql);
}

使用 RagOptions

RagOptions 允许你配置 RAG 检索的参数：

@GetMapping("/query-with-options")
public Object queryWithOptions(@RequestParam String question) {
    String sql = sqlEngine.setChatModel(chatModel)
            .setOptions(RagOptions.builder()
                    .topN(5)              // 返回的 top N 条数据
                    .rerank(false)         // 是否进行重排序
                    .limitScore(0.4)       // 返回的分数阈值
                    .build())
            .generateSql(question);
    
    return sqlEngine.executeSql(sql);
}

RagOptions 参数说明

参数	类型	默认值	说明
topN	Integer	5	返回的 top N 条相关数据
rerank	Boolean	false
limitScore	Double	0.4	相似度分数阈值

错误处理

基本错误处理

@GetMapping("/safe-query")
public ResponseEntity<?> safeQuery(@RequestParam String question) {
    try {
        String sql = sqlEngine.setChatModel(chatModel)
                .generateSql(question);
        Object result = sqlEngine.executeSql(sql);
        return ResponseEntity.ok(result);
    } catch (Exception e) {
        log.error("Query failed: {}", e.getMessage());
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body("查询失败: " + e.getMessage());
    }
}

SQL 验证

@GetMapping("/validated-query")
public Object validatedQuery(@RequestParam String question) {
    String sql = sqlEngine.setChatModel(chatModel)
            .generateSql(question);
    
    if (sql == null || sql.trim().isEmpty()) {
        throw new IllegalArgumentException("生成的 SQL 为空");
    }
    
    if (sql.toLowerCase().contains("drop")) {
        throw new SecurityException("不允许执行 DROP 操作");
    }
    
    return sqlEngine.executeSql(sql);
}

完整示例

以下是一个完整的 Controller 示例：

@RestController
@RequestMapping("/api/supersql")
@RequiredArgsConstructor
public class SuperSqlController {

    private final SpringSqlEngine sqlEngine;
    private final ChatModel chatModel;
    private static final Logger log = LoggerFactory.getLogger(SuperSqlController.class);

    @PostMapping("/train")
    public ResponseEntity<String> train(@RequestBody TrainRequest request) {
        try {
            sqlEngine.setChatModel(chatModel)
                    .train(TrainBuilder.builder()
                            .content(request.getContent())
                            .question(request.getQuestion())
                            .policy(request.getPolicy())
                            .build());
            return ResponseEntity.ok("训练成功");
        } catch (Exception e) {
            log.error("训练失败", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("训练失败: " + e.getMessage());
        }
    }

    @PostMapping("/query")
    public ResponseEntity<?> query(@RequestBody QueryRequest request) {
        try {
            String sql = sqlEngine.setChatModel(chatModel)
                    .setOptions(RagOptions.builder()
                            .topN(request.getTopN())
                            .rerank(request.isRerank())
                            .limitScore(request.getLimitScore())
                            .build())
                    .generateSql(request.getQuestion());
            
            Object result = sqlEngine.executeSql(sql);
            
            return ResponseEntity.ok(Map.of(
                    "sql", sql,
                    "result", result
            ));
        } catch (Exception e) {
            log.error("查询失败", e);
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                    .body("查询失败: " + e.getMessage());
        }
    }

    @GetMapping("/health")
    public ResponseEntity<String> health() {
        return ResponseEntity.ok("SuperSQL is running");
    }
}

下一步

掌握了基础用法后，你可以：

• 学习 高级用法 了解更多高级特性
• 查看 API 文档 了解详细 API
• 探索 示例代码 获取更多示例