金仓数据库 KingbaseES 插件参考手册 K （2）

44. kdb_flashback ¶

44.1. 插件kdb_flashback简介 ¶

插件kdb_flashback是KingbaseES 的一个扩展插件。主要功能是提供错误数据的快速恢复能力，目前提供的闪回技术包括闪回回收站，闪回查询，闪回版本查询，闪回到任意时间点。

• 插件名为 kdb_flashback

• 插件版本 V1.0

44.2. 插件kdb_flashback加载方式 ¶

KingbaseES数据库默认将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，重启数据库时自动加载。

示例：

shared_preload_libraries = 'kdb_flashback'

44.3. 插件kdb_flashback的参数配置 ¶

kdb_flashback.enable_flashback_query

闪回查询的开启参数，默认开启。

kdb_flashback.db_recyclebin

闪回回收站开启参数，参数为bool类型，参数级别为PGC_SIGHUP，默认关闭。

44.4. 插件kdb_flashback的使用方法 ¶

闪回查询相关的技术使用方法

• 整个闪回技术(闪回查询和闪回表到指定时间点) 可以通过时间戳和CSN(commit sequence number) 两种方式进行。

• 两种方式目前都需要依赖提交的时间戳，因此需要开启track_commit_timestamp 这个参数。另外闪回查询还需要开启kdb_flashback.enable_flashback_query 的参数。

• 这里解释下时间戳和CSN 两个快照指定的方式，时间戳即timestamp 用户可以在闪回查询的快照时间表达式里指定任意一个有效的时间戳。

如果允许闪回查询，那么将返回该时刻能够可见的历史快照的数据。CSN 是提交顺序号，第一个有效的CSN为65536000000，CSN 随着提交线性增加。 因此如果用户指定一个有效的CSN，比如65536000160，那么闪回查询将基于这个CSN 提交号构建历史快照。

• 闪回查询技术有一定的限制，在数据进行深度清理后和部分schema change 后将拒绝闪回查询（具体参考闪回查询须知）。

下面具体介绍这几种闪回技术, 在使用任何闪回查询相关的技术前，保证在配置文件中开启track_commit_timestamp 参数，并重启服务。

44.4.1. 闪回查询 ¶

闪回查询能否返回用户指定历史时刻的快照数据，历史快照时刻指定方式可以通过timestamp和csn 两种方式指定(具体语法参考 SELECT )。

例2-56 AS OF 闪回查询（timestamp） 语句的示例

flashback=# create table fb_example(id int, name varchar(100));
CREATE TABLE
flashback=# insert into fb_example values(1, 'name1');
INSERT 0 1
flashback=# insert into fb_example values(2, 'name1');
INSERT 0 1
flashback=# insert into fb_example values(3, 'name1');
INSERT 0 1
flashback=# select * from fb_example;
 id | name
----+-------
  1 | name1
  2 | name1
  3 | name1
(3 rows)

flashback=# \set 'tp1' `date "+%Y-%m-%d %H:%M:%S.%N"`
flashback=# update fb_example set name = null;
UPDATE 3
flashback=# select * from fb_example;
 id | name
----+------
  1 |
  2 |
  3 |
(3 rows)

flashback=# select * from fb_example as of timestamp :'tp1';
 id | name
----+-------
  1 | name1
  2 | name1
  3 | name1
(3 rows)

例2-56 中的update 语句误将 name 更改为null，此时可以通过闪回查询查询到update前的数据。

通常CSN 方式进行闪回查询的时候，需要借助闪回版本查询确定合适的CSN 号，比如delete 事务误将fb_example 表删除了， 那么通过版本查询可以确定该delete 事务的CSN为65536000007，可以通过如下的闪回语句查询删除的数据。

例2-57 AS OF 闪回查询（CSN） 语句的示例

flashback=# select versions_startscn, versions_endcsn, * from fb_example versions between csn minvalue and maxvalue;
 versions_startscn | versions_endcsn | id | name
-------------------+-----------------+----+-------
       65536000003 |     65536000006 |  1 | name1
       65536000004 |     65536000006 |  2 | name1
       65536000005 |     65536000006 |  3 | name1
       65536000006 |     65536000007 |  1 |
       65536000006 |     65536000007 |  2 |
       65536000006 |     65536000007 |  3 |
(6 rows)

flashback=# select * from fb_example as of csn 65536000006;
 id | name
----+------
  1 |
  2 |
  3 |
(3 rows)

44.4.2. 闪回版本查询 ¶

闪回版本查询的作用主要有以下几个方面：

• 进行历史数据的分析。

• 查看数据的变更历史。

• 确定闪回表的精确时间点。

闪回版本查询拥有和Oracle 相同的参考伪列，伪列和功能参考下表。

表 44.4.1 闪回版本查询的伪列  ¶

伪列名	描述
VERSIONS_STARTTIME	元组被创建的时间戳
VERSIONS_ENDTIIME	元组被删除的时间戳
VERSIONS_STARTCSN	元组被创建的commit seqno
VERSIONS_ENDCSN	元组被删除的commit seqno
VERSIONS_OPERATION	对应的操作 D表示该元组被删除，I表示该元组被插入
VEERSIONS_XID	元组被创建的事务ID

闪回版本查询的start 和end 的快照表达式既可以指定一个有效的快照表达式，也可以通过minvalue 和maxvalue 两个关键字进行查询。 当指定时，将返回该表能够闪回查询的所有的版本信息。

例2-58 通过minvalue 和maxvalue 进行闪回版本查询（CSN） 语句的示例

flashback=# select versions_startcsn, versions_endcsn, versions_operation, * from fb_example versions between csn minvalue and maxvalue;
 versions_startcsn | versions_endcsn | versions_operation | id | name
-------------------+-----------------+--------------------+----+-------
       65536000003 |     65536000006 | D                  |  1 | name1
       65536000004 |     65536000006 | D                  |  2 | name1
       65536000005 |     65536000006 | D                  |  3 | name1
       65536000006 |     65536000007 | D                  |  1 |
       65536000006 |     65536000007 | D                  |  2 |
       65536000006 |     65536000007 | D                  |  3 |
       65536000008 |                 | I                  |  5 | name3
       65536000009 |                 | I                  |  6 | name3
(8 rows)

通过上面的例子，我们可以追溯fb_example 的版本变更的历史，65536000006 这个CSN 的事务做了一次update 的操作，65536000007 这个CSN的事务做了一次delete 的操作。因此如果我们想查询被删除前的数据可以尝试65536000006 这个CSN 快照。

44.4.3. 闪回表到指定时间点 ¶

闪回表到指定的时间点，实际上为用户提供了还原数据的一种手段，如果说闪回查询能够帮助用户查询历史的数据，那么闪回表实际上是帮助用户彻底的找回数据, 具体语法参考 FLASHBACK 。

闪回表的通常步骤：

• 通过闪回版本查询确定待闪回的版本范围，查询startxxx, endxxx, 和operation确定边界。

• 通过AS OF 闪回查询结合确定的边界锁定闪回查询的精确时间点，并观察数据时候符合预期。

• 通过FLASHBACK TABLE TO [ Timestamp | CSN ] asof_item， 完成表的闪回。

还是参考2-58 的例子，比如我们推理出错误更新name 的事务是65536000006 这个CSN，那么我们可以指定65536000005 进行闪回查询。 再通过flashback 闪回到误更前的时刻。

flashback=# select * from fb_example as of csn 65536000005;
 id | name
----+-------
  1 | name1
  2 | name1
  3 | name1
(3 rows)

flashback=# flashback table fb_example to csn 65536000005;
FLASHBACK TABLE
flashback=# select * from fb_example;
 id | name
----+-------
  1 | name1
  2 | name1
  3 | name1
(3 rows)

44.4.4. 闪回查询和闪回表技术的使用须知 ¶

• 闪回查询和闪回表技术依赖于历史的数据，如果历史数据因为vacuum、truncate、rewrite 等操作被回收掉，那么会导致无法闪回到这些操作之前的时刻。因此推荐用户在期望使用闪回查询的时候对vacuum 相关参数做一定的调整（关闭表级的autovacuum, 推荐调大vacuum_defer_cleanup_age 的值以降低历史数据被回收的机会）。

• 目前闪回查询和闪回表技术在vacuum、truncate、和部分ddl 之后将不允许进行闪回到这些操作之前。

• 闪回查询应用于视图或者物化视图里面应该尽量避免对于常量时间戳和CSN 的使用，可能会引发dump 和 restore的失败。

44.4.5. 闪回回收站 ¶

闪回回收站功能为用户提供一种误删表后还原表的一种手段，闪回回收站分为将回收站中的表闪回到删除之前的状态和清空回收站。

例2-59 flashback table to before drop 语句的示例

test=# flashback table range_partition_tb to before drop;
FLASHBACK TABLE
test=# \d
                          List of relations
Schema   |            Name            |       Type        | Owner

-----------+----------------------------+-------------------+--------

flashback | range_partition_tb | partitioned table | system flashback | range_partition_tb_part_01 | table | system flashback | range_partition_tb_part_02 | table | system

(3 rows)

回收站需用户定期维护，避免回收站膨胀，用户可以通过PURGE操作对回收站进行维护，PURGE操作分为删除回收站中一个指定表和清空回收站。 清理回收站时，回收站视图recyclebin和系统表sys_recyclebin中相关对象将被清除。

例2-60 purge table 语句的示例

test=# select * from recyclebin;
  oid  |       original_name        |           droptime            | type
-------+----------------------------+-------------------------------+-------
 24968 | range_partition_tb_part_02 | 2022-05-20 15:14:53.581052+08 | TABLE
 24965 | range_partition_tb_part_01 | 2022-05-20 15:14:53.581494+08 | TABLE
 24962 | range_partition_tb         | 2022-05-20 15:14:53.582074+08 | TABLE
 24971 | purge_test                 | 2022-05-20 15:15:45.027217+08 | TABLE
 24974 | purge_test1                | 2022-05-20 15:16:49.466221+08 | TABLE
(5 rows)

test=# purge table purge_test;
PURGE
test=# select * from recyclebin;
  oid  |       original_name        |           droptime            | type
-------+----------------------------+-------------------------------+-------
 24968 | range_partition_tb_part_02 | 2022-05-20 15:14:53.581052+08 | TABLE
 24965 | range_partition_tb_part_01 | 2022-05-20 15:14:53.581494+08 | TABLE
 24962 | range_partition_tb         | 2022-05-20 15:14:53.582074+08 | TABLE
 24974 | purge_test1                | 2022-05-20 15:16:49.466221+08 | TABLE
(4 rows)

test=# purge recyclebin;
PURGE
test=# select * from recyclebin;
 oid | original_name | droptime | type
-----+---------------+----------+------
(0 rows)

44.5. 插件kdb_flashback卸载方法 ¶

修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。

示例

shared_preload_libraries = ''

44.6. 插件kdb_flashback升级方法 ¶

kdb_flashback扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

45. kdb_license ¶

45.1. 插件kdb_license简介 ¶

插件kdb_license是KingbaseES的一个扩展插件。主要功能是管理服务器license相关的信息。默认加载，属于内置功能。

• 插件名为 kdb_license

• 插件版本 V1.0

45.2. 插件kdb_license加载方式 ¶

KingbaseES数据库默认在初始化数据库时，自动加载kdb_license扩展插件。无须人为加载。

45.3. 插件kdb_license的参数配置 ¶

无需配置任何参数

45.4. 插件kdb_license的使用方法 ¶

KingbaseES数据库初始化时自动加载kdb_license扩展插件。通常用户不直接使用该扩展插件。

45.5. 插件kdb_license卸载方法 ¶

kdb_license无法人为卸载。

45.6. 插件kdb_license升级方法 ¶

kdb_license扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

46. kdb_oracle_datatype ¶

46.1. 插件kdb_oracle_datatype简介 ¶

插件kdb_oracle_datatype初始化内置，兼容 Oracle 数据类型。

• 插件名为 kdb_oracle_datatype

• 插件版本 V1.3

46.2. 插件kdb_oracle_datatype加载方式 ¶

默认已经创建，如果没有创建需要在命令行执行create extension kdb_oracle_datatype;

示例：

create extension kdb_oracle_datatype;

46.3. 插件kdb_oracle_datatype的参数配置 ¶

无需配置任何参数。

46.4. 插件kdb_oracle_datatype的使用方法 ¶

加载插件kdb_oracle_datatype后，按照如下方式使用相应功能。

46.4.1. 支持blob、clob、nclob类型导入导出和置空 ¶

实现数值类型转换为字符类型

语法

调用如下函数使用：

blob_import(text)、blob_export(bytea, text)、empty_blob()、
clob_import(text, text)、clob_export(text, text, text)、empty_clob()、
nclob_import(text, text)、nclob_export(text, text, text)、empty_nclob()

示例

select blob_export('a'::bytea,'test'::text);
blob_export
-------------
   1
(1 行记录)

select blob_import('test'::text);
blob_import
-------------
a
(1 行记录)

select empty_blob();
empty_blob
------------

(1 行记录)

46.4.2. bpcharbyte类型 ¶

支持bpcharbyte类型

示例

select '12'::bpcharbyte;
bpcharbyte
------------
12
(1 行记录)

46.4.3. bpcharbyte类型操作符 ¶

bpcharbyte类型之间支持=、<>、>、>=、<、<=和~<~、~>~、~<=~、~、!~、~*、!~*、~~、!~~、~~*、!~~*操作符。

示例

select '12'::bpcharbyte ~>=~ '12'::bpcharbyte;
?column?
----------
t
(1 行记录)

46.4.4. bpcharbyte类型转换 ¶

支持bpcharbyte类型和text、bpchar、varchar类型转换。

示例：

select '12'::bpcharbyte::varchar;
varchar
---------
12
(1 行记录)

select '12'::bpcharbyte::text;
text
------
12
(1 行记录)

select '12'::bpcharbyte::bpchar;
bpchar
--------
12
(1 行记录)

46.5. 插件kdb_oracle_datatype卸载方法 ¶

系统启动自带插件，无法卸载。

46.6. 插件kdb_oracle_datatype升级方法 ¶

kdb_oracle_datatype扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

47. kdb_oracle_datatype_nls ¶

47.1. 插件kdb_oracle_datatype_nls简介 ¶

插件kdb_oracle_datatype_nls兼容oracle日期date类型。 此插件已经合入到插件kdb_oracle_datatype中。

• 插件名为 kdb_oracle_datatype_nls

• 插件版本 V1.0

47.2. 插件kdb_oracle_datatype_nls加载方式 ¶

此插件已经合入到插件kdb_oracle_datatype中，跟随插件kdb_oracle_datatype加载自己加载。

47.3. 插件kdb_oracle_datatype_nls的参数配置 ¶

无需配置任何参数。

47.4. 插件kdb_oracle_datatype_nls的使用方法 ¶

47.4.1. 操作符的支持 ¶

支持操作符+、-

示例：

select '2019-01-01'::date + '1'::interval as A;
          a
---------------------
2019-01-01 00:00:01
(1 行记录)


select '2019-01-03'::date - '2019-01-01'::date as A;
a
---
2
(1 行记录)

47.4.2. 索引的支持 ¶

支持hash和brin索引。

示例：

create table t1(c1 date);
create index hash_index on t1 using hash(c1);

create table t1(c1 date);
create index brin_index on t1 using brin(c1);

47.5. 插件kdb_oracle_datatype_nls卸载方法 ¶

此插件已经合入到插件kdb_oracle_datatype中，插件kdb_oracle_datatype为系统启动自带插件，无法卸载。

47.6. 插件kdb_oracle_datatype_nls升级方法 ¶

kdb_oracle_datatype_nls扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

48. kdb_orafce ¶

48.1. 插件kdb_orafce简介 ¶

kdb_orafce插件用来兼容oracle的packages和functions。

• 插件名为 kdb_orafce

• 插件版本 v3.9

48.2. 插件kdb_orafce加载方式 ¶

使用时需要在命令行执行create extension kdb_orafce;

示例：

create extension kdb_orafce;

48.3. 插件kdb_orafce的参数配置 ¶

无需配置任何参数。

48.4. 插件kdb_orafce的使用方法 ¶

加载插件kdb_orafce后，按照如下方式使用相应功能。

48.4.1. pg_catalog.trunc ¶

围绕特定的参数截断日期。

语法

pg_catalog.trunc(value timestamp without time zone, fmt text) return timestamp without time zone;

参数

value：指定被截断的值

fmt：指定被截断的格式

返回值

返回被截断的结果值。

注解

fmt可以为'year','month','day'等。

示例

select pg_catalog.trunc(now,'year');
     trunc
------------------------
2022-01-01 00:00:00+00
(1 行记录)

48.4.2. pg_catalog.round ¶

围绕特定的参数生成日期的近似数。

语法

pg_catalog.round(value timestamp without time zone, fmt text) return timestamp without time zone；

参数

value：指定被截断的值

fmt：指定被截断的格式

返回值

返回被截断的结果值的近似值。

注解

fmt可以为'year','month','day'等。

示例

select pg_catalog.round(now(),'year');
     round
------------------------
2022-01-01 00:00:00+00
(1 行记录)

48.4.3. pg_catalog.next_day ¶

返回大于指定值的第一个符合目标值的日期。

语法

pg_catalog.next_day(value pg_catalog.date, weekday text) return pg_catalog.date；
pg_catalog.next_day(value pg_catalog.date, weekday integer) return pg_catalog.date；

参数

value：指定被操作的日期值。

weekday：指定的目标值。

返回值

返回大于指定值的第一个符合目标值的日期。

注解

weekday可以为'mon','mon','monday'等。也可以为1-7(其中1代表周日，2代表周一.....)。

示例

select pg_catalog.next_day('2021-12-29'::timestamp without time zone, 'mon');
  next_day
------------
 2022-01-03
(1 行记录)

select pg_catalog.next_day('2021-12-29'::timestamp without time zone, 7);
  next_day
------------
 2022-01-01
(1 行记录)

48.4.4. pg_catalog.last_day ¶

获取指定日期的所在月份的最后一天。

语法

pg_catalog.last_day(value pg_catalog.date) return pg_catalog.date;

参数

value指定被操作的日期值。

返回值

返回指定日期的所在月份的最后一天。

示例

select pg_catalog.last_day('2021-11-29'::timestamp without time zone);
  last_day
------------
 2021-11-30
(1 行记录)

48.4.5. pg_catalog.months_between ¶

获取两个日期之间间隔的月份。

语法

pg_catalog.months_between(date1 pg_catalog.date, date2 pg_catalog.date) return numeric;

参数

date1：日期1。

date2：日期2。

返回值

返回两个日期之间间隔的月份（并不是整数）。

示例

select pg_catalog.months_between('2021-12-29','2021-11-15');
  months_between
------------------
 1.45161290322581
(1 行记录)

48.4.6. pg_catalog.add_months ¶

获取指定的日期增加特定个月份后的日期值。

语法

pg_catalog.add_months(day pg_catalog.date, value int) return pg_catalog.date；

参数

day：指定被加的日期。

value：指定增加的月份的值。

返回值

返回指定的日期增加特定个月份后的日期值。

示例

select pg_catalog.add_months(now(),12);
 add_months
------------
 2022-12-29
(1 行记录)

48.4.7. pg_catalog.set_nls_sort ¶

使指定的字符集与默认的字符集进行比较和排序。

语法

pg_catalog.set_nls_sort(text);

参数

text指定参与比较的字符集。

返回值

无。

示例

select pg_catalog.set_nls_sort('en_us.utf8');
 set_nls_sort
--------------

(1 行记录)

48.4.8. pg_catalog.instr: ¶

获取匹配的子串的位置值。

语法

pg_catalog.instr(str text, patt text, _start int, nth int) return int;
pg_catalog.instr(str text, patt text, _start int) return int;
pg_catalog.instr(str text, patt text) return int;

参数

str被搜索的字符串。

返回值

匹配的子串的位置值，从0开始，没有匹配到返回0。

示例

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy!','handsome');
 instr
-------
  10
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy!','handsome',15);
 instr
-------
  53
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','handsome',15);
 instr
-------
  53
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','handsome',15,1);
 instr
-------
  53
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','boy',15);
 instr
-------
  19
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','boy',15,1);
 instr
-------
  19
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','boy',15,2);
 instr
-------
  62
(1 行记录)

select pg_catalog.instr('zqz is a handsome boy.is this correct.yeah , a very handsome boy! a good boy!','boy',15,3);
 instr
-------
  74
(1 行记录)

48.4.9. pg_catalog.to_char ¶

将**参数**转化为text类型。

语法

pg_catalog.to_char(num smallint) return text;
pg_catalog.to_char(num int) return text;
pg_catalog.to_char(num bigint) return text;
pg_catalog.to_char(num real) return text;
pg_catalog.to_char(num double precision) return text;
pg_catalog.to_char(num numeric) return text;

参数

num被转换的目标值。

返回值

返回text类型的参数值。

示例

select pg_catalog.to_char(100);
 to_char
---------
 100
(1 行记录)

48.4.10. pg_catalog.to_number ¶

将参数转化为numeric。

语法

pg_catalog.to_number(str text) return numeric;

参数

str被转换的目标字符串。

返回值

返回numeric类型的**参数**值。

示例

select pg_catalog.to_number('100');
 to_number
-----------
     100
(1 行记录)

48.4.11. pg_catalog.to_date ¶

将字符串转化为timestamp。

语法

pg_catalog.to_date(str text) return timestamp;

参数

str被转换的目标字符串。

返回值

返回timestamp类型的**参数**值。

示例

select pg_catalog.to_date('2021-12-29');
     to_date
---------------------
 2021-12-29 00:00:00
(1 行记录)

48.4.12. pg_catalog.to_multi_byte ¶

将单字节字符串转化为双字节字符串。

语法

pg_catalog.to_multi_byte(str text) return text;

参数

str被转换的单字节字符串。

返回值

返回被转化为双字节的text值。

注解

使用时要注意数据库所在的字符集。

示例

select to_multi_byte('!@#$%^&*');
  to_multi_byte
------------------
 ！＠＃＄％＾＆＊
(1 行记录)

48.4.13. pg_catalog.to_single_byte ¶

将双字节字符串转化为单字节字符串。

语法

pg_catalog.to_single_byte(str text) return text;

参数

str被转换的双字节字符串。

返回值

返回被转化为单字节的text值。

注解

使用时要注意数据库所在的字符集。

示例

select to_single_byte(to_multi_byte('!@#$%^&*'));
 to_single_byte
----------------
 !@#$%^&*
(1 行记录)

48.4.14. sinh ¶

计算双曲（线）正弦值

语法

sinh(float8) return float8

参数

float8角度值。

返回值

返回双曲（线）正弦值。

示例

select sinh(0);
 sinh
------
  0
(1 行记录)

48.4.15. cosh ¶

计算双曲余弦值

语法

cosh(float8) return float8;

参数

float8角度值。

返回值

返回双曲（线）余弦值。

示例

select cosh(0);
 cosh
------
  1
(1 行记录)

48.4.16. tanh ¶

计算双曲正切 反双曲正弦值。

语法

tanh(float8) return float8;

参数

float8角度值。

返回值

返回numeric类型的**参数**值。

示例

select tanh(0);
 tanh
------
  0
(1 行记录)

48.4.17. dump ¶

分析输入的参数。

语法

dump("any") return varchar;
dump("any", integer) return varchar;

参数

"any" ：可以为任何类型的参数。

integer：可以为2,8,10,16。

返回值

返回解析的参数的类型的oid，类型长度以及类型对应的值。

integer指定要返回的类型的值的进制。

示例

select dump('123'::int,8);
      dump
-------------------------
 typ=23 len=4: 173,0,0,0
(1 行记录)

select dump('123',8);
       dump
---------------------------
 typ=705 len=4: 61,62,63,0
(1 行记录)

48.4.18. plvstr.rvrs ¶

倒转字符串或者部分子串。

语法

plvstr.rvrs(str text, _start int, _end int) return text;
plvstr.rvrs(str text, _start int) return text;
plvstr.rvrs(str text) return text;

参数

str：目标串。

_start：子串开始的位置值。

_end：子串结束的位置值。

返回值

返回倒转后的字符串。

示例

select plvstr.rvrs('abcdefg');
  rvrs
---------
 gfedcba
(1 行记录)

select plvstr.rvrs('abcdefg',0);
  rvrs
---------
 gfedcba
(1 行记录)

select plvstr.rvrs('abcdefg',1);
  rvrs
---------
 gfedcba
(1 行记录)

select plvstr.rvrs('abcdefg',2);
  rvrs
--------
 gfedcb
(1 行记录)

select plvstr.rvrs('abcdefg',2,3);
 rvrs
------
 cb
(1 行记录)

48.4.19. oracle.substr ¶

截断字符串。

语法

oracle.substr(str text, _start numeric) return text;
oracle.substr(str text, _start numeric, len numeric)；

参数

str：目标串。

_start：截断的位置。

len：截断的长度。

返回值

返回截断后的字符串。

示例

select oracle.substr('zqz is a handsome boy',2);
    substr
----------------------
 qz is a handsome boy
(1 行记录)

select oracle.substr('zqz is a handsome boy',2,10);
   substr
------------
 qz is a ha
(1 行记录)

48.4.20. oracle.add_days_to_timestamp ¶

增加日期并转换为timestamp;

语法

oracle.add_days_to_timestamp(oracle.date,integer) return timestamp;
oracle.add_days_to_timestamp(oracle.date,bigint) return timestamp;
oracle.add_days_to_timestamp(oracle.date,smallint) return timestamp;
oracle.add_days_to_timestamp(oracle.date,numeric) return timestamp;

参数

oracle.date目标日期。

返回值

返回增加指定天数后的timestamp值。

第二个**参数**可以带有小数。

示例

select oracle.add_days_to_timestamp(now(),1);
 add_days_to_timestamp
-----------------------
 2021-12-31 10:37:46
(1 行记录)

select oracle.add_days_to_timestamp(now(),2);
 add_days_to_timestamp
-----------------------
 2022-01-01 10:37:48
(1 行记录)

select oracle.add_days_to_timestamp(now(),2.5);
 add_days_to_timestamp
-----------------------
 2022-01-01 22:37:51
(1 行记录)

48.4.21. oracle.subtract ¶

减去日期并转换为timestamp;

语法

oracle.subtract (oracle.date, integer) return timestamp;
oracle.subtract (oracle.date, bigint) return timestamp;
oracle.subtract (oracle.date, smallint) return timestamp;
oracle.subtract (oracle.date, numeric) return timestamp;
oracle.subtract(oracle.date,oracle.date) return double precision；

参数

oracle.date目标日期。

返回值

返回减去指定天数或者日期后的timestamp值。

第二个**参数**可以带有小数，也可以是指定的日期。

示例

select oracle.subtract(now(),2.5);
    subtract
---------------------
 2021-12-27 22:42:32
(1 行记录)

select oracle.subtract(now(),2);
    subtract
---------------------
 2021-12-28 10:42:36
(1 行记录)

select oracle.subtract(now(),now()-1);
 subtract
----------
    1
(1 行记录)

48.4.22. oracle.add_months ¶

给指定的日期增加月份。

语法

oracle.add_months(timestamp with time zone,integer) return timestamp;

参数

timestamp：目标timestamp值。

integer：增加指定的月份的值。

返回值

返回增加指定月份后的timestamp值。

第二个**参数**可以带有小数，也可以是负数。

示例

select oracle.add_months(now(),-1);
   add_months
---------------------
 2021-11-30 10:45:47
(1 行记录)

select oracle.add_months(now(),+1);
   add_months
---------------------
 2022-01-30 10:45:53
(1 行记录)

select oracle.add_months(now(),20);
   add_months
---------------------
 2023-08-30 10:45:57
(1 行记录)

select oracle.add_months(now(),1.5);
   add_months
---------------------
 2022-02-28 10:46:00
(1 行记录)

48.4.23. oracle.last_day ¶

获取指定日期所在的月份的最后一天。

语法

oracle.last_day(timestamptz) return timestamp;

参数

timestamp目标timestamp值。

返回值

返回指定日期所在的月份的最后一天的timestamp值。

示例

select oracle.last_day(now());
    last_day
---------------------
 2021-12-31 10:47:12
(1 行记录)

select oracle.last_day(now()-30);
    last_day
---------------------
 2021-11-30 10:47:16
(1 行记录)

select oracle.last_day(now()+3);
    last_day
---------------------
 2022-01-31 10:47:23
(1 行记录)

48.4.24. oracle.months_between ¶

获取两个日期值之间所间隔的月份

语法

oracle.months_between(timestamp with time zone,timestamp with time zone) return numberic;

参数

timestamp目标timestamp值。

返回值

返回两个日期值之间所间隔的月份值。 两个参数有顺序之分。

示例

select oracle.months_between(now(),'2021-01-01 14:31:00');
      months_between
------------------
 16.1612903225806
(1 行记录)

.. code::
select oracle.months_between(now(),'2021-11-30');
 months_between
----------------
        1
(1 行记录)

select oracle.months_between(now(),'2021-10-30');
 months_between
----------------
        2
(1 行记录)

select oracle.months_between(now(),'2022-1-30');
 months_between
----------------
       -1
(1 行记录)

48.4.25. oracle.next_day ¶

获取指定的接下来的日期。

语法

oracle.next_day(timestamp with time zone,integer) return timestamp;
oracle.next_day(timestamp with time zone,text) return timestamp;

参数

timestamp：目标timestamp值。

integer：需要增加的日期的天数。

text：指定所获取的特定的日期。

返回值

返回指定的接下来的日期。text可以是'sun','sunday'等。

示例

select oracle.next_day(now(),2);
    next_day
---------------------
 2022-01-03 13:58:07
(1 行记录)

select oracle.next_day(now(),'sun');
    next_day
---------------------
 2022-01-02 14:03:47
(1 行记录)

48.4.26. oracle.to_date ¶

将text串转换为相对应的日期。

语法

oracle.to_date(text) return oracle.date;
oracle.to_date(t1 text, t2 text) return oracle.date;

参数

text目标字符串。

返回值

返回对应的日期。 t2为对应的日期的格式。

示例

select oracle.to_date(now());
     to_date
---------------------
 2021-12-30 14:14:26
(1 行记录)

select oracle.to_date(now(), 'yyyy-mm-dd');
     to_date
---------------------
 2021-12-30 00:00:00
(1 行记录)

select oracle.to_date(now(), 'yyyy-mm');
     to_date
---------------------
 2021-12-01 00:00:00
(1 行记录)

48.4.27. oracle.to_char ¶

将timestamp转换为相应的字符串。

语法

oracle.to_char(timestamp) return text;

参数

timestamp目标值。

返回值

返回日期对应的字符串。

示例

select oracle.to_char(now());
      to_char
----------------------------
 2021-12-30 14:35:30.462850
(1 行记录)

48.4.28. oracle.sysdate ¶

获取session所在时区的当前的时间。 将timestamp转换为相应的字符串。

语法

oracle.sysdate() retrun text;

返回值

返回session所在时区的当前的时间。

示例

select oracle.sysdate();
     sysdate
---------------------
 2021-12-30 06:37:44
(1 行记录)

48.4.29. oracle.sessiontimezone ¶

获取session的timezone。

语法

oracle.sessiontimezone() return text;

参数

无

返回值

返回session所在的时区。

示例

select oracle.sessiontimezone();
 sessiontimezone
-----------------
 prc
(1 行记录)

48.4.30. oracle.dbtimezone ¶

获取数据库的timezone。

语法

oracle.dbtimezone() return text;

参数

无

返回值

返回数据库所在的时区。

示例

select oracle.dbtimezone();
 dbtimezone
------------
 gmt
(1 行记录)

48.5. 插件kdb_orafce卸载方法 ¶

卸载时drop extension kdb_orafce即可。

示例：

drop extension kdb_orafce;

48.6. 插件kdb_orafce升级方法 ¶

kdb_orafce扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

49. kdb_protect ¶

49.1. 插件kdb_protect简介 ¶

kdb_protect插件是KingbaseES 的一个扩展插件。主要功能是提供保护database、schema、table等逻辑对象不被DROP的能力。

• 插件名为 kdb_protect

• 插件版本 v1.0

49.2. 插件kdb_protect加载方式 ¶

使用时需要在命令行执行create extension kdb_protect;

示例：

create extension kdb_protect;

49.3. 插件kdb_protect的参数配置 ¶

无需配置任何参数。

49.4. 插件kdb_protect的使用方法 ¶

加载插件kdb_protect后，按照如下方式使用相应功能。

49.4.1. kdb_protect.protect_add ¶

添加被保护对象到保护表中。

语法

kdb_protect.protect_add(text name, char type);
kdb_protect.protect_add(text name, char type, bool iscascade);

参数

name：被保护对象的名字

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

iscascade：是否级联。只对db、schema有效。

返回值

成功返回't'，失败返回'f'或报错

示例

select kdb_protect.protect_add('table1', 't');
select kdb_protect.protect_add('table1', 't', true);

49.4.2. kdb_protect.protect_add_oid ¶

添加被保护对象到保护表中。

语法

kdb_protect.protect_add_oid(Oid objid, char type);
kdb_protect.protect_add_oid(Oid objid, char type, bool iscascade);

参数

objid：被保护对象的oid

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

iscascade：是否级联。只对db、schema有效。

返回值

成功返回't'，失败返回'f'或报错

示例

select kdb_protect.protect_add_oid(16394, 't');
select kdb_protect.protect_add_oid(16394, 't', true);

49.4.3. kdb_protect.protect_remove ¶

从保护表中删除被保护对象。

语法

kdb_protect.protect_remove(text name, char type);
kdb_protect.protect_remove(text name, char type, bool iscascade);

参数

name：被保护对象的名字

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

iscascade：是否级联。只对db、schema有效。

返回值

成功返回't'，失败返回'f'或报错

示例

select kdb_protect.protect_remove('table1.mysch', 't');
select kdb_protect.protect_remove('table1.mysch', 't', true);

49.4.4. kdb_protect.protect_remove_oid ¶

从保护表中删除被保护对象。

语法

kdb_protect.protect_remove_oid(Oid objid, char type);

参数

objid：被保护对象的oid

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

返回值

成功返回't'，失败返回'f'或报错

示例

select kdb_protect.protect_remove_oid(16385, 't');

49.4.5. kdb_protect.protect_remove_all ¶

删除保护表中所有被保护对象。

语法

kdb_protect.protect_remove_all();

参数

无

返回值

成功返回't'，失败返回'f'或报错

示例

select kdb_protect.protect_remove_all();

49.4.6. kdb_protect.protect_show() ¶

显示所有被保护对象。

语法

kdb_protect.protect_show();

参数

无

返回值

成功返回保护的对象信息，失败报错

示例

select * from kdb_protect.protect_show();

49.4.7. kdb_protect.protect_show_detail() ¶

显示所有被保护对象（更详细信息）。

语法

kdb_protect.protect_show_detail();

参数

无

返回值

成功返回保护的对象信息，失败报错

示例

select * from kdb_protect.protect_show_detail();

49.4.8. kdb_protect.protect_show_one() ¶

显示一个被保护对象。

语法

kdb_protect.protect_show_one(text name, char type);

参数

objid：被保护对象的oid

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

返回值

成功返回保护的对象信息，失败报错

示例

select * from kdb_protect.protect_show_one('table1', 't');

49.4.9. kdb_protect.protect_show_one_detail(text name, char type) ¶

显示一个被保护对象（更详细信息）。

语法

kdb_protect.protect_show_one_detail(text name, char type);

参数

objid：被保护对象的oid

type：被保护对象的类型，如下：

'd' --database(数据库) 's' --schema(模式) 't' --table(表/分区表) 'v' --view/materialized view(视图/物化视图) 'f' --function/procedure(函数/存储过程)

返回值

成功返回保护的对象信息，失败报错

示例

select * from kdb_protect.protect_show_one_detail('table1', 't');

49.5. 插件kdb_protect卸载方法 ¶

卸载时drop extension kdb_protect即可。

示例：

drop extension kdb_protect;

49.6. 插件kdb_protect升级方法 ¶

kdb_protect扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

50. kdb_raw ¶

50.1. 插件kdb_raw简介 ¶

kdb_raw定义了一套对于raw数据类型的操作。

• 插件名为 kdb_raw

• 插件版本 V1.0

50.2. 插件kdb_raw加载方式 ¶

在使用kdb_raw 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启 KingbaseES 数据库。

示例：

shared_preload_libraries = 'kdb_raw';

50.3. 插件kdb_raw的参数配置 ¶

无需配置任何参数

50.4. 插件kdb_raw的使用方法 ¶

加载插件kdb_raw后，在命令行执行create extension kdb_raw;使用插件

示例：

create extension kdb_raw;

50.4.1. utl_raw.cast_to_varchar2 ¶

utl_raw.cast_to_varchar2将raw类型转换为varchar2类型,返回varchar2

示例：

-- test utl_raw.cast_to_varchar2(null)
\set SQLTERM /
CREATE OR REPLACE FUNCTION test0022()
RETURNS BOOLEAN AS
DECLARE V1 raw ;
DECLARE V3  VARCHAR2;
BEGIN
V3 = utl_raw.cast_to_varchar2(V1);
return (V3 is null);
END;
/
CREATE FUNCTION

\set SQLTERM ;

select * from test0022();
test0022
----------
t
(1 行记录)

50.4.2. utl_raw.cast_to_raw： ¶

utl_raw.cast_to_raw将varchar2类型转换为raw类型,返回raw

示例：

\set SQLTERM /
CREATE OR REPLACE FUNCTION test0040()
RETURNS raw AS
DECLARE V1  VARCHAR2 := 'abcd';
DECLARE V3 raw;
BEGIN
        V3 = utl_raw.cast_to_raw(V1);
        return V3;
END;
/
\set SQLTERM ;
select * from test0040();
test0040
------------
\x61626364
(1 row)

\set SQLTERM /
CREATE OR REPLACE FUNCTION test0040()
RETURNS raw AS
DECLARE V1  VARCHAR2 := 'abcd';
DECLARE V3 raw;
BEGIN
V3 = utl_raw.cast_to_raw(V1);
return V3;
END;
/
CREATE FUNCTION
\set SQLTERM ;

select * from test0040();
test0040
------------
\x61626364
(1 行记录)

50.4.3. utl_raw.length ¶

utl_raw.length获取raw类型参数的字节值,返回int4

示例：

\set SQLTERM /
CREATE OR REPLACE FUNCTION test0030()
RETURNS INT AS
DECLARE V1 raw := 'hello金大金仓';
DECLARE V2  INT;
BEGIN
V2 = utl_raw.length(V1);
return V2;
END;
/
CREATE FUNCTION
\set SQLTERM ;

select * from test0030();
test0030
----------
17
(1 行记录)

50.4.4. utl_encode.base64_encode ¶

utl_encode.base64_encode将raw的二进制形式编码成为base 64的元素并以raw的形式返回,返回raw。

示例：

\set SQLTERM /
CREATE OR REPLACE FUNCTION test0050()
RETURNS raw AS
DECLARE V1 raw := '\x404142434445';
DECLARE V2 raw;
BEGIN
V2 = utl_encode.base64_encode(V1);
return V2;
END;
/
CREATE FUNCTION
\set SQLTERM ;

select * from test0050();
test0050
--------------------
\x5145464351305246
(1 行记录)

50.4.5. utl_encode.base64_decode ¶

utl_encode.base64_decode读取基于base64编码的raw并将其解码为原始raw值并返回。

示例：

drop function if exists test0050();
DROP FUNCTION
\set SQLTERM /
CREATE OR REPLACE FUNCTION test0050()
RETURNS raw AS
DECLARE V1 raw := '\x404142434445';
DECLARE V2 raw;
BEGIN
V2 = utl_encode.base64_encode(V1);
V2 = utl_encode.base64_decode(V2);
return V2;
END;
/
CREATE FUNCTION
\set SQLTERM ;

select * from test0050();
test0050
----------------
\x404142434445
(1 行记录)

50.5. 插件kdb_raw卸载方法 ¶

修改kingbase.conf文件shared_preload_libraries参数去掉kdb_raw，并重启 KingbaseES 数据库。

示例：

shared_preload_libraries = '';

50.6. 插件kdb_raw升级方法 ¶

kdb_raw扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

51. kdb_resource_group ¶

51.1. 插件kdb_resource_group简介 ¶

kdb_resource_group是KingbaseES的一个扩展插件，通过kdb_resource_group可以实现资源组功能。资源组限额需求主要是让数据库对操作系统资源限制、控制与分离一个进程组的资源（如CPU、内存、磁盘输入输出等），基于cgroup对资源有更大的控制从而避免因操作系统效率低下而产生的过度的资源开销、低效的调度，资源分配不当等问题。

在KingbaseES中支持构建和管理资源组实现对资源控制的隔离。资源组功能依赖于操作系统的cgroup，所以仅支持类linux操作系统。

• 插件名为 kdb_resource_group

• 插件版本 V1.0

51.2. 插件kdb_resource_group加载方式 ¶

使用并开启资源组需要以下操作：

• 资源组功能依赖于操作系统的cgroup功能，所以必须安装cgroup并正确挂载和启动，对应的挂载的子系统目录给予操作用户写入和读取权限。

• 启动数据库前需要将动态库添加到 kingbase.conf 文件的 shared_preload_libraries 中，若已启动需重启数据库。

shared_preload_libraries = 'kdb_resource_group'

51.3. 插件kdb_resource_group的参数配置 ¶

• 在 kingbase.conf 文件中设置参数，开启资源组功能，默认是off为关闭状态

resource_group_activated = on

• 在 kingbase.conf 文件中扩展内的非必选参数，设置cgroup的挂载主目录，默认为'/sys/fs/cgroup',修改后需要重启数据库生效

kdb_resource_group.resource_group_path = '/sys/fs/cgroup' #(change requires restart)

• 在 kingbase.conf 文件中扩展内的非必选参数，设置kingbase可使用操作系统CPU的总量，默认为100，取值范围1~100，修改后需要删除cgroup下的kingbase节点，命令如下：cgdelete -r cpu:kingbase。并重启数据库生效。

kdb_resource_group.resource_group_total_cpu = 100 #(change requires restart)

注意

开启资源组后连接数据库报错或警告时，确认GUC参数设置，以及cgroup目录的权限和拥有者，可以使用以下命令清除资源组的kingbase节点，然后重新连接数据库会再次创建cgroup的kingbase节点。

cgdelete -r cpu:kingbase

51.4. 插件kdb_resource_group的使用方法 ¶

51.4.1. 创建资源组 ¶

创建一个资源组并设置参数值,只有superuser可以创建,最多支持90个资源组。

rgroup1为创建的资源组名称, 一个数据库内唯一，改对象不属于某个模式下。 cpu_cfs_quota_us、cpu_shares为设置控制资源类型的名称。 不同参数取值范围不同，非值域报错。

create resource group rgroup1 with (cpu_cfs_quota_us = 100, cpu_shares = 10000);

51.4.2. 修改资源组 ¶

修改一个资源组的限制值

alter resource group rgroup1 set (cpu_cfs_quota_us = 90);

示例：

设置一个资源组的相对CPU使用率 基于cgroup的cpu子系统，可以调用CPU的获取量，这里采用了完全公平调度程序（CFS），一个比例分配调度程序，可根据任务优先级∕权重或资源组分得的份额，在任务群组（cgroups）间按比例分配 CPU 时间（CPU 带宽）。

在 CFS 中，如果系统有足够的空闲 CPU 周期，资源组可获得比其自有份额更多的 CPU 可用量，因为该调度程序有连续工作的特性。此情况通常会在资源组根据相关共享消耗 CPU 时间时出现。

value 默认值： 10000 取值范围：10-10000

alter resource group rgroup1 set (cpu_shares = 5000);

示例：

设置一个资源组的CPU绝对使用率限制 此功能可以设定在某一阶段资源组中所有任务可运行的时间总量，一旦资源组中任务用完按配额分得的时间，它们就会被在此阶段的时间提醒限制流量，并在进入下阶段前禁止运行。 以此特性我们通过设置CFS_QUOTA_US限制CPU使用的绝对上限。 将参数的值设定为100，这表示资源组不需要遵循任何 CPU 绝对限制。这也是每个资源组的默认值。 表示kingbase占的总cpu使用量（基于GUC参数resource_group_total_cpu计算，默认为100），多核机器合并计算限制使用率，取值范围不变。

value 默认值：100，不限制cpu使用 取值范围：整数，1-100。

alter resource group rgroup1 SET (cpu_cfs_quota_us = 10);

51.4.3. 删除资源组 ¶

删除一个资源组

drop resource group rgroup1;

51.4.4. 查看资源组 ¶

查看资源组信息，通过系统表sys_resgroup来查看资源组信息。

select * from sys_resgroup;

注意

查看资源组资源值,通过系统表sys_resgroupcapability来查看资源组关联的相关值限制。 系统表 sys_resgroupcapability，任何用户都可以查询。

select * from sys_resgroupcapability;

51.4.5. 资源组关联用户 ¶

通过SQL语句关联数据库用户，将此用户加入资源组，限制其使用资源的情况。 由于资源组是在数据库下设置的，限制的是用户在某个数据库连接应用下的资源限额情况。 此SQL语句将resgroup_user1用户加入到rgroup1资源组中，resgroup_user1用户将受到rgroup1中资源组的资源使用控制。

create user resgroup_user1 superuser login;
alter resource group rgroup1 set (user='resgroup_user1');

51.4.6. 查看资源组与用户关联关系 ¶

查看资源组与用户关联关系，通过系统表sys_resauthid可查询数据库用户和资源组的关联

select * from sys_resauthid;

51.5. 插件kdb_resource_group卸载方法 ¶

修改 kingbase.conf 文件中 shared_preload_libraries 参数并设置 resource_group_activated 参数后重启数据库。

shared_preload_libraries = ''
resource_group_activated = off

51.6. 插件kdb_resource_group升级方法 ¶

kdb_resource_group扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

52. kdb_schedule ¶

52.1. 插件kdb_schedule简介 ¶

kdb_schedule是KingbaseES的一个扩展插件。主要功能是基于后台进程来实现自动作业功能。kdb_schedule插件提供了DBMS_JOB和DBMS_SCHEDULER包，其中定义了与自动作业功能相关的存储过程和函数。

• 插件名为 kdb_schedule

• 插件版本 V1.0

52.2. 插件kdb_schedule加载方式 ¶

使用 kdb_shcedule 之前，需要将他添加到 kingbase.conf 文件的 shared_preload_libraries 中，并重启数据库。

示例：

shared_preload_libraries = 'kdb_schedule' # (change requires restart)

52.3. 插件kdb_schedule的参数配置 ¶

以下三个配置选项可以在 kingbase.conf 文件中指定：

• job_queue_processes 允许用户启动的最大并发数，当其值设置为0时，表示不启动自动作业功能,默认为0，不开启自动作业。

• sys_job.log_level 用于设置JOB后台进程的日志级别，更改后需要重新加载配置文件，可选项：LOG_ERROR，LOG_WARNING，LOG_DEBUG，默认为LOG_ERROR。

• sys_job.poll_time 用于设置轮询系统表间隔时间,单位秒，默认值为10秒。

注意

kdb_shcedule目前不支持windows环境下使用。 在特殊环境下（申威...)，初始化数据库时，提示用户kdb_schedule.so缺失库文件时，需用户手动export LD_LIBRARY_PATH为数据库lib目录。

52.4. 插件kdb_schedule的使用方法 ¶

52.4.1. DBMS_JOB模式下存储过程 ¶

DBMS_JOB模式提供调度和管理作业任务的功能。该包功能可以由DBMS_SCHDULE替代。

DBMS_JOB具有如下限制：

1. 需要创建kdb_schedule扩展。

2. 仅支持PL/SQL类型的任务。

3. 仅支持本地任务。

4. 间隔时间采用日历表示法。

下表列出了DBMS_JOB子程序并简要的表述了它们。

52.4.1.1. BROKEN 存储过程 ¶

此程序将job设置为中止。设置为中止的job不会再运行。

语法格式

DBMS_JOB.BROKEN(
        job INTEGER,
        broken BOOLEAN,
        next_date TIMESTAMP DEFAULT now());

参数说明

表 52.4.1 broken参数  ¶

参数	描述
job	由系统分配的job的ID。
broken	将job设置为enable或者disable。true为disable，false为enable。
next_date	job运行的下一个日期。

示例

call dbms_job.submit(jobid, 'CREATE TABLE T1(A int)', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false);
call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456');
call dbms_job.broken(1,TRUE,now());

52.4.1.2. CHANGE 存储过程 ¶

此过程更改job中的属性信息。

语法格式

DBMS_JOB.CHANGE(
       job INTEGER,
       what TEXT,
       next_date TIMESTAMP,
       interva TEXT,
       instance INTEGER DEFAULT 0,
       force BOOLEAN DEFAULT FALSE);

参数说明

表 52.4.2 change 参数  ¶

参数	描述
job	由系统分配的job的ID。
what	job要运行的PL/SQL。
next_date	job运行的下一个日期。
interva	job运行的间隔时间。
instance	暂不支持，默认为0。
force	暂不支持，默认为FALSE。

示例

call dbms_job.change(1, 'CREATE TABLE T1(a INT);', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', 0, false);

52.4.1.3. INTERVAL 存储过程 ¶

此过程更改job中的间隔时间属性。

语法格式

DBMS_JOB.INTERVAL(
        job INTEGER,
        interva TEXT);

参数说明

表 52.4.3 interval参数  ¶

参数	描述
job	由系统分配的job的ID。
interva	job运行的间隔时间。

示例

call dbms_job.interval(1, 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10');

52.4.1.4. NEXT_DATE 存储过程 ¶

此过程更改job中的下次运行时间信息。

语法格式

DBMS_JOB.NEXT_DATE(
        job INTEGER,
        next_date TIMESTAMP);

参数说明

表 52.4.4 next_date参数  ¶

参数	描述
job	由系统分配的job的ID。
next_date	job运行的下一个日期。

示例

call dbms_job.next_date(1, now());

52.4.1.5. REMOVE 存储过程 ¶

此过程删除一个job。

语法格式

DBMS_JOB.REMOVE(
        job INTEGER);

参数说明

表 52.4.5 remove参数  ¶

参数	描述
job	由系统分配的job的ID。

示例

call dbms_job.remove(1);

52.4.1.6. RUN 存储过程 ¶

此过程运行一个job。

语法格式

DBMS_JOB.RUN(
        job INTEGER);

参数说明

表 52.4.6 RUN参数  ¶

参数	描述
job	由系统分配的job的ID。

示例

call dbms_job.submit(1, 'CREATE TABLE T1(A int)', now(), 'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false);
call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456');
call dbms_job.run(1);

52.4.1.7. SUBMIT 存储过程 ¶

此过程创建一个job。

语法格式

DBMS_JOB.SUBMIT(
        OUT job INTEGER,
        what text,
        next_date TIMESTAMP DEFAULT now(),
        interva text DEFAULT NULL,
        no_parse BOOLEAN DEFAULT FALSE,
        instance INTEGER DEFAULT 0,
        force BOOLEAN DEFAULT FALSE);

参数说明

表 52.4.7 SUBMIT参数  ¶

参数	描述
job	由系统分配的job的ID。
what	job要运行的PL/SQL。
next_date	job运行的下一个日期。
interva	job运行的间隔时间。
no_parse	暂不支持，默认为FALSE。
instance	暂不支持，默认为0。
force	暂不支持，默认为FALSE。

示例

declare
        jobid int
        BEGIN
        call DBMS_JOB.submit(jobid, 'CREATE TABLE T1(A int)', now(),
        'Freq=daily;BYHOUR=10;BYMINUTE=10;BYSECOND=10', false, 0, false);
        END;
        /

52.4.1.8. WHAT 存储过程 ¶

此过程更改job执行的行为信息。

语法格式

DBMS_JOB.WHAT(
        job INTEGER,
        what TEXT);

参数说明

表 52.4.8 what 参数  ¶

参数	描述
job	由系统分配的job的ID。
what	job要运行的PL/SQL。

示例

call dbms_job.what(1, 'CREATE TABLE T1(a INT);');

52.4.1.9. INSTANCE 存储过程 ¶

此过程增加job执行的连接串信息。

语法格式

DBMS_JOB.INSTANCE(
        job INTEGER,
        instance TEXT);

参数说明

表 52.4.9 instance 参数  ¶

参数	描述
job	由系统分配的job的ID。
instance	job要运行数据库的连接串。

示例

call dbms_job.instance(1, 'user=system dbname=test port=54321 password=123456');

52.4.2. DBMS_SCHEDULER模式下函数 ¶

DBMS_SCHEDULER 模式提供调度和管理作业任务的功能。该包提供了 DBMS_JOB 包的功能，并有所增强。

DBMS_SCHEDULER具有如下限制：

1. 需要创建kdb_schedule扩展。

2. 间隔时间采用日历表示法。

下表列出了DBMS_SCHEDULRE子程序并简要的表述了它们。

52.4.2.1. CREATE_PROGRAM 存储过程 ¶

创建一个job任务的程序。

语法格式

DBMS_SCHEDULER.CREATE_PROGRAM(
        program_name TEXT,
        program_type TEXT,
        program_action TEXT,
        acconnstr TEXT,
        acdbname TEXT,
        number_of_arguments INTEGER DEFAULT 0,
        enabled BOOLEAN DEFAULT FALSE,
        comments TEXT DEFAULT NULL);

参数说明

表 52.4.10 CREATE_PROGRAM 参数 :widths: 2 5  ¶

参数	描述
program_name	程序的名字。
program_type	程序的类型。有下列类 型：PLSQL_BLOCK、STORED_存储过程、SQL_SCRIPT、 EXECUTABLE、EXTERNAL_SCRIPT、BACKUP_SCRIPT
program_action	程序的动作。
acconnstr	数据库连接串。
acdbname	数据库名称。
number_of_arguments	程序动作的参数，暂不支持, 0为默认值。
enabled	程序的状态，true启动状态，false禁用状态。
comments	程序的注释信息。

示例

call DBMS_SCHEDULER.CREATE_PROGRAM('program1', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'test', 0, true, 'this is test program');

52.4.2.2. DROP_PROGRAM 存储过程 ¶

删除一个job任务的程序。

语法格式

DBMS_SCHEDULER.DROP_PROGRAM(
        program_name TEXT,
        force BOOLEAN DEFAULT FALSE);

参数说明

表 52.4.11 DROP_PROGRAM 参数  ¶

参数	描述
program_name	程序的名字。
force	暂不支持，默认值为false。

示例

call dbms_scheduler.drop_program('program1', true);

52.4.2.3. CREATE_SCHEDULE 存储过程 ¶

创建一个job任务的调度程序。

语法格式

DBMS_SCHEDULER.CREATE_SCHEDULE(
        schedule_name TEXT,
        start_date TIMESTAMP WITH TIME ZONE DEFAULT NULL,
        repeat_interval TEXT DEFAULT NULL,
        end_date TIMESTAMP WITH TIME ZONE DEFAULT NULL,
        comments TEXT DEFAULT NULL);

参数说明

表 52.4.12 CREATE_SCHEDULE 参数  ¶

参数	描述
schedule_name	调度程序的名字。
start_date	调度程序的开始时间
repeat_interval	调度程序的间隔时间
end_date	调度程序的结束时间
comment	调度程序的注释信息

示例

call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule1', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule');

52.4.2.4. DROP_SCHEDULE 存储过程 ¶

删除一个job任务的调度程序。

语法格式

DBMS_SCHEDULER.DROP_SCHEDULE(
        schedule_name TEXT,
        force BOOLEAN DEFAULT FALSE);

参数说明

表 52.4.13 DROP_SCHEDULE 参数  ¶

参数	描述
schedule_name	调度程序的名字。
force	暂不支持，默认值为false。

示例

call DBMS_SCHEDULER.DROP_SCHEDULE('schedule1', true);

52.4.2.5. EVALUATE_CALENDAR_STRING 存储过程 ¶

计算符合规则的下一个日期。

语法格式

DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING(
        calendar_string TEXT,
        start_date TIMESTAMP WITH TIME ZONE,
        return_date_after TIMESTAMP WITH TIME ZONE,
        OUT next_run_date TIMESTAMP WITH TIME ZONE);

参数说明

表 52.4.14 EVALUATE_CALENDAR_STRING 参数  ¶

参数	描述
calendar_string	调度规则。
start_date	开始时间。
return_date_after	最近一次的执行时间。
next_run_date	下一次运行的时间。返回参数

示例

declare
next_run_date timestamp;
begin DBMS_SCHEDULER.EVALUATE_CALENDAR_STRING('freq=yearly;interval=5;bymonth=10;
bymonthday=10;byhour=10;byminute=10;bysecond=10','','',next_run_date);
DBMS_OUTPUT.PUT_LINE(next_run_date);
end;

52.4.2.6. CREATE_JOB 存储过程 ¶

创建一个job任务。

语法格式

DBMS_SCHEDULER.CREATE_JOB(
        job_name TEXT,
        program_name TEXT,
        schedule_name TEXT,
        job_class TEXT DEFAULT 'Routine Maintenance',
        enabled BOOLEAN DEFAULT FALSE,
        auto_drop BOOLEAN DEFAULT TRUE,
        comments TEXT DEFAULT NULL,
        credentail_name TEXT DEFAULT NULL,
        destination_name TEXT DEFAULT NULL);

参数说明

表 52.4.15 CREATE_JOB 参数  ¶

参数	描述
job_name	job的名字。
program_name	程序的名字。
schedule_name	调度程序的名字。
job_class	job的类型，默认Routine Maintenance。
enabled	job的状态。true启用，false禁用
auto_drop	job完成后自动删除，暂不支持，默认true
comment	job的注释信息
credentail_name	暂不支持，默认为NULL
destination_name	暂不支持，默认为NULL

示例

call DBMS_SCHEDULER.CREATE_PROGRAM('program1', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'postgres', 0, true, 'this is test program');
call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule1', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule');
call DBMS_SCHEDULER.CREATE_JOB('job', 'program1', 'schedule1', 'Routine Maintenance', false, true, 'this is test job');

52.4.2.7. DROP_JOB 存储过程 ¶

删除一个job任务。

语法格式

DBMS_SCHEDULER.DROP_JOB(
        job_name TEXT,
        force BOOLEAN DEFAULT FALSE,
        defer BOOLEAN DEFAULT FALSE,
        commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR');

参数说明

表 52.4.16 DROP_JOB 参数  ¶

参数	描述
job_name	job的名字。
force	暂不支持，默认值为false。
defer	暂不支持，默认值为false。
commit_semantice	暂不支持，默认值为STOP_ON_FIRST_ERROR。

示例

call DBMS_SCHEDULER.DROP_JOB('job', false, false, 'STOP_ON_FIRST_ERROR');

52.4.2.8. RUN_JOB 存储过程 ¶

运行一个job任务。

语法格式

DBMS_SCHEDULER.RUN_JOB(
        job_name TEXT,
        use_current_session BOOLEAN DEFAULT TRUE);

参数说明

表 52.4.17 RUN_JOB 参数  ¶

参数	描述
job_name	job的名字。
use_current_session	暂不支持，默认值为true。

示例

call DBMS_SCHEDULER.CREATE_PROGRAM('program2', 'PLSQL_BLOCK', 'create table t2(A int)', 'user=system dbname=test port=54321 password=123456', 'postgres', 0, true, 'this is test program');
call DBMS_SCHEDULER.CREATE_SCHEDULE('schedule2', now(), 'Freq=daily;BYHOUR=10; BYMINUTE=10;BYSECOND=10', NULL, 'this is test schedule');
call DBMS_SCHEDULER.CREATE_JOB('job1', 'program2', 'schedule2', 'Routine Maintenance', false, true, 'this is test job');
call DBMS_SCHEDULER.RUN_JOB('job1', true);

52.4.2.9. DISABLE 存储过程 ¶

禁用一个job任务。

语法格式

DBMS_SCHEDULER.DISABLE(
        name TEXT,
        force BOOLEAN DEFAULT FALSE,
        commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR');

参数说明

表 52.4.18 DISABLE 参数  ¶

参数	描述
name	job的名字。
force	暂不支持，默认值为false。
commit_semantics	暂不支持，默认值为STOP_ON_FIRST_ERROR。

示例

call DBMS_SCHEDULER.DISABLE('job1', false, 'STOP_ON_FIRST_ERROR');

52.4.2.10. ENABLE 存储过程 ¶

启用一个job任务。

语法格式

DBMS_SCHEDULER.ENABLE(
        name TEXT,
        commit_semantics TEXT DEFAULT 'STOP_ON_FIRST_ERROR');

参数说明

表 52.4.19 ENABLE 参数  ¶

参数	描述
name	job的名字。
commit_semantics	暂不支持，默认值为STOP_ON_FIRST_ERROR。

示例

call DBMS_SCHEDULER.ENABLE('job1', 'STOP_ON_FIRST_ERROR');

52.4.3. 日历表示法 ¶

日历表示法是用来定义重复间隔的实现方法，DBMS_JOB和DBMS_SCHEDULER中的时间定义使用该语法。

语法格式

repeat_interval = regular_schedule
regular_schedule = frequency_clause
[";" interval_clause] [";" bymonth_clause] [";" byweekno_clause]
[";" byyearday_clause] [";" bydate_clause] [";" bymonthday_clause]
[";" byday_clause] [";" byhour_clause] [";" byminute_clause] [";" bysecond_clause]
frequency_clause = "FREQ" "=" ( predefined_frequency predefined_frequency =
"YEARLY" | "MONTHLY" | "WEEKLY" | "DAILY" | "HOURLY" | "MINUTELY" | "SECONDLY"
interval_clause = "INTERVAL" "=" intervalnum
   intervalnum = 1 through 99
bymonth_clause = "BYMONTH" "=" monthlist
   monthlist = month ( "," month)*
   month = numeric_month | char_month
   numeric_month = 1 | 2 | 3 ...  12
   char_month = "JAN" | "FEB" | "MAR" | "APR" | "MAY" | "JUN" | "JUL" | "AUG"
   | "SEP" | "OCT" | "NOV" | "DEC"
bymonthday_clause = "BYMONTHDAY" "=" monthday_list
   monthday_list = monthday ( "," monthday)*
   monthday = [minus] monthdaynum
   monthdaynum = 1 through 31
byhour_clause = "BYHOUR" "=" hour_list
   hour_list = hour ( "," hour)*
   hour = 0 through 23
byminute_clause = "BYMINUTE" "=" minute_list
   minute_list = minute ( "," minute)*
   minute = 0 through 59
byscond_clause = "BYSECOND" "=" second_list
   second_list = second ( "," second)*
   second = 0 through 59

参数说明

表 52.4.20 参数含义  ¶

参数	描述
FREQ	重复时间的类型。 这里有yearly、monthly、weekly、daily、hourly、minutely
INTERVAL	重复的频率，默认值是1。
BYMONTH	指定月份。
BYMONTHDAY	指定一月中的某一天。
BYHOUR	指定一天中的某一个小时。
BYBYMINTUE	指定一个小时中的秒一分。
BYSECOND	指定一分钟内的某一秒。

示例

每天早上10点

  FREQ=DAILY;BYHOUR=10;BYMINUTE=0;BYSECOND=0;

每个隔7天早上10点

  FREQ=DAILY;INTERVAL=7;BYHOUR=10;BYMINUTE=0;BYSECOND=0;

每年10月1号早上10点

FREQ=YEARLY;BYMONTH=10;BYMONTHDAY=1;BYHOUR=10;BYMINUTE=0;BYSECOND=0;

52.5. 插件kdb_schedule卸载方法 ¶

修改 kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。

示例：

shared_preload_libraries = ''

52.6. 插件kdb_schedule升级方法 ¶

kdb_schedule扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

53. kdb_tinyint ¶

53.1. 插件kdb_tinyint简介 ¶

插件kdb_tinyint是初始化内置，基本类型，支持tinyint类型。

• 插件名为 kdb_tinyint

• 插件版本 V1.0

53.2. 插件kdb_tinyint加载方式 ¶

默认已经创建，如果没有创建，需要在命令行执行create extension kdb_tinyint;

示例：

create extension kdb_tinyint;

53.3. 插件kdb_tinyint的参数配置 ¶

无需配置任何参数。

53.4. 插件kdb_tinyint的使用方法 ¶

加载插件kdb_tinyint后，按照如下方式使用相应功能。

53.4.1. conversion functions support ¶

支持tinyint类型和数值及字符类型之间转换。

语法

create cast (int4 as tinyint) with function tinyint(int4) as assignment;
create cast (tinyint as int4) with function int4(tinyint) as implicit;
create cast (bool as tinyint) with function tinyint(bool) as assignment;
create cast (tinyint as bool) with function bool(tinyint) as assignment;
create cast (int2 as tinyint) with function tinyint(int2) as assignment;
create cast (tinyint as int2) with function int2(tinyint) as implicit;
create cast (int8 as tinyint) with function tinyint(int8) as assignment;
create cast (tinyint as int8) with function int8(tinyint) as implicit;
create cast (float4 as tinyint) with function tinyint(float4) as assignment;
create cast (tinyint as float4) with function float4(tinyint) as implicit;
create cast (float8 as tinyint) with function tinyint(float8) as assignment;
create cast (tinyint as float8) with function float8(tinyint) as implicit;
create cast (numeric as tinyint) with function tinyint(numeric) as assignment;
create cast (tinyint as numeric) with function tinyinttonumeric(tinyint) as implicit;
create cast (bpchar as tinyint) with function tinyint(bpchar) as implicit;
create cast (tinyint as bpchar) with function text(tinyint) as assignment;
create cast (varchar as tinyint) with function tinyint(varchar) as implicit;
create cast (tinyint as varchar) with function text(tinyint) as assignment;
create cast (bpcharbyte as tinyint) with function tinyint(bpcharbyte) as implicit;
create cast (tinyint as bpcharbyte) with function text(tinyint) as assignment;
create cast (varcharbyte as tinyint) with function tinyint(varcharbyte) as implicit;
create cast (tinyint as varcharbyte) with function text(tinyint) as assignment;
create cast (text as tinyint) with function tinyint(text) as implicit;
create cast (tinyint as text) with function text(tinyint) as implicit;

示例

select '127'::tinyint::int2 as result;
result
--------
127

select '127'::tinyint::int4 as result;
result
--------
127

select '127'::tinyint::int8 as result;
result
--------
127

53.4.2. operator functions support ¶

tinyint类型和tinyint、int2、int4、int8之间支持算术操作符+- * /和比较操作符=、<>、<、<=、>、>=操作。 支持tinyint类型和money之间*操作。

示例

select tinyint '8' + int2 '5' as result;
result
--------
13

select tinyint '8' - tinyint '5' as result;
result
--------
3

select tinyint '8' * tinyint '5' as result;
result
--------
40

select tinyint '8' / tinyint '5' as result;

53.4.3. index suppor ¶

tinyint类型支持btree、bitmap、hash、gin、brin类型索引。

示例

create table tinyint_ind(a tinyint);
CREATE TABLE

insert into tinyint_ind values(generate_series(-128, 127));
INSERT 0 256

create index btree_index on tinyint_ind using btree(a);
CREATE INDEX

53.4.4. mathematics functions support ¶

tinyint类型支持支持mod、abs、and、or、xor、shl、shr、not、um、up函数。

示例

select mod(20::tinyint,3);
mod
-----
2

53.5. 插件kdb_tinyint卸载方法 ¶

系统启动自带插件，无法卸载。

53.6. 插件kdb_tinyint升级方法 ¶

kdb_tinyint扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

54. kdb_utils_function ¶

54.1. 插件kdb_utils_function简介 ¶

kdb_utils_function是KingbaseES中的一个扩展插件，能够实现工具函数的功能，如：KingbaseES版本信息函数，若干字符串函数，若干xml函数以及行列转换函数等。

• 插件名为 kdb_utils_function

• 插件版本 V1.3

54.2. 插件kdb_utils_function加载方式 ¶

KingbaseES默认不加载kdb_utils_function扩展插件，用户可以使用如下命令手工加载。

示例：

create extension kdb_utils_function;

54.3. 插件kdb_utils_function配置参数 ¶

无需配置任何参数

54.4. 插件kdb_utils_function使用方法 ¶

在使用kdb_utils_function里提供的函数之前，我们需要将他添加到kingbase.conf文件的shared_preload_libraries中，并重启KingbaseES数据库，或者使用CREATE EXTENSION命令在使用时创建。

shared_preload_libraries = 'kdb_utils_function' # (change requires restart)

或者在ksql中使用：

CREATE EXTENSION kdb_utils_function; 语句在使用时创建。

54.4.1. 函数列表 ¶

表 表 54.4.1 列出了kdb_utils_function扩展所提供的函数。

表 54.4.1 扩展函数列表  ¶

插件名称	用途
appendchildxml(xml,text,xml)	参考 appendchildxml
appendchildxml(xml,text,xml,text[])	参考 appendchildxml
deletexml(xml,text)	参考 deletexml
deletexml(xml,text,text[])	参考 deletexml
existsnode(xml,text)	参考 existsnode
existsnode(xml,text,text[])	参考 existsnode
extractvalue(xml,text)	参考 extractvalue
extractvalue(xml,text,text[])	参考 extractvalue
get_kingbasees_version()	获取KingbaseES发生版本信息
insertchildxmlafter(xml,text,text,text)	参考 insertchildxmlafter
insertchildxmlafter(xml,text,text,text,text[])	参考 insertchildxmlafter
insertchildxmlafter(xml,text,text,xml)	参考 insertchildxmlafter
insertchildxmlafter(xml,text,text,xml,text[])	参考 insertchildxmlafter
insertchildxmlbefore(xml,text,text,text)	参考 insertchildxmlbefore
insertchildxmlbefore(xml,text,text,text,text[])	参考 insertchildxmlbefore
insertchildxmlbefore(xml,text,text,xml)	参考 insertchildxmlbefore
insertchildxmlbefore(xml,text,text,xml,text[])	参考 insertchildxmlbefore
insertchildxml(xml,text,text,text)	参考 insertchildxml
insertchildxml(xml,text,text,text,text[])	参考 insertchildxml
insertchildxml(xml,text,text,xml)	参考 insertchildxml
insertchildxml(xml,text,text,xml,text[])	参考 insertchildxml
insertxmlafter(xml,text,text,text)	参考 insertxmlafter
insertxmlafter(xml,text,text,text,text[])	参考 insertxmlafter
insertxmlafter(xml,text,text,xml)	参考 insertxmlafter
insertxmlafter(xml,text,text,xml,text[])	参考 insertxmlafter
insertxmlbefore(xml,text,text,text)	参考 insertxmlbefore
insertxmlbefore(xml,text,text,text,text[])	参考 insertxmlbefore
insertxmlbefore(xml,text,text,xml)	参考 insertxmlbefore
insertxmlbefore(xml,text,text,xml,text[])	参考 insertxmlbefore
updatexml(xml,text,text)	参考 updatexml
updatexml(xml,text,text,text[])	参考 updatexml
updatexml(xml,text,xml)	参考 updatexml
lnnvl(boolean)	参考 LNNVL
max(character varying)	参考 聚集函数
min(character varying)	参考 聚集函数
nanvl(double precision,double precision)	NaN值判断函数，返回第一个非NaN值的参数值
nanvl(numeric,numeric)	NaN值判断函数，返回第一个非NaN值的参数值
nanvl(real,real)	NaN值判断函数，返回第一个非NaN值的参数值
group_concat(anyarray,text)	参考 GROUP_CONCAT
nlssort(text,text)	参考 nlssort
wm_concat(text)	参考 聚集函数
varchar_larger(character varying,character varying)	参考 字符串函数和操作符
varchar_smaller(character varying,character varying)	参考 字符串函数和操作符

示例

-- 安装kdb_utils_function

CREATE EXTENSION kdb_utils_function;

-- 使用get_kingbasees_version()

select get_kingbasees_version();
                  get_kingbasees_version
------------------------------------------------------------------
KingBaseES V8.0. (c) Kingbase Corporation. All rights reserved.
(1 row)

54.5. 插件backtrace卸载方法 ¶

修改kingbase.conf 文件中 shared_preload_libraries 参数后重启数据库。或者使用DROP EXTENSION命令进行卸载。

示例：

DROP EXTENSION kdb_utils_function;

55. kdb_xmltype ¶

55.1. 插件kdb_xmltype简介： ¶

kdb_xmltype是KingbaseES的一个扩展插件，主要用于定义Oracle兼容XMLTYPE类型和相关的操作函数。

• 插件名为 kdb_xmltype

• 插件版本 V1.0.0

55.2. 插件kdb_xmltype加载方式: ¶

KingbaseES默认不加载kdb_xmltype扩展插件，请使用以下命令加载插件和创建扩展：

CREATE EXTENSION kdb_xmltype;

55.3. 插件kdb_xmltype的参数配置: ¶

无需配置任何参数

55.4. 插件kdb_xmltype的使用方法： ¶

55.4.1. XMLTYPE类型： ¶

kdb_xmltype插件定义了Oracle兼容的XMLTYPE类型，该类型是一个对象类型。XMLTYPE类型位于sys模式下，为数据库系统依赖，禁止删除。

XMLTYPE类型可以用于定义表和视图的列类型，也可用于定义函数或者过程的参数和返回值类型。XMLTYPE类型与已有xml类型兼容，支持所有xml类型处理函数。XMLTYPE类型支持XML格式检查，对输入的非良好格式将报错。

CREATE OR REPLACE TYPE xmltype AS OBJECT (
  xml_data xml,
  constructor function xmltype(self in out xmltype) return self as result,
  constructor function xmltype(xml_string in text) return self as result
);

XMLTYPE函数的典型用法举例如下：

CREATE TABLE tab_xml (a int, b xmltype);
INSERT INTO tab_xml VALUES (1, '<a><b>1</b><b>2</b></a>');
INSERT INTO tab_xml VALUES (2, xmltype('<a><b>3</b><c>4</c></a>'));
SELECT * FROM tab_xml;
DROP TABLE tab_xml;

55.4.1.1. 输入输出： ¶

XMLTYPE类型的输入输出函数与record类型的输入输出函数有相同的参数。

不同于record类型，XMLTYPE类型的输入函数的第一个参数只能接受XML字符串（例如：'<a>1</a>'），而不能接受用小括号包围的XML字符串（例如： '(<a>1</a>)'），后一情况被视为不合格的XML字符串。

对于不合格的XML字符串，xml解析器的行为受GUC参数 xmloption 控制。当 xmloption=content 时（默认值），xml解析器将不合格的输入字符串当作XML元素内容；当 xmloption=document 时，XML解析器对不合格的输入字符串报错处理。对于空字符串或空值NULL，均会被XML解析器作为NULL处理，生成的实例为NULL。

不同于record类型，XMLTYPE类型的输出函数返回结果是XML字符串，而不是用小括号()包围的XML字符串。

XMLTYPE类型的构造函数，接受一个text类型的XML字符串，返回一个XMLTYPE类型实例。构造函数对输入参数的解析规则与XMLTYPE类型的输入函数完全相同。

55.4.1.2. 数据存储： ¶

XMLTYPE类型属于一种内置的对象类型，它的数据存储格式与record类型相同。

55.4.1.3. 操作符： ¶

XMLTYPE类型不支持任何操作符，这一点与内置xml类型相同。

55.4.1.4. 类型转换： ¶

XMLTYPE类型支持与内置xml类型之间的双向隐式转换，支持与text/bpchar/varchar类型之间的双向隐式赋值转换。

55.4.1.5. 索引： ¶

不支持在XMLTYPE类型列上直接创建列索引，但可以使用xml函数extractvalue创建基于函数的索引。

55.4.1.6. xml函数： ¶

基于XMLTYPE类型与内置xml类型之间的双向隐式转换规则，所有接受内置xml类型为参数的函数，也均可接受XMLTYPE类型的参数。

55.4.2. XMLSEQUENCE函数： ¶

kdb_xmltype插件定义了Oracle兼容的XMLSEQUENCE函数，该函数接受一个xml类型的XML实例，返回一个包含所有顶层XML节点的可变数组。

XMLSEQUENCE(xml_instance xml) returns xmlsequencetype

XMLSEQUENCE函数、函数返回值的类型都位于sys模式下。返回值 xmlsequencetype 类型是XMLTYPE类型的可变数组。 当输入数据为NULL时，函数返回0行，而不是空值。

XMLSEQUENCE函数的典型用法是和TABLE函数联合使用，用法举例：

CREATE TABLE tab_xml (a int, b xml);
INSERT INTO tab_xml VALUES (1, '<a><b>1</b><b>2</b></a>');
INSERT INTO tab_xml VALUES (2, xml ('<a><b>3</b><c>4</c></a>'));
SELECT t.* FROM tab_xml, table(xmlsequence(extract(b, '/a/*'))) AS t;
DROP TABLE tab_xml;

55.4.3. VALUE函数： ¶

kdb_xmltype插件定义了Oracle兼容的VALUE函数，该函数接受一个范围表别名作为参数，返回record类型的对象实例。对象实例的类型与表的record类型相同。

CREATE OR REPLACE FUNCTION value(x record) RETURNS record
CREATE OR REPLACE FUNCTION value(x xmltype) RETURNS xmltype

VALUE函数有两个重载版本，当输入数据为空值NULL时，这两个版本函数均返回空值NULL。

VALUE函数的典型用法举例：

CREATE TYPE person_t AS OBJECT (name varchar2(100), ssn number);
CREATE TABLE persons OF person_t;
INSERT INTO persons VALUES (person_t('Bob', 1234));
INSERT INTO persons VALUES (person_t('Joe', 32456));
INSERT INTO persons VALUES (person_t('Tim', 5678));
SELECT value(t) FROM persons t;
DROP TABLE persons;
DROP TYPE person_t;

CREATE TABLE subjects OF xmltype;
INSERT INTO subjects VALUES ('<doc><lesson>math</lesson></doc>');
INSERT INTO subjects VALUES ('<doc><lesson>english</lesson></doc>');
INSERT INTO subjects VALUES ('<doc><lesson>chinese</lesson></doc>');
SELECT value(t) FROM subjects t;
DROP TABLE subjects;

55.5. 插件kdb_xmltype卸载方法： ¶

请使用以下命令卸载kdb_xmltype插件。

示例：

DROP EXTENSION kdb_xmltype;

55.6. 插件kdb_xmltype升级方法： ¶

kdb_xmltype扩展插件随着KingbaseES安装包一并升级。通常情况下用户无须单独升级插件。

56. kingbase_fdw ¶

56.1. 插件kingbase_fdw简介 ¶

kingbase_fdw模块提供了外部数据包装器kingbase_fdw，它可以被用来访问存储在外部KingbaseES服务器中的数据。

这个模块提供的功能大体上覆盖了较老的dblink模块的功能。但是kingbase_fdw提供了更透明且更兼容标准的语法来访问远程表，并且可以在很多情况下给出更好的性能。

要使用kingbase_fdw来为远程访问做准备：

• 使用CREATE EXTENSION来安装kingbase_fdw扩展。

• 使用CREATE SERVER创建一个外部服务器对象，它用来表示你想连接的每一个远程数据库。指定除了user和password之外的连接信息作为该服务器对象的选项。

• 使用CREATE USER MAPPING创建一个用户映射，每一个用户映射都代表你想允许一个数据库用户访问一个外部服务器。指定远程用户名和口令作为用户映射的user和password选项。

• 为每一个你想访问的远程表使用CREATE FOREIGN TABLE或者IMPORT FOREIGN SCHEMA创建一个外部表。外部表的列必须匹配被引用的远程表。但是，如果你在外部表对象的选项中指定了正确的远程名称，你可以使用不同于远程表的表名和/或列名。

现在只需要从一个外部表SELECT来访问存储在它的底层的远程表中的数据。也可以使用INSERT、UPDATE或DELETE修改远程表（当然，在用户映射中已经指定的远程用户必须具有做这些事情的权限）。

注意当前kingbase_fdw缺少对于带ON CONFLICT DO UPDATE子句的INSERT语句的支持。不过，它支持ON CONFLICT DO NOTHING子句，已提供的唯一索引推断说明会被省略。 另请注意kingbase_fdw支持 UPDATE 语句在分区表上执行的行移动调用，但是它目前不处理这样的情况：选择将移动行插入到的远程分区也是稍后将更新的UPDATE目标分区。

通常推荐一个外部表的列被声明为与被引用的远程表列完全相同的数据类型和排序规则（如果可用）。尽管kingbase_fdw目前已经能够容忍在需要时执行数据类型转换，但是当类型或排序规则不匹配时可能会发生奇怪的语义异常，因为远程服务器解释WHERE子句时可能会与本地服务器有所不同。

注意一个外部表可以被声明比底层的远程表较少的列，或者使用一种不同的列序。与远程表的列匹配是通过名字而不是位置进行的。

• 插件名为 kingbase_fdw

• 插件版本 V1.0.0

56.2. 插件kingbase_fdw的加载方式 ¶

在ksql中运行：

CREATE EXTENSION kingbase_fdw;

56.3. 插件kingbase_fdw的参数配置 ¶

56.3.1. 连接选项 ¶

一个使用kingbase_fdw外部数据包装器的外部服务器可以使用和libpq在连接字符串中能接受的选项，如对象名称选项所述，不过不允许这些选项：

• user和password（应该在用户映射中指定这些）

• client_encoding（这是自动从本地服务器编码设置）

• fallback_application_name（总是设置为kingbase_fdw）

只有超级用户可以在不经过口令认证的情况下连接到外部服务器，因此应总是为属于非超级用户的用户映射指定password选项。

56.3.2. 对象名称选项 ¶

这些选项可以被用来控制使用在被发送到远程KingbaseES服务器的 SQL 语句中使用的名称。

当一个外部表被使用不同于底层远程表的名称创建时，就需要这些选项。

• schema_name

  这个选项给出用在远程服务器之上的外部表的模式名称，它可以为一个外部表指定。如果这个选项被忽略，该外部表的模式名称将被使用。

• table_name

  这个选项给出用在远程服务器上的外部表给出表名，它可以为一个外部表指定。如果这个选项被忽略，该外部表的名字将被使用。

• column_name

  这个选项给出用在远程服务器上列的列名，它可以为一个外部表的一个列指定。如果这个选项被忽略，该列的名字将被使用。

56.3.3. 代价估计选项 ¶

kingbase_fdw通过在远程服务器上执行查询来检索远程数据，因此理想的扫描一个外部表的估计代价应该是在远程服务器上完成它的花销，外加一些通信开销。得到这样一个估计的最可靠的方法是询问远程服务器并加上一些通信开销 — 但是对于简单查询，不值得为获得一个代价估计而额外使用一次远程查询。因此kingbase_fdw提供了下列选项来控制如何完成代价估计：

• use_remote_estimate

  这个选项控制kingbase_fdw是否发出EXPLAIN命令来获得代价估计，它可以为一个外部表或一个外部服务器指定。一个外部表的设置会覆盖它的服务器的任何设置，但是只用于这个表。默认值是false。

• fdw_startup_cost

  这个选项是一个要被加到那个服务器上所有外部表扫描的估计启动代价的数字值。这表示建立一个连接、在远端解析和规查询的额外负荷等。默认值是100。

• fdw_tuple_cost

  这个选项是一个数字值，它被用作表示某个服务器上外部表扫描时，每元组额外代价，它可以为某个外部服务器单独指定。表示在服务器之间数据传输的额外负荷。用户可以增加或减少这个数来反映到远程服务器更高或更低的网络延迟。默认值是 0.01。

当use_remote_estimate为真时，kingbase_fdw从远程服务器获得行计数和代价估计，然后在代价估计上加上fdw_startup_cost和fdw_tuple_cost。当use_remote_estimate为假时，kingbase_fdw执行本地行计数和代价估计，并且接着在代价估计上加上fdw_startup_cost 和fdw_tuple_cost。这种本地估计不会很准确，除非有远程表统计数据的本地拷贝可用。在外部表上运行ANALYZE是更新本地统计数据的方法，这将执行远程表的一次扫描并接着计算和存储统计数据，就好像表在本地一样。保留本地统计数据可能是一种有用的方法来减少一个远程表的预查询规划负荷 — 但是如果远程表被频繁更新，本地统计数据将很快就被废弃。

56.3.4. 远程执行选项 ¶

默认情况下，只有使用了内建操作符和函数的WHERE子句才会被考虑在远程服务器上执行。

涉及非内建函数的子句将会在取完行后在本地进行检查。如果这类函数在远程服务器上可用并且可以用来产生和本地执行时一样的结果，则可以通过将这种WHERE子句发送到远程执行来提高性能。可以用下面的选项控制这种行为：

• extensions

  这个选项是一个用逗号分隔的已安装的KingbaseES扩展名称列表，这些扩展在本地和远程服务器上具有兼容的版本。属于一个该列表中扩展的 immutable 函数和操作符将被考虑转移到远程服务器上执行。这个选项只能为外部服务器指定，无法逐个表指定。

  在使用extensions选项时，用户应该负责确保列出的扩展在本地和远程服务器上都存在且保持一致。否则，远程查询可能失败或者行为异常。

• fetch_size

  这个选项指定在每次获取行的操作中kingbase_fdw应该得到的行数。可以为一个外部表或者外部服务器指定这个选项。在表上指定的选项将会覆盖在服务器级别上指定的选项。默认值为100。

56.3.5. 可更新性选项 ¶

默认情况下，所有使用kingbase_fdw的外部表都被假定是可更新的。这可以使用下列选项覆盖：

• updatable

  这个选项控制kingbase_fdw是否允许外部表被使用INSERT、UPDATE和DELETE命令更新。它可以为一个外部表或一个外部服务器指定。一个表级选项会覆盖一个服务器级选项。默认值是true。

  当然，如果远程表实际上并非可更新的，将产生一个错误。这个选项的使用主要是允许在不查询远程服务器的情况下在本地抛出错误。但是要注意information_schema视图会根据这个选项的设置报告一个kingbase_fdw外部表是可更新的（或者不可更新），而不需要远程服务器的任何检查。

56.3.6. 导入选项 ¶

kingbase_fdw能使用IMPORT FOREIGN SCHEMA导入外部表定义。这个命令会在本地服务器上创建外部表定义，这个定义能匹配存在于远程服务器上的表或者视图。如果要被导入的远程表有用户自定义数据类型的列，本地服务器上也必须具有相同名称的兼容类型。

导入行为可以用下列选项自定义（在IMPORT FOREIGN SCHEMA命令中给出）：

• import_collate

  这个选项控制是否在从外部服务器导入的外部表定义中包括列的COLLATE选项。默认是true。如果远程服务器具有和本地服务器不同的排序规则名集合，可能需要关闭这个选项，在不同的操作系统上运行时很可能就是这样。

• import_default

  这个选项控制是否在从外部服务器导入的外部表定义中包括列的DEFAULT表达式。默认是false。如果启用这个选项，要当心在远程服务器和本地服务器上计算表达式的方式不同，nextval()常会导致这类问题。如果导入的默认值表达式使用了一个本地不存在的函数或者操作符，IMPORT将整个失败。

• import_not_null

  这个选项控制是否在从外部服务器导入的外部表定义中包括列的NOT NULL约束。默认是true。

注意除NOT NULL之外的约束将不会从远程表中导入。虽然KingbaseES确实支持外部表上的CHECK约束，但不会自动导入它们，因为存在本地和远程服务器计算约束表达式方式不同的风险。CHECK约束中的任何这类不一致都可能导致查询优化中很难检测的错误。因此，如果你希望导入CHECK约束，你必须手工来做，并且你应该仔细地验证每一个这种约束的语义。有关处理外部表上CHECK约束的更多细节，请见CREATE FOREIGN TABLE。

自动排除作为其他表的分区的表或外部表。分区表被导入，除非它们是其他表的分区。 由于所有数据都可以通过作为分区层次根的分区表来访问， 所以这种方法应该允许访问所有数据而不创建额外的对象。

56.4. 插件kingbase_fdw的使用 ¶

这里是一个用kingbase_fdw创建外部表的例子。首先安装该扩展：

CREATE EXTENSION kingbase_fdw;

然后使用CREATE SERVER创建一个外部服务器。在这个例子中我们希望连接到一个位于主机192.83.123.89上并且监听5432端口的KingbaseES服务器。在该远程服务器上要连接的数据库名为foreign_db：

CREATE SERVER foreign_server
       FOREIGN DATA WRAPPER kingbase_fdw
       OPTIONS (host '192.83.123.89', port '5432', dbname 'foreign_db');

需要用CREATE USER MAPPING定义一个用户映射来标识在远程服务器上使用哪个角色：

CREATE USER MAPPING FOR local_user
       SERVER foreign_server
       OPTIONS (user 'foreign_user', password 'password');

现在就可以使用CREATE FOREIGN TABLE创建外部表了。在这个例子中我们希望访问远程服务器上名为some_schema.some_table的表。它的本地名称是foreign_table：

CREATE FOREIGN TABLE foreign_table (
       id integer NOT NULL,
       data text
)
       SERVER foreign_server
       OPTIONS (schema_name 'some_schema', table_name 'some_table');

CREATE FOREIGN TABLE中声明的列数据类型和其他性质必须要匹配实际的远程表。列名也必须匹配，不过也可以为个别列附上column_name选项以表示它们在远程服务器上对应哪个列。在很多情况中，要手工构造外部表定义，使用IMPORT FOREIGN SCHEMA会更好。

56.5. 插件kingbase_fdw的卸载 ¶

在ksql中运行：

DROP EXTENSION kingbase_fdw;

56.6. 插件kingbase_fdw的升级 ¶

kingbase_fdw扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级些插件。

57. kingbase_version ¶

57.1. 插件kingbase_version简介 ¶

kingbase_version支持查询KingbaseES的构建版本号。

• 插件名为kingbase_version

• 插件版本 V1.0

57.2. 插件kingbase_version加载方式 ¶

该插件为内置加载。

57.3. 插件kingbase_version参数配置 ¶

无需配置任何参数。

57.4. 插件kingbase_version使用方法 ¶

57.4.1. bulid_version ¶

获取kingbase的构建版本号。

语法

bulid_version( ) RETURNS text。

示例

 TEST=# select build_version();
 build_version
---------------
 4c5e415
 (1 行记录)

57.5. 插件bulid_version卸载方法 ¶

无

57.6. 插件bulid_version升级方法 ¶

bulid_version扩展插件通常随KingbaseES安装包一并升级。通常情况下用户无法单独升级插件。

58. ktrack ¶

58.1. 插件ktrack简介 ¶

ktrack是KingbaseES的一个扩展插件，作为块级别增量备份引擎为物理备份工具提供基础支持。

启用插件后，插件功能自动运行，并提供SQL函数供查询使用。

• 插件名为 ktrack

• 插件版本 V2.2

58.2. 插件ktrack加载方式 ¶

将 ktrack 追加到 kingbase.conf 的 shared_preload_libraries 配置项中，同时新增一行设置 ktrack.map_size，重启数据库后执行 create extension ktrack; 语句。

shared_preload_libraries = 'ktrack'
ktrack.map_size = 1024

58.3. 插件ktrack的参数配置 ¶

ktrack 使用 ktrack.map_size 设置的值设定存储块变化信息的文件的大小（单位为 MB），最大为 1024；改变该值需要重启数据库，之前存储的块变化信息会丢失（该值不变时重启数据库信息不会丢失）。

58.4. 插件ktrack的使用方法 ¶

启用 ktrack 插件后，可使用如下四个SQL函数做查询。

• ktrack_version() : 返回 ktrack 的版本信息

• ktrack_init_lsn() : 返回 ktrack 开始记录块变化信息的LSN

• ktrack_get_pagemapset() : 返回自指定LSN以来发生改变的块信息

• ktrack_get_change_stat() : 返回自指定LSN以来发生改变的块信息的统计信息

 select ktrack_version();
ktrack_version
----------------
2.2
(1 row)

 select ktrack_init_lsn();
ktrack_init_lsn
-----------------
0/3000028
(1 row)

 select path, pagecount, pagemap from ktrack_get_pagemapset('0/2417EBA8');
      path       | pagecount |         pagemap
------------------+-----------+--------------------------
base/15900/49171 |         1 | \x0100000000000000000000
(1 row)

 select * from ktrack_get_change_stat('0/2417EBA8');
files | pages |        size, MB
-------+-------+------------------------
    1 |     1 | 0.03125000000000000000
(1 row)

58.5. 插件ktrack卸载方法 ¶

连接到数据库执行 DROP 插件操作，删除 kingbase.conf 文件中 shared_preload_libraries 内的 ktrack 参数，删除 ktrack.map_size 设置，重启数据库。

drop extension ktrack;

shared_preload_libraries = ''

58.6. 插件ktrack升级方法 ¶

ktrack扩展插件通常随着KingbaseES安装包一并升级。通常情况下用户无须单独升级该插件。