数据服务语法支持的占位符以及函数，可以在任意语法规则中使用，UnifiedSQL 语法除外。

1 占位符

共支持 ${}和 #{} 两种占位符：

1.1 ${} 占位符

${} 表示直接将对应的数据插入到 SQL 中：
如图所示，id_list 在 SQL 写为 ${id_list}，id_list 的请求参数使用 string 类型，测试值写为 (1,2,3)。

此时转化的SQL为：

1.2 #{} 占位符

#{} 操作符会根据数据类型自动生成 SQL 片段，可以有效解决 SQL 注入：

如图所示，id_list 在 SQL 写为 #{id_list}，id_list 的请求参数使用 array 类型，测试值写为 [1,2,3]。

此时转化的SQL为：

2 函数

函数必须结合占位符使用，且只会对用户传入的参数进行计算，查询返回的结果不能使用这些函数。

2.1 TO_YYYYMMDD

语法

1. 函数签名：

   TO_YYYYMMDD(date)

2. 入参：

   date : 必须为YYYY-mm-dd日期格式的string类型参数。

3. 出参：

   YYYYmmdd 日期格式的 string 类型参数，不会在前后加单引号。

示例

1. 字面量作为入参

   select a from t where p_date=${TO_YYYYMMDD('2023-05-01')}
   转换成
   select a from t where p_date=20230501
   

2. 结合 ${} 占位符使用

   select a from t where date=${TO_YYYYMMDD(date)}    // 入参{"date": "2023-05-01"}
   转换成
   select a from t where p_date=20230501
   

   或者

   select a from t where date='${TO_YYYYMMDD(date)}'    // 入参{"date": "2023-05-01"}
   select a from t where p_date='20230501'
   

3. 结合 #{} 占位符使用

   select a from t where date=#{TO_YYYYMMDD(date)}    // 入参{"date": "2023-05-01"}
   转换成
   select a from t where p_date='20230501'
   

2.2 ADD_DATE

语法

1. 函数签名：

   ADD_DATE(date, offset)

2. 入参：

   1. date : 必须为YYYYmmdd YYYY-mm-dd、 YYYY.mm.dd 、YYYY/mm/dd、YYYY_mm_dd、 YYYY:mm:dd日期格式的 string 类型参数。

   2. offset : int 类型的整数，可以为正数或负数。

3. 出参：

   与入参日期格式相同的 string 类型参数，不会在前后加单引号。

示例

1. 字面量作为入参

   select a from t where p_date='${ADD_DATE('2023-05-01', 1)}'
   转换成
   select a from t where p_date='20230502'
   

2. 结合 ${} 占位符使用

   select a from t where date='${ADD_DATE(date, 1)}'    // 入参{"date": "2023/05/01"}
   转换成
   select a from t where p_date='2023/05/02'
   

   或者

   select a from t where date='${ADD_DATE(date, -1)}'    // 入参{"date": "2023.05.01"}
   select a from t where p_date='2023.04.30'
   

3. 结合 #{} 占位符使用

   select a from t where date=#{ADD_DATE(date, -1)}    // 入参{"date": "2023:05:01"}
   转换成
   select a from t where p_date='2023:04:30'
   

2.3 SUB_DATE

与上方ADD_DATE函数相同。

2.4 DATE_PARTITION

语法

1. 函数签名：

   DATE_PARTITION(pattern, [logic_table_name]*)

2. 入参

   1. pattern : 日期格式占位符的 string 类型参数

      pattern 格式	含义	实例
      %Y	年，4位	2022
      %m	月，数值(00-12)	06
      %d	日，数值(0-31)	30
      %H	小时 (00-23)	20
      %i	分钟，数值(00-59)	35
      %s	秒(00-59)	59
      %S	秒(00-59)	59

   2. logic_table_name :就绪时间所相关的逻辑表名称，参数个数为 0 个或多个，0 个表示 api 关联的所有逻辑表，并且这些逻辑表相关的物理表需要创建就绪时间回调任务（写入数据就绪时间）。

3. 出参

   相关逻辑表中所有就绪时间最早的日期，string类型，不会在前后加单引号。

示例

1. 字面量作为入参

   select a from t where p_date=${DATE_PARTITION('%Y%m%d')}    // 表t就绪时间 20230502
   转换成
   select a from t where p_date=20230502
   

2. 结合 ${} 占位符使用

   select a from t where date='${DATE_PARTITION(pattern)}'    // 入参{"pattern": "%Y/%m/%d"} 表t就绪时间 20230502
   转换成
   select a from t where p_date='2023/05/02'
   

   或者

   select t.a from t join t2 on t.b=t2.b where t.date=${DATE_PARTITION('%Y%m%d', 't', 't2')}   // 表t就绪时间 20230502 表t2就绪时间 20230430
   转换成
   select t.a from t join t2 on t.b=t2.b where t.date=20230430
   

3. 结合 #{} 占位符使用

   select a from t where date=#{DATE_PARTITION('%Y-%m-%d')}    // 表t就绪时间 20230502
   转换成
   select a from t where p_date='2023-05-02'
   

2.5 DATE_SUB_PARTITION

语法

1. 函数签名

   DATE_SUB_PARTITION(pattern, partition_field ,partition_value [logic_table_name]*)

2. 入参

   1. pattern : 日期格式占位符的 string 类型参数

      pattern格式	含义	实例
      %Y	年，4位	2022
      %m	月，数值(00-12)	06
      %d	日，数值(0-31)	30
      %H	小时 (00-23)	20
      %i	分钟，数值(00-59)	35
      %s	秒(00-59)	59
      %S	秒(00-59)	59

   2. partition_field ：二级分区的字段名

   3. partition_value ：二级分区的字段值

   4. logic_table_name ：就绪时间所相关的逻辑表名称，参数个数为 0 个或多个，0个表示 api 关联的所有逻辑表。

   该函数将会过滤相关的逻辑表中，与传入的二级分区字段名+字段值相匹配的就绪时间，返回最早的数据就绪时间

3. 出参

   相关逻辑表中所有就绪时间最早的日期，string 类型，不会在前后加单引号。

示例

1. 字面量作为入参

   select a from t where p_date=${DATE_SUB_PARTITION('%Y%m%d', 'name', 'zhangsan')}    // 表t就绪时间 20230502
   转换成
   select a from t where p_date=20230502
   

2. 结合 ${} 占位符使用

   select a from t where date=${DATE_SUB_PARTITION(pattern, 'name', 'zhangsan')}    // 入参{"pattern": "%Y%m%d"} 表t二级分区key=name,val=zhangsan的就绪时间 20230502
   转换成
   select a from t where p_date='20230502'
   

   或者

   select t.a from t join t2 on t.b=t2.b where t.date=${DATE_PARTITION('%Y%m%d', 'name', 'zhangsan', 't', 't2')}   // 表t二级分区key=name,val=zhangsan的就绪时间 20230502 表t二级分区key=name,val=zhangsan的就绪时间 20230430
   转换成
   select t.a from t join t2 on t.b=t2.b where t.date=20230430
   

3. 结合 #{} 占位符使用

   select t.a from t join t2 on t.b=t2.b where t.date=#{DATE_PARTITION('%Y-%m-%d', 'name', 'zhangsan', 't', 't2')}     // 表t二级分区key=name,val=zhangsan的就绪时间 20230502 表t二级分区key=name,val=zhangsan的就绪时间 20230430 
   转换成 
   select t.a from t join t2 on t.b=t2.b where t.date='2023-05-02'