华为云用户手册

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 --创建存储过程dynamic_proc CREATE OR REPLACE PROCEDURE dynamic_proc AS staff_id NUMBER(6) := 200; first_name VARCHAR2(20); salary NUMBER(8,2); BEGIN --执行匿名块 EXECUTE IMMEDIATE 'begin select first_name, salary into :first_name, :salary from staffs where staff_id= :dno; end;' USING OUT first_name, OUT salary, IN staff_id; dbms_output.put_line(first_name|| ' ' || salary); END; / --调用存储过程 CALL dynamic_proc(); --删除存储过程 DROP PROCEDURE dynamic_proc;

语法 语法请参见图1。 图1 call_anonymous_block::= using_clause子句的语法参见图2。 图2 using_clause-4 对以上语法格式的解释如下： 匿名块程序实施部分，以BEGIN语句开始，以END语句停顿，以一个分号结束。 USING [IN|OUT|IN OUT] bind_argument，用于指定存放传递给存储过程参数值的变量。bind_argument前的修饰符与对应参数的修饰符一致。 匿名块中间的输入输出参数使用占位符来指明，要求占位符个数与参数个数相同，并且占位符所对应参数的顺序和USING中参数的顺序一致。 目前 GaussDB (DWS)在动态语句调用匿名块时，EXCEPTION语句中暂不支持使用占位符进行输入输出参数的传递。

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 --创建存储过程proc_add。 CREATE OR REPLACE PROCEDURE proc_add ( param1 in INTEGER, param2 out INTEGER, param3 in INTEGER ) AS BEGIN param2:= param1 + param3; END; / DECLARE input1 INTEGER:=1; input2 INTEGER:=2; statement VARCHAR2(200); param2 INTEGER; BEGIN --声明调用语句 statement := 'call proc_add(:col_1, :col_2, :col_3)'; --执行语句 EXECUTE IMMEDIATE statement USING IN input1, OUT param2, IN input2; dbms_output.put_line('result is: '||to_char(param2)); END; / --删除存储过程 DROP PROCEDURE proc_add;

语法 语法请参见图1。 图1 call_procedure::= using_clause子句的语法参见图2。 图2 using_clause-3 对以上语法格式的解释如下： CALL procedure_name，调用存储过程。 [:placeholder1，:placeholder2，…]，存储过程参数占位符列表。占位符个数与参数个数相同。 USING [IN|OUT|IN OUT] bind_argument，用于指定存放传递给存储过程参数值的变量。bind_argument前的修饰符与对应参数的修饰符一致。

示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 --创建表 CREATE TABLE sections_t1 ( section NUMBER(4) , section_name VARCHAR2(30), manager_id NUMBER(6), place_id NUMBER(4) ) DISTRIBUTE BY hash(manager_id); --声明变量 DECLARE section NUMBER(4) := 280; section_name VARCHAR2(30) := 'Info support'; manager_id NUMBER(6) := 103; place_id NUMBER(4) := 1400; new_colname VARCHAR2(10) := 'sec_name'; BEGIN --执行查询 EXECUTE IMMEDIATE 'insert into sections_t1 values(:1, :2, :3, :4)' USING section, section_name, manager_id,place_id; --执行查询（重复占位符） EXECUTE IMMEDIATE 'insert into sections_t1 values(:1, :2, :3, :1)' USING section, section_name, manager_id; --执行ALTER语句（建议采用“||”拼接数据库对象构造DDL语句） EXECUTE IMMEDIATE 'alter table sections_t1 rename section_name to ' || new_colname; END; / --查询数据 SELECT * FROM sections_t1; --删除表 DROP TABLE sections_t1;

语法 语法请参见图1。 图1 noselect::= using_clause子句的语法参见图2。 图2 using_clause-2 对以上语法格式的解释如下： USING IN bind_argument用于指定存放传递给动态SQL值的变量，在dynamic_noselect_string中存在占位符时使用，即动态SQL语句执行时，bind_argument将替换相对应的占位符。要注意的是，bind_argument只能是值、变量或表达式，不能是表名、列名、数据类型等数据库对象。如果存储过程需要通过声明参数传递数据库对象来构造动态SQL语句（常见于执行DDL语句时），建议采用连接运算符“||”拼接dynamic_select_clause。另外，动态语句允许出现重复的占位符，相同占位符只能与唯一一个bind_argument按位置一一对应。

OPEN FOR 动态查询语句还可以使用OPEN FOR打开动态游标来执行。 语法参见图3。 图3 open_for::= 参数说明： cursor_name：要打开的游标名。 dynamic_string：动态查询语句。 USING value：在dynamic_string中存在占位符时使用。 游标的使用请参考GaussDB(DWS)存储过程游标。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 DECLARE name VARCHAR2(20); phone_number VARCHAR2(20); salary NUMBER(8,2); sqlstr VARCHAR2(1024); TYPE app_ref_cur_type IS REF CURSOR; --定义游标类型 my_cur app_ref_cur_type; --定义游标变量 BEGIN sqlstr := 'select first_name,phone_number,salary from staffs where section_id = :1'; OPEN my_cur FOR sqlstr USING '30'; --打开游标, using是可选的 FETCH my_cur INTO name, phone_number, salary; --获取数据 WHILE my_cur%FOUND LOOP dbms_output.put_line(name||'#'||phone_number||'#'||salary); FETCH my_cur INTO name, phone_number, salary; END LOOP; CLOSE my_cur; --关闭游标 END; /

EXECUTE IMMEDIATE 语法图请参见图1。 图1 EXECUTE IMMEDIATE dynamic_select_clause::= using_clause子句的语法图参见图2。 图2 using_clause-1 对以上语法格式的解释如下： define_variable，用于指定存放单行查询结果的变量。 USING IN bind_argument，用于指定存放传递给动态SQL值的变量，即在dynamic_select_string中存在占位符时使用。 USING OUT bind_argument，用于指定存放动态SQL返回值的变量。 查询语句中，into和out不能同时存在； 占位符命名以“:”开始，后面可跟数字、字符或字符串，与USING子句的bind_argument一一对应； bind_argument只能是值、变量或表达式，不能是表名、列名、数据类型等数据库对象，即不支持使用bind_argument为动态SQL语句传递模式对象。如果存储过程需要通过声明参数传递数据库对象来构造动态SQL语句（常见于执行DDL语句时），建议采用连接运算符“||”拼接dynamic_select_clause； 动态PL/SQL块允许出现重复的占位符，即相同占位符只能与USING子句的一个bind_argument按位置对应。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 --从动态语句检索值（INTO 子句）： DECLARE staff_count VARCHAR2(20); BEGIN EXECUTE IMMEDIATE 'select count(*) from staffs' INTO staff_count; dbms_output.put_line(staff_count); END; / --传递并检索值（INTO子句用在USING子句前）： CREATE OR REPLACE PROCEDURE dynamic_proc AS staff_id NUMBER(6) := 200; first_name VARCHAR2(20); salary NUMBER(8,2); BEGIN EXECUTE IMMEDIATE 'select first_name, salary from staffs where staff_id = :1' INTO first_name, salary USING IN staff_id; dbms_output.put_line(first_name || ' ' || salary); END; / --调用存储过程 CALL dynamic_proc(); --删除存储过程 DROP PROCEDURE dynamic_proc;

调用语句 语法 调用一个语句的语法请参见图3。 图3 call_clause::= 对以上语法格式的解释如下： procedure_name，为存储过程名。 parameter，为存储过程的参数，可以没有或者有多个参数。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 --创建存储过程proc_staffs CREATE OR REPLACE PROCEDURE proc_staffs ( section NUMBER(6), salary_sum out NUMBER(8,2), staffs_count out INTEGER ) IS BEGIN SELECT sum(salary), count(*) INTO salary_sum, staffs_count FROM staffs where section_id = section; END; / --创建存储过程proc_return. CREATE OR REPLACE PROCEDURE proc_return AS v_num NUMBER(8,2); v_sum INTEGER; BEGIN proc_staffs(30, v_sum, v_num); --调用语句 dbms_output.put_line(v_sum||'#'||v_num); RETURN; --返回语句 END; / --调用存储过程proc_return. CALL proc_return(); --清除存储过程 DROP PROCEDURE proc_staffs; DROP PROCEDURE proc_return; --创建函数func_return. CREATE OR REPLACE FUNCTION func_return returns void language plpgsql AS $$ DECLARE v_num INTEGER := 1; BEGIN dbms_output.put_line(v_num); RETURN; --返回语句 END $$; -- 调用函数func_return CALL func_return(); 1 -- 清除函数 DROP FUNCTION func_return;

定义变量 介绍PL/SQL中变量的声明，以及该变量在代码中的作用域。 变量声明 变量声明语法请参见图1。 图1 declare_variable::= 对以上语法格式的解释如下： variable_name，为变量名。 type，为变量类型。 value，是该变量的初始值（如果不给定初始值，则初始为NULL）。value也可以是表达式。 示例 1 2 3 4 5 6 DECLARE emp_id INTEGER := 7788; --定义变量并赋值 BEGIN emp_id := 5*7784; --变量赋值 END; / 变量类型除了支持基本类型，还可使用%TYPE和%ROWTYPE去声明一些与其他表字段或表结构本身相关的变量。 %TYPE属性 %TYPE主要用于声明某个与其他变量类型（例如，表中某列的类型）相同的变量。假如想定义一个my_name变量，它的变量类型与employee的firstname类型相同，可使用如下定义： my_name employee.firstname%TYPE 这样定义可以带来两个好处，首先，不用预先知道employee 表的firstname类型具体是什么。其次，即使之后firstname类型有了变化，也不需要再次修改my_name的类型。 %ROWTYPE属性 %ROWTYPE属性主要用于对一组数据的类型声明，用于存储表中的一行数据，或从游标匹配的结果。假如需要一组数据，该组数据的字段名称与字段类型都与employee表相同。可以通过如下定义： my_employee employee%ROWTYPE 多个CN的环境下，存储过程中无法声明临时表的%ROWTYPE及%TYPE属性。因为临时表仅在当前session有效，在编译阶段其他CN无法看到当前CN的临时表。故多个CN的环境下，会提示该临时表不存在。 变量作用域 变量的作用域表示变量在代码块中的可访问性和可用性。只有在它的作用域内，变量才有效。 变量必须在declare部分声明，即必须建立BEGIN-END块。块结构也强制变量必须先声明后使用，即变量在过程内有不同作用域、不同的生存期。 同一变量可以在不同的作用域内定义多次，内层的定义会覆盖外层的定义。 在外部块定义的变量，可以在嵌套块中使用。但外部块不能访问嵌套块中的变量。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 DECLARE emp_id INTEGER :=7788; --定义变量并赋值 outer_var INTEGER :=6688; --定义变量并赋值 BEGIN DECLARE emp_id INTEGER :=7799; --定义变量并赋值 inner_var INTEGER :=6688; --定义变量并赋值 BEGIN dbms_output.put_line('inner emp_id ='||emp_id); --显示值为7799 dbms_output.put_line('outer_var ='||outer_var); --引用外部块的变量 END; dbms_output.put_line('outer emp_id ='||emp_id); --显示值为7788 END; /

赋值语句 语法 给变量赋值的语法请参见图2。 图2 assignment_value::= 对以上语法格式的解释如下： variable_name，为变量名。 value，可以是值或表达式。值value的类型需要和变量variable_name的类型兼容才能正确赋值。 示例 1 2 3 4 5 6 7 DECLARE emp_id INTEGER := 7788;--赋值 BEGIN emp_id := 5;--赋值 emp_id := 5*7784; END; /

匿名块 匿名块（Anonymous Block）一般用于不频繁执行的脚本或不重复进行的活动。它们在一个会话中执行，并不被存储。 语法 匿名块的语法参见图1。 图1 anonymous_block::= 对以上语法图的解释如下： 匿名块程序实施部分，以BEGIN语句开始，以END语句停顿，以一个分号结束。输入“/”按回车执行它。 最后的结束符“/”必须独占一行，不能直接跟在END后面。 声明部分包括变量定义、类型、游标定义等。 最简单的匿名块不执行任何命令。但一定要在任意实施块里至少有一个语句，甚至是一个NULL语句。 示例 下面列举了基本的匿名块程序： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 --空语句块 BEGIN NULL; END; / --将信息打印到控制台： BEGIN dbms_output.put_line('hello world!'); END; / --将变量内容打印到控制台： DECLARE my_var VARCHAR2(30); BEGIN my_var :='world'; dbms_output.put_line('hello'||my_var); END; /

基本结构 PL/SQL块中可以包含子块，子块可以位于PL/SQL中任何部分。PL/SQL块的结构如下： 声明部分：声明PL/SQL用到的变量，类型及游标，以及局部的存储过程和函数。 DECLARE 不涉及变量声明时声明部分可以没有。 对匿名块来说，没有变量声明部分时，可以省去DECLARE关键字。 对存储过程来说，没有DECLARE， AS相当于DECLARE。即便没有变量声明的部分，关键字AS也必须保留。 执行部分：过程及SQL语句，程序的主要部分。必选。 BEGIN 执行异常部分：错误处理。可选。 EXCEPTION 结束 END; / 禁止在PL/SQL块中使用连续的Tab，连续的Tab可能会造成在使用gsql工具带“-r”参数执行PL/SQL块时出现异常。

LIMIT LIMIT函数可以返回数组的最大长度限制。 用法如下： varray.LIMIT或varray.LIMIT() 示例： 1 2 3 4 5 6 7 8 9 10 --演示在存储过程中对数组LIMIT函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; BEGIN v_varray := varray_type(1, 2, 3, 4, 5); DBMS_OUTPUT.PUT_LINE('v_varray.limit:' || v_varray.limit); END; / 执行结果： 1 2 call test_varray(); v_varray.limit:20

DELETE DELETE函数可以从数组删除数组中的所有元素。 用法如下： varray.DELETE或varray.DELETE() 示例： 1 2 3 4 5 6 7 8 9 10 11 --演示在存储过程中对数组DELETE函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; BEGIN v_varray := varray_type(1, 2, 3, 4, 5); v_varray.delete; DBMS_OUTPUT.PUT_LINE('v_varray.count:' || v_varray.count); END; / 执行结果： 1 2 call test_varray(); v_varray.count:0

EXISTS EXISTS函数可以判断数组下标是否存在。 用法如下： varray.EXISTS(index) 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 --演示在存储过程中对数组EXISTS函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; BEGIN v_varray := varray_type(1, 2, 3); IF v_varray.EXISTS(1) THEN DBMS_OUTPUT.PUT_LINE('v_varray.EXISTS(1)'); END IF; IF NOT v_varray.EXISTS(10) THEN DBMS_OUTPUT.PUT_LINE('NOT v_varray.EXISTS(10)'); END IF; END; / 执行结果： 1 2 3 call test_varray(); v_varray.EXISTS(1) NOT v_varray.EXISTS(10)

TRIM TRIM函数可以从数组尾部删除指定数量的元素。 用法如下： varray.TRIM(size) 其中varray.TRIM这种无参的调用会默认入参为1，等价于varray.TRIM(1) 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 --演示在存储过程中对数组TRIM函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; BEGIN v_varray := varray_type(1, 2, 3, 4, 5); v_varray.trim(3); DBMS_OUTPUT.PUT_LINE('v_varray.count' || v_varray.count); v_varray.trim; DBMS_OUTPUT.PUT_LINE('v_varray.count:' || v_varray.count); END; / 执行结果： 1 2 3 call test_varray(); v_varray.count:2 v_varray.count:1

数组类型的使用 在使用数组之前，需要自定义一个数组类型。 在存储过程中紧跟AS关键字后面定义数组类型。定义方法为： TYPE array_type IS VARRAY(size) OF data_type [NOT NULL]; 其中： array_type：要定义的数组类型名。 VARRAY：表示要定义的数组类型。 size：取值为正整数，表示可以容纳的成员的最大数量。 data_type：要创建的数组中成员的类型。 NOT NULL: 可选约束，可以约束该数组中的元素均不为NULL。 在GaussDB(DWS)中，数组会自动增长，访问越界会返回一个NULL，不会报错。越界写入数组会提示：Subscript outside of limit. 在存储过程中定义的数组类型，其作用域仅在该存储过程中。 建议选择上述定义方法的一种来自定义数组类型，当同时使用两种方法定义同名的数组类型时，GaussDB(DWS)会优先选择存储过程中定义的数组类型来声明数组变量。 GaussDB(DWS) 8.1.0之前版本， 由于数组可以自动增长，系统不会校验数组越界以及数组元素的长度限制。当前版本为了兼容Oracle的用法增加了相关约束。如果已经存在越界写入等场景，可通过在behavior_compat_options参数中配置varray_verification，来兼容之前不校验的行为。 示例：

EXTEND EXTEND函数主要是为了兼容Oracle的两种用法。在GaussDB(DWS)中，数组会自动增长，EXTEND函数不是必须的。如果是新写的存储过程，完全没有必要使用EXTEND函数。 EXTEND函数可以对数组进行扩展，EXTEND有两种调用方式。 方式一： EXTEND包含一个整型入参，表示数组向后扩展size大小的长度，EXTEND后COUNT和LAST函数的值也会有相应的变化。 用法如下： varray.EXTEND(size) 其中varray.EXTEND这种无参的调用默认会向后扩展1位等价于varray.EXTEND(1) 方式二： EXTEND包含两个整型入参，第一个参数代表向后扩展size大小的长度，第二个参数表示扩展后的数组元素值和之下标为index的元素相同。 用法如下： varray.EXTEND(size, index) 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 --演示在存储过程中对数组EXTEND函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; BEGIN v_varray := varray_type(1, 2, 3); v_varray.extend(3); DBMS_OUTPUT.PUT_LINE('v_varray.count=' || v_varray.count); v_varray.extend(2,3); DBMS_OUTPUT.PUT_LINE('v_varray.count=' || v_varray.count); DBMS_OUTPUT.PUT_LINE('v_varray(7)=' || v_varray(7)); DBMS_OUTPUT.PUT_LINE('v_varray(8)=' || v_varray(7)); END; /

NEXT和PRIOR NEXT函数和PRIOR函数主要用于数组的循环遍历中，NEXT函数会根据入参index值，返回下一个数组元素的下标，若已经到达数组下标最大值则返回NULL。PRIOR函数会根据入参index值，返回上一个数组元素的下标，若已经到达数组下标最小值则返回NULL。 用法如下： varray.NEXT(index) varray.PRIOR(index) 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 --演示在存储过程中对数组NEXT和PRIOR函数的用法。 CREATE OR REPLACE PROCEDURE test_varray AS TYPE varray_type IS VARRAY(20) OF INT; v_varray varray_type; i int; BEGIN v_varray := varray_type(1, 2, 3); i := v_varray.COUNT; WHILE i IS NOT NULL LOOP DBMS_OUTPUT.PUT_LINE('test prior v_varray('||i||')=' || v_varray(i)); i := v_varray.PRIOR(i); END LOOP; i := 1; WHILE i IS NOT NULL LOOP DBMS_OUTPUT.PUT_LINE('test next v_varray('||i||')=' || v_varray(i)); i := v_varray.NEXT(i); END LOOP; END; / 执行结果： 1 2 3 4 5 6 7 call test_varray(); test prior v_varray(3)=3 test prior v_varray(2)=2 test prior v_varray(1)=1 test next v_varray(1)=1 test next v_varray(2)=2 test next v_varray(3)=3

GaussDB(DWS)存储过程数据类型转换 数据库中允许有些数据类型进行隐式类型转换（赋值、函数调用的参数等），有些数据类型间不允许进行隐式数据类型转换，可尝试使用GaussDB(DWS)提供的类型转换函数，例如CAST进行数据类型强转。 GaussDB(DWS)数据库常见的隐式类型转换，请参见表1。 GaussDB(DWS)支持的DATE的效限范围是：公元前4713年到公元294276年。 表1 隐式类型转换表 原始数据类型 目标数据类型 备注 CHAR VARCHAR2 - CHAR NUMBER 原数据必须由数字组成。 CHAR DATE 原数据不能超出合法日期范围。 CHAR RAW - CHAR CLOB - VARCHAR2 CHAR - VARCHAR2 NUMBER 原数据必须由数字组成。 VARCHAR2 DATE 原数据不能超出合法日期范围。 VARCHAR2 CLOB - NUMBER CHAR - NUMBER VARCHAR2 - DATE CHAR - DATE VARCHAR2 - RAW CHAR - RAW VARCHAR2 - CLOB CHAR - CLOB VARCHAR2 - CLOB NUMBER 原数据必须由数字组成。 INT4 CHAR - 父主题： GaussDB(DWS)存储过程

什么是GaussDB(DWS)存储过程 商业规则和业务逻辑可以通过程序存储在GaussDB(DWS)中，这个程序就是存储过程。 存储过程是SQL，PL/SQL，Java语句的组合。存储过程使执行商业规则的代码可以从应用程序中移动到数据库。从而，代码存储一次能够被多个程序使用。 存储过程的创建及调用办法请参考CREATE PROCEDURE。 GaussDB(DWS) PL/pgSQL语言函数节所提到的PL/pgSQL语言创建的函数与存储过程的应用方法相同。下面各节中，除非特别声明，否则内容通用于存储过程和PL/pgSQL语言函数。

GaussDB(DWS) PL/pgSQL语言函数 PL/pgSQL类似于Oracle的PL/SQL，是一种可载入的过程语言。 用PL/pgSQL创建的函数可以被用在任何可以使用内建函数的地方。例如，可以创建复杂条件的计算函数并且后面用它们来定义操作符或把它们用于索引表达式。 SQL被大多数数据库用作查询语言。它是可移植的并且容易学习。但是每一个SQL语句必须由数据库服务器单独执行。 这意味着客户端应用必须发送每一个查询到数据库服务器、等待它被处理、接收并处理结果、做一些计算，然后发送更多查询给服务器。如果客户端和数据库服务器不在同一台机器上，所有这些会引起进程间通信并且将带来网络负担。 通过PL/pgSQL，可以将一整块计算和一系列查询分组在数据库服务器内部，这样就有了一种过程语言的能力并且使SQL更易用，同时能节省的客户端/服务器通信开销。 客户端和服务器之间的额外往返通信被消除。 客户端不需要的中间结果不必被整理或者在服务器和客户端之间传送。 多轮的查询解析可以被避免。 PL/pgSQL可以使用SQL中所有的数据类型、操作符和函数。 应用PL/pgSQL创建函数的语法为CREATE FUNCTION。正如前面所说，PL/pgSQL类似于Oracle的PL/SQL，是一种可载入的过程语言。其应用方法与GaussDB(DWS)存储过程相似，只是存储过程无返回值，函数有返回值。 父主题： GaussDB(DWS)用户自定义函数

相关GUC参数 udf_memory_limit 系统级别的GUC参数，用于限制每个CN、DN执行UDF可以使用的物理内存量，默认为0.05 * max_process_memory。可通过修改postgresql.conf文件进行配置，配置后需要重启数据库服务后才可生效。 udf_memory_limit是max_process_memory的一部分。每个CN、DN启动时，会预留（udf_memory_limit - 200MB）内存供UDF Worker进程使用。CN、DN和UDF Worker是不同的进程，但CN、DN自动少用一部分内存，把这部分内存节省下来供UDF Worker进程使用。 例如：在某DN上把max_process_memory设置为10GB，udf_memory_limit设置为4GB，则此DN最多使用10GB - (4GB - 200MB)=6.2GB内存。即使用户没有执行任何UDF，则此DN也最多只能使用6.2GB内存。默认情况下，udf_memory_limit为0.05 * max_process_memory。查询pv_total_memory_detail视图时可以发现，process_used_memory永远不会超过max_process_memory - (udf_memory_limit - 200MB)。 UDF进程断连时会有报错提示。当出现“memory in UDF Work Process is limited by cgroup: [usage: xxx, max_usage_history: xxx, limit: xxx]”时，可以根据提示判断当前内存使用情况。报错中的usage表示UDF进程被KILL后剩余UDF进程的总物理内存使用量；max_usage_history表示UDF实例启动后历史上使用过的最大内存量，limit表示UDF进程使用内存的最大限制量。如果max_usage_history值接近limit值说明当前集群存在内存超过限制的风险，需要优化业务或按实际情况调整udf_memory_limit参数限制。 一个CN执行最简单的Java UDF函数，使用的物理内存量大约为50MB，用户可以根据自己Java函数的内存使用量和并发度设置此参数。新增此参数后，不再建议用户设置UDFWorkerMemHardLimit和FencedUDFMemoryLimit。 当UDF进程并发度过大，内存超出udf_memory_limit设置值时会导致进程退出等非预期情况，该场景下执行结果可能不可靠，强烈建议根据实际情况进行参数设置，保留足够内存余量。如果系统记录有/var/log/messages，可查看该日志文件是否存在因超过cgroup内存限制而造成内存不足。内存严重不足时，甚至可能导致UDF master进程退出，可以查看UDF日志进行分析，默认的UDF日志路径在$GAUSS LOG /cm/cm_agent/pg_log下。例如，出现以下日志时就说明内存资源严重不足，导致了UDF master进程退出，需要检查udf_memory_limit参数设置。 0 [BACKEND] FATAL: poll() failed: Bad address, please check the parameter:udf_memory_limit to make sure there is enough memory. FencedUDFMemoryLimit 会话级别的GUC参数，用户限制会话发起的单个Fenced UDF Worker进程的最大虚拟内存使用量，设置方法如下： SET FencedUDFMemoryLimit='512MB'; 该参数的取值范围为 (150MB, 1G]，当设置大于1G时会立即报错，当设置小于等于150MB时，则会在调用函数时报错。 FencedUDFMemoryLimit设置为0，表示不控制Fenced UDF Worker的虚拟内存使用量。 建议通过设置udf_memory_limit控制Fenced UDF Worker使用的物理内存量。不建议用户使用FencedUDFMemoryLimit，尤其在使用Java UDF时不建议用户设置此参数。但是如果用户非常清楚设置该参数带来的影响，可以参考下列信息进行设置： C UDF worker启动之后，占用的虚拟内存约为200MB，占用的物理内存约为16MB。 Java UDF worker启动之后，占用的虚拟内存约为2.5GB，占用的物理内存约为50MB。

基本数据类型映射关系 表1 PL/Java默认数据类型映射关系 GaussDB(DWS) Java BOOLEAN boolean "char" byte bytea byte[] SMALLINT short INTEGER int BIGINT long FLOAT4 float FLOAT8 double CHAR java.lang.String VARCHAR java.lang.String TEXT java.lang.String name java.lang.String DATE java.sql.Timestamp TIME java.sql.Time (stored value treated as local time) TIMETZ java.sql.Time TIMESTAMP java.sql.Timestamp TIMESTAMPTZ java.sql.Timestamp

数组类型处理 GaussDB(DWS)支持基础数组类型的转换，只需要在创建函数时在数据类型后追加 [] 即可，例如： CREATE FUNCTION java_arrayLength(INTEGER[]) RETURNS INTEGER AS 'Example.getArrayLength' LANGUAGE JAVA; Java代码类似于： public class Example { public static int getArrayLength(Integer[] intArray) { return intArray.length; } } 那么下面的调用的语句后： SELECT java_arrayLength(ARRAY[1, 2, 3]); 得到预期结果应该如下所示： java_arrayLength --------------------- 3 (1 row)

重载函数 PL/Java支持重载函数，因此可以创建同名函数，或者调用Java代码中的重载方法。步骤如下： 创建重载函数 例如，在Java中可以实现两个方法名相同，输入参数类型不同的方法dummy(int) 和dummy(String) public class Example { public static int dummy(int value) { return value*2; } public static String dummy(String value) { return value; } } 并在GaussDB(DWS)中创建两个同名函数分别指定为上述两个方法： CREATE FUNCTION java_dummy(INTEGER) RETURNS INTEGER AS 'Example.dummy' LANGUAGE JAVA; CREATE FUNCTION java_dummy(VARCHAR) RETURNS VARCHAR AS 'Example.dummy' LANGUAGE JAVA; 调用重载函数 在调用重载函数时，GaussDB(DWS)会根据输入的参数类型去调用匹配该类型的Java方法。因此上述两个函数的调用结果如下所示： SELECT java_dummy(5); java_dummy ----------------- 10 (1 row) SELECT java_dummy('5'); java_dummy --------------- 5 (1 row) 需要注意的是，由于GaussDB(DWS)对数据类型存在隐式转换的情况，因此建议在调用重载函数时，指定输入参数的类型，例如： SELECT java_dummy(5::varchar); java_dummy ---------------- 5 (1 row) 此时会优先匹配所指定的参数类型，如果不存在指定参数类型的Java方法，则会对参数进行隐式转换匹配转换后的参数类型对应的Java方法。 SELECT java_dummy(5::INTEGER); java_dummy ----------------- 10 (1 row) DROP FUNCTION java_dummy(INTEGER); SELECT java_dummy(5::INTEGER); java_dummy ---------------- 5 (1 row) 隐式转换的数据类型包括： 可以默认转换为INTEGER类型的包括：SMALLINT 可以默认转换为BIGINT类型的包括：SMALLINT、INTEGER 可以默认转换为BOOL类型的包括：TINYINT、SMALLINT、INTEGER、BIGINT 可以默认转换为TEXT类型的包括：CHAR、NAME、BIGINT、INTEGER、SMALLINT、 TINYINT、RAW、FLOAT4、FLOAT8、BPCHAR、VARCHAR、NVARCHAR2、DATE、TIMESTAMP、TIMESTAMPTZ、NUMERIC、SMALLDATETIME 可以默认转换为VARCHAR类型的包括：TEXT、CHAR、BIGINT、INTEGER、SMALLINT、TINYINT、RAW、FLOAT4、FLOAT8、BPCHAR、DATE、NVARCHAR2、TIMESTAMP、NUMERIC、SMALLDATETIME 删除重载函数 对于重载函数，删除时需要指定函数的参数类型，否则无法删除。 DROP FUNCTION java_dummy(INTEGER);

日志 PL/Java使用标准的Java Logger。 因此，用户可以通过如下方式记录日志： Logger.getAnonymousLogger().config( "Time is " + new Date(System.currentTimeMillis())); 初始化的Java Logger类会默认设置为CONFIG级别，对应为GaussDB(DWS)的LOG级别。Java Logger类输出的日志消息都会重定向到GaussDB(DWS)后端，并写入到服务器日志或显示在用户界面上。MPPDB服务器日志将记录LOG、WARNING、ERROR级别的信息，而SQL用户界面将显示WARNING和ERROR级别的日志消息。Java Logger级别与GaussDB(DWS)的日志级别对应关系见下表。 表2 PL/Java日志级别 java.util.logging.Level GaussDB(DWS) 日志级别 SERVER ERROR WARNING WARNING CONFIG LOG INFO INFO FINE DEBUG1 FINER DEBUG2 FINEST DEBUG3 用户可以通过以下方式更改Java Logger的记录级别。例如通过下面的Java代码修改Java Logger级别为SEVERE，此时再记录WARNING级别的日志时，日志消息（msg）就不会再写入到GaussDB(DWS)日志中。 Logger log = Logger.getAnonymousLogger(); Log.setLevel(Level.SEVERE); log.log(Level.WARNING, msg);

示例 使用PL/Java函数时，需要首先将Java方法的实现打包为jar包并且部署到数据库中，然后使用数据库管理员账号创建函数，考虑兼容性问题，请使用1.8.0_322版本的JRE进行编译。 编译jar包。 Java方法的实现和出包可以借助IDE来实现，以下是一个通过命令行来进行编译和出包的简单的示例，通过这个简单示例可以创建出一个包含单个方法的jar包文件。 首先，编写一个Example.java文件，在此文件中实现子字符串大写转换的方法，本例中类名为Example，方法名为upperString，内容如下： 1 2 3 4 5 6 7 public class Example { public static String upperString (String text, int beginIndex, int endIndex) { return text.substring(beginIndex, endIndex).toUpperCase(); } } 然后，创建manifest.txt清单文件，文件内容如下： 1 2 3 4 5 6 Manifest-Version: 1.0 Main-Class: Example Specification-Title: "Example" Specification-Version: "1.0" Created-By: 1.6.0_35-b10-428-11M3811 Build-Date: 08/14/2018 10:09 AM 其中，Manifest-Version定义了manifest文件的版本，Main-Class定义了jar文件的入口类，Specification-Title和Specification-Version属于包的扩展属性，Specification-Title定义了扩展规范的标题，Specification-Version定义了扩展规范的版本，Created-By声明了该文件的生成者，Build-Date声明了该文件构建日期。 最后，编译java文件并打包得到javaudf-example.jar 1 2 javac Example.java jar cfm javaudf-example.jar manifest.txt Example.class jar包的命名规则应符合JDK命名要求，如果含有非法字符，在部署或者使用函数时将出错。 部署jar包。 Jar包首先需要放置到OBS服务器中，放置方法具体请参见《 对象存储服务 控制台指南》的上传文件章节。接着创建访问密钥AK/SK，获取访问密钥的具体步骤，请参见创建访问密钥（AK和SK）章节。登录数据库运行gs_extend_library函数，将文件导入到GaussDB(DWS)中： 1 SELECT gs_extend_library('addjar', 'obs://bucket/path/javaudf-example.jar accesskey=access_key_value_to_be_replaced secretkey=secret_access_key_value_to_be_replaced region=region_name libraryname=example'); gs_extend_library函数如何使用请参见 管理jar包和文件。函数中的AK/SK值，请用户根据实际获取值替换。region_name请用户根据实际所在的区 域名 称替换。 使用PL/Java函数。 首先，使用拥有sysadmin权限的数据库用户（例如：dbadmin）登录数据库并创建java_upperstring函数如下： 1 2 3 4 CREATE FUNCTION java_upperstring(VARCHAR, INTEGER, INTEGER) RETURNS VARCHAR AS 'Example.upperString' LANGUAGE JAVA; 函数java_upperstring中定义的数据类型为GaussDB(DWS)的数据类型。该数据类型需要和步骤1中java定义的方法upperString中数据类型一一对应。GaussDB(DWS)与Java数据类型的对应关系，请参见表1。 AS子句用于指定该函数所调用的Java方法的类名和static方法名，格式为“类名.方法名”。该字段需要和步骤1中java定义的类名和方法名一致。 使用PL/Java函数时，LANGUAGE字段应指定为JAVA。 CREATE FUNCTION更多说明，请参见创建函数。 然后，执行java_upperstring函数： 1 SELECT java_upperstring('test', 0, 1); 得到预期结果为： 1 2 3 4 java_upperstring --------------------- T (1 row) 授权普通用户使用PL/Java函数。 创建普通用户，名称为udf_user。 1 CREATE USER udf_user PASSWORD 'password'; 授权普通用户udf_user对java_upperstring函数的使用权限。注意，此处需要把函数所在模式和函数的使用权限同时赋予给用户，用户才可以使用此函数。 1 2 GRANT ALL PRIVILEGES ON SCHEMA public TO udf_user; GRANT ALL PRIVILEGES ON FUNCTION java_upperstring(VARCHAR, INTEGER, INTEGER) TO udf_user; 以普通用户udf_user登录数据库。 1 SET SESSION SESSION AUTHORIZATION udf_user PASSWORD 'password'; 执行java_upperstring函数： 1 SELECT public.java_upperstring('test', 0, 1); 得到预期结果为： 1 2 3 4 java_upperstring --------------------- T (1 row) 删除函数。 如果不再使用该函数可以进行删除： 1 DROP FUNCTION java_upperstring; 卸载jar包。 使用gs_extend_library函数卸载jar包： 1 SELECT gs_extend_library('rmjar', 'libraryname=example');

SQL语句出错自动重试 GaussDB(DWS)支持在SQL语句执行出错时自动重试（下文简称CN Retry）。对于来自gsql客户端、JDBC、ODBC驱动的SQL语句，在SQL语句执行失败时，CN端能够自动识别语句执行过程中的报错，并重新下发任务进行自动重试。 该功能的限制和约束如下： 功能范围限制： 仅能提高故障发生时SQL语句执行成功率，不能保证100%的执行成功。 CN Retry默认开启，开启后temp表会记录日志，关闭CN Retry后，temp表不会记录日志，因此不能在使用temp表时反复打开/关闭CN Retry开关，否则主备切换后再CN Retry会造成数据不一致。 CN Retry默认开启，开启后新创建的unlogged表会忽视unlogged关键字，建成普通表。关闭CN Retry后，unlogged表不会记录日志，因此不能在使用unlogged表时反复打开/关闭CN Retry开关，否则主备切换后再CN Retry会造成数据不一致。 在使用gds进行数据导出时，支持CN Retry。现有机制导出时会对重复文件进行检测并删除相同的文件，因此建议不要对相同的外表重复导出数据，除非确定数据目录中相同文件名的文件需要删除。 错误类型约束： SQL语句出错时能够被识别和重试的错误，仅限在错误类型列表（请参考表1）中定义的错误。 语句类型约束： 支持单语句CN Retry、存储过程、函数、匿名块。不支持事务块中的语句。 存储过程语句约束： 包含EXCEPTION的存储过程，如果在执行过程中（包含语句块执行和EXCEPTION中的语句执行）错误被抛出，可以retry，且系统内部错误发生时，retry会先于EXCEPTION被执行，而如果报错被EXCEPTION捕获则不能retry。 不支持使用全局变量的package。 不支持DBMS_JOB。 不支持UTL_FILE。 如果存储过程中有输出打印信息（如dbms_output.put_line或raise info等），则发生retry时会重复输出已打印的消息，并会在重复消息前输出“Notice：Retry triggered, some message may be duplicated.”加以提示。 集群状态约束： 仅支持DN、GTM实例故障。 CN Retry有次数限制，如果在CN Retry达到最大尝试次数（最大次数由max_query_retry_times控制）之前，集群状态无法从故障状态恢复到正常状态，那么CN Retry不能保证执行成功。 扩容时不支持CN Retry。 数据导入约束： 不支持COPY FROM STDIN语句。 不支持gsql \copy from元命令。 不支持JDBC CopyManager copyIn导入数据。 CN Retry支持的错误类型列表和对应的错误码信息见表1， 可以通过GUC参数retry_ecode_list设置CN Retry支持的错误类型列表，但不建议用户直接修改该参数，如有修改需求请联系技术工程师协助处理。 表1 CN Retry支持的错误类型列表 错误类型 错误码 备注 对端连接重置（CONNECTION_RESET_BY_PEER） YY001 TCP通信错误：Connection reset by peer（CN和DN间通信） 对端流重置（STREAM_CONNECTION_RESET_BY_PEER） YY002 TCP通信错误：Stream connection reset by peer（DN和DN间通信） 锁等待超时（LOCK_WAIT_TIMEOUT） YY003 锁超时，Lock wait timeout 连接超时（CONNECTION_TIMED_OUT） YY004 TCP通信错误，Connection timed out 查询设置错误（SET_QUERY_ERROR） YY005 SET命令发送失败，Set query 超出逻辑内存（OUT_OF_LOGICAL_MEMORY） YY006 内存申请失败，Out of logical memory 通信库内存分配（SCTP_MEMORY_ALLOC） YY007 SCTP通信错误，Memory allocate error 无通信库缓存数据（SCTP_NO_DATA_IN_BUFFER） YY008 SCTP通信错误，SCTP no data in buffer 通信库释放内存关闭（SCTP_RELEASE_MEMORY_CLOSE） YY009 SCTP通信错误，Release memory close SCTP、TCP断开（SCTP_TCP_DISCONNECT） YY010 SCTP通信错误，TCP disconnect 通信库断开（SCTP_DISCONNECT） YY011 SCTP通信错误，SCTP disconnect 通信库远程关闭（SCTP_REMOTE_CLOSE） YY012 SCTP通信错误，Stream closed by remote 等待未知通信库通信（SCTP_WAIT_POLL_UNKNOW） YY013 等待未知通信库通信，SCTP wait poll unknow 无效快照（SNAPSHOT_INVALID） YY014 快照非法，Snapshot invalid 通讯接收信息错误（ERRCODE_CONNECTION_RECEIVE_WRONG） YY015 连接获取错误，Connection receive wrong 内存耗尽（OUT_OF_MEMORY） 53200 内存耗尽，Out of memory 连接失败（CONNECTION_FAILURE） 08006 GTM出错，Connection failure 连接异常（CONNECTION_EXCEPTION） 08000 连接出现错误，和DN的通讯失败，Connection exception 管理员关闭系统（ADMIN_SHUTDOWN） 57P01 管理员关闭系统，Admin shutdown 关闭远程流接口（STREAM_REMOTE_CLOSE_SOCKET） XX003 关闭远程套接字，Stream remote close socket 重复查询编号（ERRCODE_STREAM_DUPLICATE_QUERY_ID） XX009 重复查询，Duplicate query id stream查询并发更新同一行（ERRCODE_STREAM_CONCURRENT_UPDATE） YY016 stream查询并发更新同一行，Stream concurrent update LLVM内存分配错误（ERRCODE_LLVM_BAD_ALLOC_ERROR ） CG003 内存分配错误， Allocate error LLVM致命错误（ERRCODE_LLVM_FATAL_ERROR） CG004 致命错误，Fatal error HashJoin临时文件读取错误(ERRCODE_HASHJOIN_TEMP_FILE_ERROR) F0011 临时文件读取错误，File error Buffer文件读取错误(ERRCODE_BUFFER_FILE_ERROR) F0012 文件读取错误，File error 分区个数发生变化(ERRCODE_PARTITION_NUM_CHANGED) 45003 在扫描LIST分区表时，发现此时的分区个数和优化阶段的分区个数不一致，一般出现在查询和ADD/DROP分区并发时。（此错误类型仅8.1.3及以上集群版本支持） 节点间对象SCHEMA名称不一致(ERRCODE_UNMATCH_OBJECT_SCHEMA) 42P30 对象SCHEMA名称不一致，Unmatched schema name 开启CN Retry功能需要设置如下GUC参数： 必选的GUC参数（CN和DN都需设置） max_query_retry_times CN Retry功能开启时会为临时表数据记录日志，为保证数据一致性，在使用临时表时不能切换CN Retry开关状态，保持使用临时表的会话中CN Retry开关始终处于打开状态或者关闭状态。 可选的GUC参数 cn_send_buffer_size max_cn_temp_file_size 父主题： SQL调优