1.9.3. 统一SQL Java 接口

1.9.3.1. 简介

统一SQL提供了 Java API，可供 JAVA 程序直接调用；用户只需要在Maven项目中引入sql-convert-runtime依赖即可使用 JAVA API，具体可参考集成统一SQL代理。

1.9.3.2. SQL转换

1.9.3.2.1. 接口签名

public static String parse(String sql, String sourceDialect, String targetDialect) {}
public static String parse(String sql, String sourceDialect, String targetDialect, long sessionId) {}

该接口方法位于sql-convert-runtime模块中的com.hundsun.lightdb.unisql.golang.Transformer类中。

1.9.3.2.2. 接口请求参数

JAVA 接口的每一项参数说明如下：

接口请求参数
参数名	类型	是否必须	说明	示例
sql	string	是	源SQL语句	"select name, avg(score) from student_score group by name"
sourceDialect	string	是	源数据库方言名称，具体可查看数据库支持范围中的 `源端`	ORACLE
targetDialect	string	是	目标数据库方言名称，具体可查看数据库支持范围中的 `目标端`	LIGHTDB_ORACLE
sessionId	long	否	会话ID

1.9.3.2.3. 接口返回参数

返回类型是一个 string，表示转换后的sql语句，返回值有2种情况：

返回 null 值：表示转换失败
返回非 null 值：表示转换后的sql语句

1.9.3.2.4. 调用示例

本例子使用标准的 JAVA 测试用例展示该接口的使用方式，示例代码如下：

@Test
public void parseTest() {
    String parsedSql = Transformer.parse("SELECT MEDIAN(amount) AS median_amount FROM aggregate_sales " +
            "WHERE product_id = 1 ORDER BY  median_amount", DbType.ORACLE.name(), DbType.POSTGRESQL.name());
    System.out.println("统一SQL转换后sql " + parsedSql);
}

示例执行结果，Oracle的median函数将被转换为PostgreSQL的percentile_cont分析函数。

统一SQL转换后sql SELECT percentile_cont(5e-01) WITHIN GROUP (ORDER BY amount) AS median_amount FROM aggregate_sales WHERE product_id=1 ORDER BY median_amount

1.9.3.3. 创建会话

1.9.3.3.1. 接口签名

public static Long createSession() {}
public static Long createSession(String targetDbType, int targetDbVersion) {}

1.9.3.3.2. 接口请求参数

createSession()

无参数，并且不支持库级别的参数配置

createSession(String targetDbType, int targetDbVersion)

接口请求参数
参数名	类型	是否必须	说明	示例
targetDbType	String	是	目标数据库类型，具体可查看数据库支持范围中的 `目标端`	"GAUSSDB_ORACLE"
targetDbVersion	int	是	目标数据库版本号，支持数据库版本号请参考统一SQL参考手册，若gaussdboracle 505.2.0 为 5050200	5050200

1.9.3.3.3. 接口返回参数

返回类型是一个 Long，会话ID

1.9.3.4. 销毁会话

1.9.3.4.1. 接口签名

public static void freeSession(Long sessionId) {}

1.9.3.4.2. 接口请求参数

JAVA 接口的每一项参数说明如下：

接口请求参数
参数名	类型	是否必须	说明	示例
sessionId	Long	是	会话ID

1.9.3.4.3. 接口返回参数

无

1.9.3.5. 参数设置

1.9.3.5.1. 接口签名

public static void setSessionParamStr(String paramName, String paramValue, long sessionId) {}

1.9.3.5.2. 接口请求参数

JAVA 接口的每一项参数说明如下：

接口请求参数
参数名	类型	是否必须	说明	示例
paramName	String	是	参数名	"unisql.skip"
paramValue	String	是	参数值	"true"
sessionId	long	是	会话ID

1.9.3.5.3. 参数类型说明

根据配置参数的不同级别，setSessionParamStr 的行为有所不同：

1. 会话参数（session scope）

设置只影响当前会话（session）
典型参数：unisql.skip、unisql.error.skip、unisql.charset 等
示例：设置当前会话跳过SQL转换

Long sessionId = Transformer.createSession("ORACLE_19C", 1900);
// 设置当前会话跳过SQL转换
Transformer.setSessionParamStr("unisql.skip", "false", sessionId);

2. 全局参数（global scope）

如果配置了库级别参数，则影响当前目标库；如果没有配置库级别参数，则影响所有库
典型参数：unisql.keyword.doublequotes、unisql.auto.increment.column 等

示例1：未对参数进行库级别配置时，设置影响所有库

// 配置文件中没有配置 unisql.keyword.doublequotes.oracle_19c-1900
// 此时设置影响所有目标库
Long sessionId = Transformer.createSession("ORACLE_19C", 1900);
Transformer.setSessionParamStr("unisql.keyword.doublequotes", "TEST1,TEST2", sessionId);
// 对 ORACLE_19C、GAUSSDB_ORACLE 等所有库都生效

示例2：参数配置了库级别时，设置只影响当前库

// 配置文件中配置了库级别参数：
// unisql.keyword.doublequotes.oracle_19c-1900 = ORA_KEY1,ORA_KEY2

// 创建 ORACLE_19C 会话，只影响 ORACLE_19C，不影响 其他库
Long sessionId1 = Transformer.createSession("ORACLE_19C", 1900);
Transformer.setSessionParamStr("unisql.keyword.doublequotes", "NEW_KEY1,NEW_KEY2", sessionId1);

警告

设置参数时不需要带库名称和版本号，因为createSession已经指定过了

3. 系统参数（system scope）

不允许通过此接口修改
系统参数在进程启动时初始化，运行时不支持修改
典型参数：unisql.lib.dir、unisql.log.path、unisql.log.level 等
如需修改系统参数，请通过配置文件

注意

部分全局参数不支持库级别配置（如 unisql.cache、 unisql.sql.pretty 等）
设置参数前请确认参数的级别和作用范围，避免产生非预期效果

1.9.3.5.4. 接口返回参数

无

1.9.3.6. 元数据加载

1.9.3.6.1. 接口说明

统一SQL提供元数据加载功能，用户可以通过调用元数据加载接口将目标端数据库的元数据信息加载到统一SQL中，从而提升SQL转换的准确性。具体接口签名及参数说明可参考: 元数据管理。