shark-系统常用函数

本章节只包含shark插件新增的系统常用函数。

rand()
描述：0.0到1.0之间的随机数。等价于random。
返回值类型：double precision
示例：
```
openGauss=# SELECT rand();
        rand
-------------------
0.254671605769545
(1 row)
```
rand(seed int)
描述：根据入参设置随机数种子，随后生成 0.0 到 1.0 之间的随机数。等价于 setseed + random。种子的有效值范围为 [-2 ^ 31, 2 ^ 31 - 1]。
返回值类型：double precision
示例：
```
openGauss=# SELECT rand(1);
        rand
-------------------
0.0416303444653749
(1 row)
```

day(timestamp)

描述：获取日期/时间值中天数的值。

返回值类型：double precision

示例：

openGauss=# SELECT day(timestamp '2001-02-16 20:38:40');
day
-----------
    16
(1 row)

openGauss=# SELECT day('2002-4-25'::date);
day
-----------
    25
(1 row)

openGauss=# SELECT day('2025-02-28 00:00:01'::timestamp(0) without time zone);
day
-----------
    28
(1 row)

ERROR_NUMBER()
描述：返回PL过程中异常的错误号。
参数类型: 无
返回值类型：int
示例：参见ERROR_MESSAGE()示例
ERROR_SEVERITY()
描述：返回PL过程中异常的严重性值。
参数类型: 无
返回值类型：int
示例：参见ERROR_MESSAGE()示例
ERROR_STATE()
描述：返回PL过程中异常的错误消息的状态号
参数类型: 无
返回值类型：int
示例：参见ERROR_MESSAGE()示例
ERROR_PROCEDURE()
描述：返回PL过程中生成错误的存储过程或触发器的名称
参数类型: 无
返回值类型：text
示例：参见ERROR_MESSAGE()示例
ERROR_LINE()
描述：返回PL过程中出现错误的行号
参数类型: 无
返回值类型：int
示例：参见ERROR_MESSAGE()示例
ERROR_MESSAGE()
描述：返回PL过程中错误消息的完整文本
参数类型: 无
返回值类型：text
示例：

    openGauss=#CREATE TABLE test(a int);
    openGauss=#CREATE OR REPLACE PROCEDURE p1()
               AS
               BEGIN
                  select 1/0;
               END;
               /
    openGauss=#CREATE OR REPLACE PROCEDURE p2()
               AS
               BEGIN
                   BEGIN TRY
                       delete from test;
                       insert into test values(1);
                       insert into test values(2);
                       call p1();
                       insert into test values(3);
                   END TRY
                   BEGIN CATCH
                       insert into test values(4);
                       RAISE NOTICE 'ERROR_NUMBER() is %', ERROR_NUMBER();
                       RAISE NOTICE 'ERROR_SEVERITY() is %', ERROR_SEVERITY();
                       RAISE NOTICE 'ERROR_STATE() is %', ERROR_STATE();
                       RAISE NOTICE 'ERROR_PROCEDURE() is %', ERROR_PROCEDURE();
                       RAISE NOTICE 'ERROR_LINE() is %', ERROR_LINE();
                       RAISE NOTICE 'ERROR_MESSAGE() is %', ERROR_MESSAGE();
                   END CATCH;
                END;
                /
    openGauss=#CALL p2();
    NOTICE:  ERROR_NUMBER() is 33816706
    NOTICE:  ERROR_SEVERITY() is 20
    NOTICE:  ERROR_STATE() is 1
    NOTICE:  ERROR_PROCEDURE() is p1()
    NOTICE:  ERROR_LINE() is 2
    NOTICE:  ERROR_MESSAGE() is division by zero

ident_current(table_or_view)

描述：返回为指定的表或视图生成的最后一个标识值。所生成的最有一个标识值可以针对任何会话和任何作用域。

参数类型: table_or_view为表或视图的名称，类型为nvarchar(128)。

返回值类型：numeric(38, 0)

示例：

openGauss=# CREATE TABLE employees(id int identity, name varchar(100) NOT NULL);
CREATE TABLE

-- 包含identity列的表，还未插入数据
openGauss=# SELECT ident_current('employees');
ident_current 
---------------
            1
(1 row)

-- 包含identity列的表，更新了序列值
openGauss=# INSERT INTO employees(name) VALUES('alice');
INSERT 0 1
openGauss=# INSERT INTO employees(name) VALUES('bob');
INSERT 0 1
openGauss=# SELECT ident_current('employees');
ident_current 
---------------
            2
(1 row)

dateadd(datepart , number , date)
描述：返回将number添加到date的datepart部分后得到的时间。
参数说明：
- datepart：
  要增加number的日期部分。
  datepart 缩写形式
  year yy, yyyy
  quarter qq, q
  month mm, m
  dayofyear dy, y
  day dd, d
  week wk, ww
  weekday dw, w
  hour hh
  minute mi, n
  second ss, s
  millisecond ms
  microsecond mcs
  nanosecond ns
- number：
  要增加的数量。
- date：
  合法的日期，指定起始时间。支持数据类型：date、time、timetz、timestamp和timestamptz。
示例：
```
select dateadd(hh,1,timestamp'1997-12-31 23:59:59');
         dateadd          
--------------------------
 Thu Jan 01 00:59:59 1998
(1 row)

select dateadd(dd,1,timestamp'1997-12-31 23:59:59');
         dateadd          
--------------------------
 Thu Jan 01 23:59:59 1998
(1 row)
```
datepart(datepart , date)
描述：返回表示 date 的指定 datepart 的整数。
参数说明：
- datepart：
  指定返回的特定部分。
  datepart 缩写形式
  year yy, yyyy
  quarter qq, q
  month mm, m
  dayofyear dy, y
  day dd, d
  week wk, ww
  weekday dw, w
  hour hh
  minute mi, n
  second ss, s
  millisecond ms
  microsecond mcs
  nanosecond ns
  TZoffset tz
  ISO_WEEK ISOWK, ISOWW
- date：
  合法的日期，指定时间。支持数据类型：date、time、timetz、timestamp和timestamptz。
示例：
```
SELECT DATEPART(year,timestamp'2007-10-30 12:15:32.1234567');
 datepart 
----------
     2007
(1 row)

SELECT DATEPART(quarter,timestamp'2007-10-30 12:15:32.1234567');
 datepart 
----------
        4
(1 row)
```
datename（datepart , date）
描述：返回表示 date 的指定 datepart 的字符串。
参数：
- datepart ：
  指定返回的特定部分。
  datepart 缩写形式
  year yy, yyyy
  quarter qq, q
  month mm, m
  dayofyear dy, y
  day dd, d
  week wk, ww
  weekday dw, w
  hour hh
  minute mi, n
  second ss, s
  millisecond ms
  microsecond mcs
  nanosecond ns
  TZoffset tz
  ISO_WEEK ISOWK, ISOWW
- date：
  合法的日期，指定起始时间。支持数据类型：date、time、timetz、timestamp和timestamptz。
示例：
```
SELECT DATENAME(mm,timestamp'2007-1-30 12:15:32.1234567');
 datename 
----------
 January
(1 row)

SELECT DATENAME(m,timestamp'2007-2-28 12:15:32.1234567');
 datename 
----------
 February
(1 row)
```

datepart	缩写形式
year	yy, yyyy
quarter	qq, q
month	mm, m
dayofyear	dy, y
day	dd, d
week	wk, ww
weekday	dw, w
hour	hh
minute	mi, n
second	ss, s
millisecond	ms
microsecond	mcs
nanosecond	ns

datepart	缩写形式
year	yy, yyyy
quarter	qq, q
month	mm, m
dayofyear	dy, y
day	dd, d
week	wk, ww
weekday	dw, w
hour	hh
minute	mi, n
second	ss, s
millisecond	ms
microsecond	mcs
nanosecond	ns
TZoffset	tz
ISO_WEEK	ISOWK, ISOWW

datepart	缩写形式
year	yy, yyyy
quarter	qq, q
month	mm, m
dayofyear	dy, y
day	dd, d
week	wk, ww
weekday	dw, w
hour	hh
minute	mi, n
second	ss, s
millisecond	ms
microsecond	mcs
nanosecond	ns
TZoffset	tz
ISO_WEEK	ISOWK, ISOWW

getdate()

描述：获取当前系统时间。

示例：

select getdate();
         getdate
-------------------------
 2025-08-22 06:05:14.853
(1 row)

len(expr)
描述：返回数据长度。
示例：
```
SELECT LEN('abc');
 len 
-----
   3
(1 row)
```
log10(float_expression)
描述：接受一个浮点数表达式，计算10为底的对数
参数类型：double precision
返回值类型：double precision
示例：
```
openGauss=# select log(100);
 log 
-----
   2
(1 row)
```
isnull(check_expression, replacement_value)
描述：返回第一个非NULL值
参数类型: check_expression可为任意类型，replacement_value需为可以隐式或显式地转换为check_expression的类型
返回值类型：返回值类型与check_expression类型相同
示例：
```
openGauss=# select isnull(1, NULL);
 isnull 
--------
      1
(1 row)

openGauss=# select isnull(NULL, 'abc');
 isnull 
--------
 abc
(1 row)
```
atn2(float_expression, float_expression)
描述：返回以弧度表示的角，该角位于正X轴和原点至点(y, x)的射线之间，其中x和y是两个指定的浮点数表达式的值
参数类型：double precision
返回值类型：double precision
示例：
```
openGauss=# select atan2(1.2, 2.5);
     atan2      
-----------------
 .44751997515717
(1 row)
```
charindex(expressionToFind, expressionToSearch [, start_location])
描述：在expressionToSearch中搜索expressionToFind第一次出现的位置，如果start_location存在的话，则从start_location开始
参数类型：expressionToFind与expressionToSearch为text类型，start_location为int类型
返回值类型：int
示例：
```
openGauss=# select charindex('aaa', 'aaa bbb ccc aaa');
 charindex 
-----------
         1
(1 row)

openGauss=# select charindex('aaa', 'aaa bbb ccc aaa', 4);
 charindex 
-----------
        13
(1 row)
```
datediff(datepart, startdate, enddate)
描述：返回指定datepart单位的enddate和startdate之间的差值
参数类型：datepart为指定的日期单位，详情参见下表。startdate和enddate为timestamp类型
返回值类型：int
datepart类型：
datepart 缩写形式
year yy, yyyy
quarter qq, q
month mm, m
dayofyear dy, y
day dd, d
week wk, ww
weekday dw, w
hour hh
minute mi, n
second ss, s
millisecond ms
microsecond mcs
nanosecond ns
示例：
```
openGauss=# select datediff(day, timestamp'1997-12-31 23:59:59', timestamp'1998-12-31 23:59:59');
 datediff 
----------
      365
(1 row)
```
datediff_big(datepart, startdate, enddate)
描述：返回指定datepart单位的enddate和startdate之间的差值
参数类型：datepart为指定的日期单位，同datediff。startdate和enddate为timestamp类型
返回值类型：bigint
示例
```
openGauss=# select datediff_big(second, timestamp'1997-12-31 23:59:59', timestamp'1998-12-31 23:59:59');
 datediff_big 
--------------
     31536000
(1 row)
```
cast(expression AS data_type[(length)])
描述：将表达式转换为指定类型
参数类型：expression为任意类型表达式，data_type为类型关键字，length为int类型
返回值类型：指定的data_type类型
备注：
- D库中，length默认值为30，该默认值主要适用于字符串相关类型，目前D兼容模式下char和varchar及其别名类型都适用该length默认值
示例：
```
openGauss=# select cast(123456789 AS char) as result;
         result             
--------------------------------
 123456789                     
(1 row)
```
try_cast(expression AS data_type[(length)])
描述：将表达式转换为指定类型，如进行不支持的类型转换则报错, 支持的类型转换但是转换失败情况下返回NULL
参数类型：expression为任意类型表达式，data_type为类型关键字，length为int类型
返回值类型：指定的data_type类型
备注：
- D库中，length默认值为30，该默认值主要适用于字符串相关类型，目前D兼容模式下char和varchar及其别名类型都适用该length默认值
```
openGauss=# select try_cast(123456789 AS smallint) as result;
 result 
--------

(1 row)
```

datepart	缩写形式
year	yy, yyyy
quarter	qq, q
month	mm, m
dayofyear	dy, y
day	dd, d
week	wk, ww
weekday	dw, w
hour	hh
minute	mi, n
second	ss, s
millisecond	ms
microsecond	mcs
nanosecond	ns

convert(data_type[(length)], expression[, style])

描述：将表达式转换为指定类型

参数类型：expression为任意类型表达式，data_type为类型关键字，length为int类型

返回值类型：指定的data_type类型

备注：

针对不容的类型转换，style可以具有下表所表示的某个值，其他值作为0进行处理
目前仅支持涉及日期，时间和浮点数，货币(money)的样式

表1 日期和时间样式

不带世纪位数	带世纪位数	标准	输入/输出
-	0或100	默认值	mon dd yyyy hh:miAM
1	101	美国	1 = mm/dd/yy 101 = mm/dd/yyyy
2	102	ANSI	2 = yy.mm.dd 102 = yyyy.mm.dd
3	103	英国/法国	3 = dd/mm/yy 103 = dd/mm/yyyy
4	104	德国	4 = dd.mm.yy 104 = dd.mm.yyyy
5	105	意大利	5 = dd-mm-yy 105 = dd-mm-yyyy
6	106	-	6 = dd mon yy 106 = dd mon yyyy
7	107	-	7 = Mon dd, yy 107 = Mon dd, yyyy
8或24	108	-	hh:mi:ss
-	9或109	默认格式 + 毫秒	9 = mon dd yyyy 109 = hh:mi:ss:mmmAM(PM)
10	110	美国	11 = yy/mm/dd 111 = yyyy/mm/dd
11	111	日本	11 = yy/mm/dd 111 = yyyy/mm/dd
12	112	ISO	12 = yymmdd 112 = yyyymmdd
-	13或113	欧洲默认格式 + 毫秒	dd mon yyyy hh:mi:ss:mmm(24小时制)
14	114	-	hh:mi:ss:mmm(24小时制)
-	20或120	ODBC规范	yyyy-mm-dd hh:mi:ss
-	21或25或121	time、date、datetime2和 datetimeoffset的ODBC规范(毫秒标识)默认值	yyyy-mm-dd hh:mi:ss.mmm(24小时制)
22	-	美国	mm/dd/yy hh:mi:ss AM(PM)
-	23	ISO8601	yyyy-mm-dd
-	126	ISO8601	yyyy-mm-ddThh:mi:ss.mmm
-	127	包括时区Z的ISO8601	yyy-MM-ddThh:mm:ss.fffZ
-	130	回历	dd mon yyyy hh:mi:ss:mmmAM
-	131	回历	dd/mm/yyyy hi:mi:ss:mmmAM

表2 float和real样式

值	输出
0	最多包含6位，根据需要使用科学计数法。
1	始终为8位值，根据需要使用科学计数法。
2	始终为16位值，根据需要使用科学计数法。
3	始终为17位值，用于无损转换。

表3 money样式

值	输出
0	小数点左侧每三位数字之间不以逗号分隔，小数点右侧取两位数。
1	小数点左侧每三位之间以逗号分隔，小数点右侧取两位数。
2	小数点左侧每三位数字之间不以逗号分隔，小数点右侧取四位数。
126	转换为char(n)或varchar(n)时，等同于样式2。

示例：

openGauss=# select convert(varchar, timestamp'2012-03-23 00:12:23', 1) as result;
  result  
----------
 03/23/12
(1 row)

try_convert(data_type[(length)], expression[, style])
描述：将表达式转换为指定类型，如进行不支持的类型转换则报错, 支持的类型转换但是转换失败情况下返回NULL
参数类型：expression为任意类型表达式，data_type为类型关键字，length为int类型
返回值类型：指定的data_type类型
示例：
```
openGauss=# select try_convert(smallint, 123456789) as result;
 result 
--------

(1 row)
```