华为云用户手册

kill_snapshot(scope cstring) 描述：中止后台快照线程。该函数向后台快照线程发送中止信号并等待线程结束。 输入参数scope：表示操作范围。该参数取值范围为local和global。 local表示中止当前CN上的快照线程。 global表示不仅会中止当前CN上的快照线程，还会向集群中所有其他CN发送中止快照线程的请求，即中止集群中所有CN上的快照线程。 如果输入其他值，则报错“Scope is invalid, use "local" or "global".”。 输入参数可为空，表示默认取值为local。 返回值类型：无 该函数只有数据库管理员SYSADMIN才有权执行，非管理员执行会提示无权限。 该函数只能在CN上执行，在DN上执行会提示：“kill_snapshot can only be executed on coordinator.”； 执行该函数会向后台快照线程发送中止信号并等待其结束。如果100s内快照线程仍未中止则会报错：“Kill snapshot thread failed”；

pg_export_snapshot() 描述：保存当前的快照并返回它的标识符。 返回值类型：text 备注：函数pg_export_snapshot保存当前的快照并返回一个文本字符串标识此快照。这个字符串必须传递给想要导入快照的客户端。可用在set transaction snapshot snapshot_id时导入snapshot，但是应用的前提是该事务设置了REPEATABLE READ隔离级别。该函数的输出不可用做set transaction snapshot的输入。 示例： 1 2 3 4 5 SELECT pg_export_snapshot(); pg_export_snapshot -------------------- 00000000000A7128-1 (1 row)

create_wdr_snapshot() 描述：创建性能数据快照。 返回值类型：text 该函数只有数据库管理员SYSADMIN才可以执行，非管理员执行会提示无权限。 该函数只能在CN上执行，在DN上执行会返回：“WDR snapshot can only be created on coordinator.”。 执行该函数前需确认enable_wdr_snapshot参数处于开启状态。如果enable_wdr_snapshot为off，执行该函数会返回：“WDR snapshot request can't be executed, because GUC parameter 'enable_wdr_snapshot' is off.”。 如果执行该函数时，快照线程由于节点重启等原因尚未启动，会提示错误：“WDR snapshot request can not be accepted, please retry later.”。 如果执行该函数失败，会提示：“Cannot respond to WDR snapshot request.”。 如果执行成功，会返回：“WDR snapshot request has been submitted.”。该提示表明创建快照请求已发送至后台快照线程，但不代表创建快照成功。

pg_terminate_query(queryId int) 描述：终止一个后端的当前查询。该函数8.1.2及以上版本支持。 返回值类型：boolean 示例： 1 2 3 4 5 6 7 8 9 10 11 12 SELECT query_id FROM pgxc_stat_activity WHERE stmt_type ='RESET'; query_id ---------- 0 0 (2 rows) SELECT pg_terminate_query(0); pg_terminate_query -------------------- f (1 row)

pgxc_terminate_query(queryId int) 描述：终止当前集群下正在执行的查询。该函数8.1.2及以上版本支持。 返回值类型：boolean 示例： 1 2 3 4 5 6 7 8 9 10 11 SELECT query_id FROM pgxc_stat_activity; query_id ----------------- 72339069014638631 (1 rows) SELECT pgxc_terminate_query(72339069014638631); pgxc_terminate_query ---------------------- t (1 row)

pg_cancel_backend(pid int) 描述：取消一个后端的当前查询。 返回值类型：boolean 备注：pg_cancel_backend向由pid标识的后端进程发送一个查询取消（SIGINT）信号。一个活动的后端进程的PID可以从pg_stat_activity视图的pid字段找到，或者在服务器上用ps列出数据库进程。 示例： 1 2 3 4 5 6 7 8 9 10 11 SELECT pid FROM pg_stat_activity WHERE stmt_type ='RESET'; pid ----------------- 281471222065200 (1 row) SELECT pg_cancel_backend(281471222065200); pg_cancel_backend ------------------- t (1 row)

pg_rotate_logfile() 描述：滚动服务器的日志文件。 返回值类型：boolean 备注：pg_rotate_logfile通知日志文件管理器立即切换到一个新的输出文件。该函数仅在内置日志收集器运行时有效。 示例： 1 2 3 4 5 SELECT pg_rotate_logfile(); pg_rotate_logfile ------------------- t (1 row)

pg_cancel_query(queryId int) 描述：取消一个后端的当前查询。该函数8.1.2及以上版本支持。 返回值类型：boolean 备注：pg_cancel_query向由query_id标识的后端进程发送一个查询取消（SIGINT）信号。一个活动的后端进程的query_id可以从pg_stat_activity视图的query_id字段找到。 示例： 1 2 3 4 5 6 7 8 9 10 11 12 SELECT query_id FROM pgxc_stat_activity WHERE stmt_type ='RESET'; query_id ---------- 0 0 (2 rows) SELECT pg_cancel_query(0); pg_cancel_query ----------------- f (1 row)

pgxc_cancel_query(queryId int) 描述：取消当前集群下正在执行的查询。该函数8.1.2及以上版本支持。 返回值类型：boolean 备注：如果所有节点的查询均已取消，函数返回true，否则返回false。 示例： 1 2 3 4 5 6 7 8 9 10 11 12 SELECT query_id FROM pgxc_stat_activity WHERE stmt_type ='RESET'; query_id ---------- 0 0 (2 rows) SELECT pgxc_cancel_query(0); pgxc_cancel_query ------------------- f (1 row)

pg_terminate_backend(pid int) 描述：终止一个后台线程。 返回值类型：boolean 备注：如果成功，函数返回true，否则返回false。 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 SELECT pid FROM pg_stat_activity; pid ----------------- 140657876268816 140433774061312 140433587902208 140433656592128 140433723717376 140433637189376 140433552770816 140433481983744 140433349310208 (9 rows) SELECT pg_terminate_backend(140657876268816); pg_terminate_backend ---------------------- t (1 row)

pg_wlm_jump_queue(pid int) 描述：调整任务到CN队列的最前端。 返回值类型：boolean 备注：如果成功，函数返回true，否则返回false。 示例： 1 2 3 4 5 6 7 8 9 10 11 SELECT pid FROM pg_stat_activity WHERE stmt_type ='RESET'; pid ----------------- 281471222065200 (1 row) SELECT pg_wlm_jump_queue(281471222065200); pg_wlm_jump_queue ------------------- t (1 row)

pg_ls_dir(dirname text) 描述：列出目录中的文件。 返回值类型：setof text 备注：pg_ls_dir返回指定目录里面的除了特殊项“.”和“..”之外所有名字。 示例： 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 SELECT pg_ls_dir('./'); pg_ls_dir ---------------------- .postgresql.conf.swp postgresql.conf pg_tblspc PG_VERSION pg_ident.conf core server.crt pg_serial pg_twophase postgresql.conf.lock pg_stat_tmp pg_notify pg_subtrans pg_ctl.lock pg_xlog pg_clog base pg_snapshots postmaster.opts postmaster.pid server.key.rand server.key.cipher pg_multixact pg_errorinfo server.key pg_hba.conf pg_replslot .pg_hba.conf.swp cacert.pem pg_hba.conf.lock global gaussdb.state (32 rows)

pg_read_binary_file(filename text [, offset bigint, length bigint,missing_ok boolean]) 描述：返回一个二进制文件的内容。 返回值类型：bytea 备注：pg_read_binary_file的功能与pg_read_file类似，除了结果的返回值为bytea类型不一致，相应地不会执行编码检查。与convert_from函数结合，这个函数可以用来读取用指定编码的一个文件。 1 SELECT convert_from(pg_read_binary_file('filename'), 'UTF8');

pg_read_file(filename text, offset bigint, length bigint) 描述：返回一个文本文件的内容。 返回值类型：text 备注：pg_read_file返回一个文本文件的一部分，从offset开始，最多返回length字节（如果先达到文件结尾，则小于这个数值）。如果offset是负数，则它是相对于文件结尾回退的长度。如果省略了offset和length，则返回整个文件。 示例： 1 2 3 4 5 6 7 8 9 10 11 SELECT pg_read_file('postmaster.pid',0,100); pg_read_file --------------------------------------- 53078 + /srv/BigData/hadoop/data1/coordinator+ 1500022474 + 8000 + /var/run/dws + localhost + 2 (1 row)

pg_stat_file(filename text) 描述：返回一个文本文件的状态信息。 返回值类型：record 备注：pg_stat_file返回一条记录，其中包含：文件大小、最后访问时间戳、最后更改时间戳、最后文件状态修改时间戳以及标识传入参数是否为目录的boolean值。典型的用法： 1 SELECT * FROM pg_stat_file('filename'); 1 SELECT (pg_stat_file('filename')).modification; 示例： 1 2 3 4 5 6 7 8 9 SELECT * FROM pg_stat_file('postmaster.pid'); size | access | modification | change | creation | isdir ------+------------------------+------------------------+------------------------ +----------+------- 117 | 2017-06-05 11:06:34+08 | 2017-06-01 17:18:08+08 | 2017-06-01 17:18:08+08 | | f (1 row) 1 2 3 4 5 SELECT (pg_stat_file('postmaster.pid')).modification; modification ------------------------ 2017-06-01 17:18:08+08 (1 row)

read_global_var(global_setting_name) 描述：用于读取全局变量当前的设置值。 返回值类型：text 备注：read_global_var用于以查询形式获取global_setting_name的当前值。和SQL语句SHOW是等效的。 示例： 1 2 3 4 5 6 SET my.var = 1000; SELECT read_global_var('my.var'); read_global_var ----------------- 1000 (1 row)

set_config(setting_name, new_value, is_local) 描述：设置参数并返回新值。 返回值类型：text 备注：set_config将参数setting_name设置为new_value，如果is_local为true，则新值将只应用于当前事务。如果希望新值应用于当前会话，可以使用false，和SQL语句SET是等效的。比如： 1 2 3 4 5 6 SELECT set_config('log_statement_stats', 'off', false); set_config ------------ off (1 row) 如果GUC参数behavior_compat_options设置配置项为DISABLE_SET_GLOBAL_VAR_ON_DATANODE，则不可以通过该函数直接在DN上设置全局变量。

current_setting(setting_name) 描述：当前的设置值。 返回值类型：text 备注：current_setting用于以查询形式获取setting_name的当前值。和SQL语句SHOW是等效的。比如： 1 2 3 4 5 6 SELECT current_setting('datestyle'); current_setting ----------------- ISO, MDY (1 row)

nullif(expr1, expr2) 描述：当且仅当expr1和expr2相等时，NULLIF才返回NULL，否则它返回expr1。 nullif(expr1, expr2) 逻辑上等价于CASE WHEN expr1 = expr2 THEN NULL ELSE expr1 END。 示例： 1 2 3 4 5 SELECT nullif('hello','world'); nullif -------- hello (1 row) 备注： 如果两个参数的数据类型不同，则： 两种数据类型之间存在隐式转换，则以其中优先级较高的数据类型为基准将另一个参数隐式转换成该类型，转换成功则进行计算，转换失败则返回错误。如： 1 2 3 4 5 SELECT nullif('1234'::VARCHAR,123::INT4); nullif -------- 1234 (1 row) 1 2 SELECT nullif('1234'::VARCHAR,'2012-12-24'::DATE); ERROR: invalid input syntax for type timestamp: "1234" 两种数据类型之间不存在隐式转换，则返回错误 。如： 1 2 3 4 5 SELECT nullif(TRUE::BOOLEAN,'2012-12-24'::DATE); ERROR: operator does not exist: boolean = timestamp without time zone LINE 1: SELECT nullif(TRUE::BOOLEAN,'2012-12-24'::DATE) FROM DUAL; ^ HINT: No operator matches the given name and argument type(s). You might need to add explicit type casts.

sys_context( 'namespace' , 'parameter') 描述：获取并返回指定namespace下参数parameter的值。 返回值类型：VARCHAR 示例： 1 2 3 4 5 SELECT sys_context('USERENV', 'CURRENT_SCHEMA'); sys_context ------------- public (1 row) 根据当前所在的实际schema而变化。 目前仅支持SYS_CONTEXT('USERENV', 'CURRENT_SCHEMA') 和SYS_CONTEXT('USERENV', 'CURRENT_USER')两种格式。

greatest(expr1 [, ...]) 描述：获取并返回参数列表中值最大的表达式的值。 ORA和TD兼容模式下，返回结果为所有非null参数的最大值。 MySQL兼容模式下，入参中存在null时，返回结果为null。 示例： 1 2 3 4 5 SELECT greatest(1*2,2-3,4-1); greatest ---------- 3 (1 row) 1 2 3 4 5 SELECT greatest('ABC', 'BCD', 'CDE'); greatest ---------- CDE (1 row)

EMPTY_BLOB() 描述：使用EMPTY_BLOB在INSERT或UPDATE语句中初始化一个BLOB变量，取值为NULL。 返回值类型：BLOB 示例： 1 2 3 4 5 6 --新建表 CREATE TABLE blob_tb(b blob,id int) DISTRIBUTE BY REPLICATION; --插入数据 INSERT INTO blob_tb VALUES (empty_blob(),1); --删除表 DROP TABLE blob_tb; 使用DBMS.GETLENGTH求得的长度为0。

ifnull(expr1, expr2) 描述：当expr1不为NULL时，返回expr1，否则返回expr2。 ifnull(expr1, expr2) 逻辑上等价于CASE WHEN expr1 IS NOT NULL THEN expr1 ELSE expr2 END。 示例： 1 2 3 4 5 SELECT ifnull(NULL,'hello'); ifnull -------- hello (1 row) 参数expr1和expr2可以为任意类型，返回结果类型规则请参考UNION，CASE和相关构造。

nvl( expr1 , expr2 ) 描述：如果expr1为NULL则返回expr2。如果expr1非NULL，则返回expr1。 示例： 1 2 3 4 5 SELECT nvl('hello','world'); nvl ------- hello (1 row) 参数expr1和expr2可以为任意类型，当NVL的两个参数不属于同类型时，看第二个参数是否可以向第一个参数进行隐式转换，如果可以则返回第一个参数类型。如果第二个参数不能向第一个参数进行隐式转换而第一个参数可以向第二个参数进行隐式转换，则返回第二个参数的类型。如果两个参数之间不存在隐式类型转换并且也不属于同一类型则报错。

least(expr1 [, ...]) 描述：获取并返回参数列表中值最小的表达式的值。 ORA和TD兼容模式下，返回结果为所有非null参数的最小值。 MySQL兼容模式下，入参中存在null时，返回结果为null。 示例： 1 2 3 4 5 SELECT least(1*2,2-3,4-1); least ------- -1 (1 row) 1 2 3 4 5 SELECT least('ABC','BCD','CDE'); least -------- ABC (1 row)

decode(base_expr, compare1, value1, Compare2,value2, … default) 描述：把base_expr与后面的每个compare(n) 进行比较，如果匹配返回相应的value(n)。如果没有发生匹配，则返回default。 示例： 1 2 3 4 5 SELECT decode('A','A',1,'B',2,0); case ------ 1 (1 row)

coalesce(expr1, expr2, ..., exprn) 描述：返回参数列表中第一个非NULL的参数值。 COALESCE(expr1, expr2) 等价于CASE WHEN expr1 IS NOT NULL THEN expr1 ELSE expr2 END。 示例： 1 2 3 4 5 SELECT coalesce(NULL,'hello'); coalesce ---------- hello (1 row) 如果表达式列表中的所有表达式都等于NULL，则本函数返回NULL。 它常用于在显示数据时用缺省值替换NULL。 和CASE表达式一样，COALESCE不会计算不需要用来判断结果的参数；即在第一个非空参数右边的参数不会被计算。

create_audit_csv_foregion_table() 描述：创建读审计日志的分区外表。用户调用该函数生成审计日志外表pgxc_audit_logs，通过读取pgxc_audit_logs可以读取放在obs上的审计日志信息。该函数仅8.2.1.300及以上集群支持。 入参： obs_server：text类型，obs server名称 file_path：text类型，obs文件路径 返回值类型：record 示例： --创建obs server CREATE SERVER obs_server FOREIGN DATA WRAPPER DFS_FDW OPTIONS ( address 'obs.example.xxx:xxx', encrypt 'true', access_key 'xxxxxxxxx', secret_access_key 'xxxxxxxxxxxxxx', type 'obs' ); --调用该函数生成审计日志外表 SELECT * FROM pg_catalog.create_audit_csv_foregion_table('obs_server','/obs-audit/test/'); create_audit_csv_foregion_table --------------------------------- t (1 row) --读取放在obs上的审计日志信息 SELECT * FROM pgxc_audit_logs where year=2023 and month=7 and date=24; year | month | date | begintime | endtime | operation_type | audit_type | result | username | database | client_conninfo | object_name | object_details |command_text| detail_info | transaction_xid | query_id | node_name | session_id | local_port | remote_port | result_rows | error_code ------+-------+------+----------------------------+----------------------------+----------------+-------------------+--------+----------+----------+-----------------+--------------------------------+----------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------+-----------------+--------------------+-----------+------------------------------------+------------+-------------+-------------+------------ 2023 | 7 | 24 | 2023-07-24 09:56:40.727+08 | 2023-07-24 09:56:42.215+08 | dml | dml_action_select | ok | dbadmin | gaussdb | gsql@[local] | public.pgxc_audit_logs | | select * f rom pgxc_audit_logs where year=2023 and date=24 and month=7;

pg_query_audit_details() 描述：查看审计日志并将审计日志中的object_name和object_details字段由json格式解析出来。该函数仅8.2.1.100及以上集群版本支持。 返回值类型：record 函数返回字段如下： 表4 pg_query_audit()函数返回字段 名称 类型 描述 begintime timestamp with time zone 操作的执行开始时间。 endtime timestamp with time zone 操作的执行结束时间。 operation_type text 操作类型，具体类型见表2。 audit_type text 审计类型，具体类型见表3。 result text 操作结果。 username text 执行操作的用户名。 database text 数据库名称。 client_conninfo text 客户端连接信息，即gsql，jdbc或odbc。 transaction_xid text 事务ID。 query_id text 查询ID。 node_name text 节点名称。 session_id text 会话ID。 local_port text 本地端口。 remote_port text 远端端口。 object_name text 表名、函数名、视图名。 column_name text 列名。 type_of_use text 对象的使用类型： 1：仅涉及（在实际使用中，此标志位暂不存在） 2：执行过程中访问（语句中出现的列以及在解析过程中访问到的列） 4：条件中发现（条件类型语句中，不包括条件表达式及函数） 8：inner join中发现 16：outer join中发现 32：聚合节点中发现（包括distinct、group by、聚集函数） 64：full join中发现 该列数值为叠加显示的数值。 use_type text type_of_use解析出的具体类型： 1：Reference only 2：Access 4：Conditional 8：Inner join 16：Outer join 32：Sum 64：Full join command_text text 操作的执行命令。 示例： 查询审计语句中所有对象的列及其在语句中使用的类型： 1 2 SET audit_object_details = on; SELECT object_name,object_details,result_rows,error_code,command_text FROM pg_query_audit('2023-05-12-03 8:00:00','2023-05-12 22:55:00') where command_text like '%student%'; 查询结果如下： 1 2 3 4 5 6 object_name | object_details | result_rows | error_code | command_text ------------------------------------------------------------------+------------------------------------------------------------------------------------------+-------------+------------+------------------------------------------------------------------------------------------------------------------------------------------------------- student | | 0 | | CREATE TABLE student(stuNo int, stuName TEXT); studentscore | | 0 | | CREATE TABLE studentscore(stuNo int, stuscore int); ["public.student_view01","public.studentscore","public.student"] | | 0 | | CREATE OR REPLACE VIEW student_view01 AS SELECT * FROM student t1 where t1.stuNo in (select stuNo from studentscore t2 where t1.stuNo = t2.stuNo); ["public.student_view01","public.student","public.studentscore"] | {"public.student":[{"stuno":"6"},{"stuname":"2"}],"public.studentscore":[{"stuno":"6"}]} | 0 | | SELECT * FROM student_view01 查询结果object_details中显示部分语句执行过程中，涉及到的列及其使用类型，使用json格式进行记录。 使用pg_query_audit_details函数对object_name和object_details列进行解析： 1 SELECT database,object_name,column_name,type_of_use,use_type FROM pg_query_audit_details('2021-02-03 8:00:00','2024-02-03 22:55:00','current') where command_text like '%student%'; 查询结果如下： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 database | object_name | column_name | type_of_use | use_type ----------+-----------------------+-------------+-------------+-------------------- gaussdb | student | | 2 | Access gaussdb | | | 2 | Access gaussdb | studentscore | | 2 | Access gaussdb | | | 2 | Access gaussdb | public.student_view01 | | 2 | Access gaussdb | public.studentscore | | 2 | Access gaussdb | public.student | | 2 | Access gaussdb | | | 2 | Access gaussdb | public.student | stuno | 6 | Access,Conditional gaussdb | public.student | stuname | 2 | Access gaussdb | public.studentscore | stuno | 6 | Access,Conditional gaussdb | public.student_view01 | | 2 | Access gaussdb | public.student | | 2 | Access gaussdb | public.studentscore | | 2 | Access gaussdb | | | 2 | Access (15 rows)

login_audit_messages_pid(flag boolean) 描述：查看登录用户的登录信息。与login_audit_messages的区别在于结果基于当前backendid向前查找。所以不会因为同一用户的后续登录，而影响本次登录的查询结果。也就是查询不到该用户后续登录的信息。 返回值类型：元组 示例： 查看上一次登录认证通过的日期、时间和IP等信息： 1 2 3 4 5 SELECT * FROM login_audit_messages_pid(true); username | database | logintime | type | result | client_conninfo | backendid | session_id ------------+----------+------------------------+---------------+--------+--------------------+----------------------------------------- dbadmin | postgres | 2017-06-02 15:28:34+08 | login_success | ok | gsql@[local] | 140311900702464 | 1663745305.140192538154752.coordinator1 (1 row) 查看上一次登录认证失败的日期、时间和IP等信息： 1 2 3 4 SELECT * FROM login_audit_messages_pid(false) ORDER BY logintime desc limit 1; username | database | logintime | type | result | client_conninfo | backendid | session_id ------------+----------+------------------------+--------------+--------+-------------------------+------------ (0 rows) 查看自从最后一次认证通过以来失败的尝试次数、日期和时间： 1 2 3 4 SELECT * FROM login_audit_messages_pid(false); username | database | logintime | type | result | client_conninfo | backendid | session_id ------------+----------+------------------------+--------------+--------+-------------------------+------------ (0 rows)