华为云用户手册

参数说明 no表示hint的stream方式不使用，当指定AGG分布列的hint时指定no关键字无效。 block_name表示语句块的block_name，详细说明请参考block_name。 table_list为进行stream操作的单表或多表join结果集，见参数说明。 当指定分布列的hint时，*为固定写法，不支持指定表名。 columns指定group by子句中的一个或者多个列，没有group by子句也可以指定distinct子句中的列。 指定的分布列，需要用group by或distinct中的列序号或列名来表示，count（distinct）中的列只能通过列名指定。 对于多层的查询，可以在每层指定对应层的分布列hint，只在当前层生效。 指定的count(distinct)列仅针对生成双层hashagg的计划时才生效，否则指定的分布列无效。 指定了分布列，如果优化器估算后发现不需要重分布，则指定的分布列无效。

示例 对示例中原语句使用如下hint： 1 2 explain select /*+ no redistribute(store_sales store_returns item store) leading(((store_sales store_returns item store) customer)) */ i_product_name product_name ... 原计划中，(store_sales store_returns item store)和customer做join时，前者做了重分布，此hint表示禁止前者混合表做重分布，但仍然保持join顺序，则生成计划如下所示：

建议 通常优化器会根据统计信息选择一组不倾斜的分布键进行数据重分布。当默认选择的分布键有倾斜时，可以手动指定重分布的列，避免数据倾斜。 在选择分布键的时候，通常要根据数据分布特征选取一组distinct值比较高的列作为分布列，这样可以保证重分布后，数据均匀的分布到各个DN。 在编写好hint后，可以通过explain verbose+SQL打印执行计划，查看指定的分布键是否有效，如果指定的分布键无效会有warning提示。

创建Iceberg External表 通过CREATE EXTERNAL TABLE语法创建Iceberg表。与一般EXTERNAL表相比，创建Iceberg EXTERNAL表没有特别的参数需要指定，只需要指定STORE AS ICEBERG即可。具体语法可参见CREATE EXTERNAL TABLE。 当前创建Iceberg External表仅支持创建V2表。 示例： 1 2 3 4 5 6 7 8 9 CREATE EXTERNAL TABLE iceberg_ext( col1 int, col2 varchar(20), ... )PARTITION BY (col3 bigint) TABLEPROPERTIES ( 'write.metadata.delete-after-commit.enabled'='true'， 'write.metadata.previous-versions-max' = '10' ) STORE AS ICEBERG; 其中write.metadata.delete-after-commit.enabled控制是否在提交事务后删除旧版本元数据文件，默认情况为false。true的情况下，可以通过write.metadata.previous-versions-max设定保留多少个metadata。 使用这两个参数需要谨慎，虽然删除元数据文件可以节省存储空间，但需要确保不会影响数据的一致性和可用性。

generate_series(start, stop, step interval) 描述：生成一个数值序列，从start到stop，步长为step。 参数类型：timestamp或timestamp with time zone 返回值类型：setof timestamp或setof timestamp with time zone（与参数类型相同） 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 --这个示例应用于date-plus-integer操作符。 SELECT current_date + s.a AS dates FROM generate_series(0,14,7) AS s(a); dates ------------ 2017-06-02 2017-06-09 2017-06-16 (3 rows) SELECT * FROM generate_series('2008-03-01 00:00'::timestamp, '2008-03-04 12:00', '10 hours'); generate_series --------------------- 2008-03-01 00:00:00 2008-03-01 10:00:00 2008-03-01 20:00:00 2008-03-02 06:00:00 2008-03-02 16:00:00 2008-03-03 02:00:00 2008-03-03 12:00:00 2008-03-03 22:00:00 2008-03-04 08:00:00 (9 rows)

generate_series(start, stop) 描述：生成一个数值序列，从start到stop，步长默认为1。 参数类型：int、bigint、numeric 返回值类型：setof int、setof bigint、setof numeric（与参数类型相同） 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 SELECT * FROM generate_series(2,4); generate_series ----------------- 2 3 4 (3 rows) SELECT * FROM generate_series(4,3); generate_series ----------------- (0 rows) SELECT * FROM generate_series(1,NULL); generate_series ----------------- (0 rows)

generate_series(start, stop, step) 描述：生成一个数值序列，从start到stop，步长为step。 参数类型：int、bigint、numeric 返回值类型：setof int、setof bigint、setof numeric（与参数类型相同） 示例： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 SELECT * FROM generate_series(5,1,-2); generate_series ----------------- 5 3 1 (3 rows) SELECT * FROM generate_series(4,6,-5); generate_series ----------------- (0 rows) SELECT * FROM generate_series(4,3,0); ERROR: step size cannot equal zero

|| 描述：将两个tsquery类型的词汇进行“或”操作 示例： 1 2 3 4 5 6 7 8 9 10 SELECT 'fat | rat'::tsquery || 'cat'::tsquery AS RESULT; result --------------------------- ( 'fat' | 'rat' ) | 'cat' (1 row) SELECT 'a:1 b:2'::tsvector || 'c:1 d:2 b:3'::tsvector AS RESULT; result --------------------------- 'a':1 'b':2,5 'c':3 'd':4 (1 row)

示例 定义一个求和的函数： 1 2 3 4 5 6 7 8 9 10 11 CREATE FUNCTION your_schema.func_add(integer, integer) RETURNS integer LANGUAGE python python_version='3.9' handler = 'sum' IMMUTABLE STRICT AS $$ def sum(x,y): return x+y $$;

参数说明 表1 CREATE FUNCTION参数说明 参数 描述 取值范围 function_name 要创建的函数名字（可以用模式修饰）。 取值范围：字符串，要符合标识符的命名规范。 须知： 如果创建的函数名与系统函数同名，建议指定schema。调用自定义函数时需指定schema，否则系统会优先调用系统函数。 argname 函数参数的名字。 取值范围：字符串，要符合标识符的命名规范。 argtype 函数参数的类型。 - rettype 函数返回值的数据类型。 - LANGUAGE lang_name 用于实现函数的语言的名字。自定义函数仅支持python。 - IMMUTABLE 表示该函数在给出同样的参数值时总是返回同样的结果。 如果函数的入参是常量，会在优化器阶段计算该函数的值。益处是可以尽早获取表达式的值，从而能更准确地进行代价估算，生成的执行计划也更优。 用户自定义的IMMUTABLE的函数是会被自动下推到DN执行的，但是这样可能有潜在的风险，即如果用户错误定义了函数的IMMUTABLE属性，但是函数执行的过程并不是IMMUTABLE的，那么可能会导致结果错误等严重问题。因此，用户在指定函数的属性为IMMUTABLE的时候，要特别慎重。 举例如下： 如果自定义函数中有不下推的因素，则该函数不能定义成IMMUTABLE，因为IMMUTABLE意味着要下推到DN执行，与函数内部的不下推因素相互冲突。典型场景例如，包含不下推的函数、语法等。 如果自定义函数中含有聚合运算，但聚合运算的运算需要生成STREAM计划才能完成计算的（部分结果在DN计算，部分结果在CN计算，例如listagg函数等）。 STABLE 表示该函数不能修改数据库，对相同参数值，在同一次表扫描里，该函数的返回值不变，但是返回值可能在不同SQL语句之间变化。 - VOLATILE 表示该函数值可以在一次表扫描内改变，因此不会做任何优化。 - SHIPPABLE NOT SHIPPABLE 表示该函数是否可以下推到DN上执行。 对于IMMUTABLE类型的函数，函数始终可以下推到DN上执行。 对于STABLE/VOLATILE类型的函数，仅当函数的属性是SHIPPABLE的时候，函数可以下推到DN执行。 用户在定义函数的SHIPPABLE属性时也需特别慎重，SHIPPABLE意味着整个函数会下推到DN上执行，如果设置不当，会导致结果错误等严重问题。 与定义IMMUTABLE属性一样，SHIPPABLE属性的定义也有诸多约束，简单来说就是函数内不能有不可下推的因素，函数下推到单DN执行后，函数内部的计算逻辑仅依赖当前DN的数据集合。 举例如下： 函数内部有不可下推的因素，函数，语法等，那么该函数不能定义为SHIPPABLE，可参考语句下推调优。 函数内部的计算过程可能需要跨DN数据，这种情况该函数通常不能定义为SHIPPABLE，例如一些聚合运算等。 PACKAGES 表示该函数运行时环境所依赖的python三方包。 - PYTHON_VERSION 表示函数运行时环境的python的具体版本。当前仅支持指定为3.9和3.11。 - HANDLER 表示函数的主函数入口。 - STRICT STRICT用于指定如果函数的某个参数是NULL，此函数总是返回NULL。如果声明了这个参数，当有NULL值参数时该函数不会被执行；而只是自动返回一个NULL结果。 - definition 函数体的具体实现。 -

使用注意事项 如果创建函数时参数或返回值带有精度，不进行精度检测。 仅支持scalar udf，不支持udtf和udaf，且函数语言仅支持python。 udf运行时环境的python版本为python3.9和python3.11，具体版本是在DDL时指定，仅支持python3.9和3.11，理论上udf的具体函数体的代码实现小于等于DDL时指定的python版本，都可兼容。 udf的三方依赖包列表需要保证lib间的兼容性，udf的依赖包路径，仅支持添加一个，即所有的udf依赖的文件，都需要在一个压缩包里，目前仅支持tar、zip格式。 UDF入参和返回值的类型都仅支持基本数据类型，参数暂不支持设置默认值。 AS和IMPORTS两者必须定义一个，且不能同时都定义。

语法格式 创建自定义函数语法。 1 2 3 4 5 6 7 8 9 10 11 12 CREATE [ OR REPLACE ] FUNCTION function_name ( [ { argname argtype } ] [, ...] ] ) [ RETURNS rettype ] LANGUAGE lang_name [ { IMMUTABLE | STABLE | VOLATILE } ] [ { SHIPPABLE | NOT SHIPPABLE } ] PYTHON_VERSION = { 'version' } HANDLER = 'function_name' [ STRICT ] [ PACKAGES = ( 'package_name==[version]' [ , ...] ) ] [ IMPORTS = ( 'obs_file_path' ) ] [ AS 'definition' ]

查看和设置GUC参数 在Fabric SQL中，用户只能以SQL语句方式执行SET命令来设置GUC参数。具体格式如下 1 SET paramName TO paramValue; 例如：用户设置语句超时statement_timeout参数，可以在通过REST API接口发送SET statement_timeout TO 600 设置为10分钟。 如果用户要查看设置的GUC参数的值，可以通过SHOW语句来查看本Session设置的GUC参数值。例如： SHOW statement_timeout； 语句可以查询设置的语句超时值。

参数类型和值 所有的参数名称不区分大小写。 参数取值有整型、浮点型、字符串、布尔型和枚举型五类。 布尔值可以是（on，off）、（true，false）、（yes，no）或者（1，0），且不区分大小写。 枚举类型的取值由系统视图pg_settings的enumvals字段取值所定义。 对于有单位的参数，在设置时请指定单位，否则将使用默认的单位。 参数的默认单位由系统视图pg_settings的unit字段所定义。 内存单位有：KB（千字节）、MB（兆字节）和GB（吉字节）。 时间单位：ms（毫秒）、s（秒）、min（分钟）、h（小时）和d（天）。

应用示例 查询指定函数的OID。例如，获取函数justify_days的OID为1295。 1 2 3 4 5 SELECT oid FROM pg_proc where proname ='justify_days'; oid ------ 1295 (1 row) 查询指定函数是否为聚集函数。例如，查询justify_days函数为非聚集函数。 1 2 3 4 5 SELECT proisagg FROM pg_proc where proname ='justify_days'; proisagg ---------- f (1 row)

参数说明 IF NOT EXISTS 如果存在同名表，则发出一个notice而不是抛出一个错误。 schema_name 表所属的数据库名，如果未指定数据库名时，则将在current_schema下建表。 table_name 创建表的表名，表名长度不可超过63个字符。 col_name 创建表的列名，列名长度不可超过63个字符。普通列和分区列的数量总和不可超过5000个。 col_type 创建表的列类型，列类型支持范围如下： 列类型 是否可以声明为分区列 是否支持ORC格式 是否支持PARQUET格式 是否支持Iceberg格式 SmallInt √ √ √ √ Int √ √ √ √ BigInt √ √ √ √ Float × √ √ √ Double × √ √ √ Decimal √ √ √ √ Numeric √ √ √ √ Timestamp √ √ √ √ Date √ √ √ √ Varchar √ √ √ √ Char √ √ √ √ Bool × √ √ √ Bytea × √ √ √ Text √ √ √ √ col_comment 列注释信息，可指定为任意字符串。 table_comment 表注释信息，可指定为任意字符串。 bucket_num bucket个数。 option_key = option_value 表级别参数设置，支持参数范围如下： 表1 option_key参数支持范围 option_key option_value 说明 适用范围 orc.compress zlib, snappy, lz4 ORC文件压缩方式。 ORC parquet.compression zlib, snappy, lz4 PARQUET文件压缩方式。 PARQUET julian_adjust true, false 是否转换为Julian日期。 PARQUET checkencoding high, low, no 是否检查字符编码。 ORC, PARQUET column_index_access true, false 读取时表定义列和文件列匹配方式，默认true为列索引匹配，false为列名匹配。 ORC, PARQUET filesize 1~1024的证书 生成外表文件大小。 ORC, PARQUET write.delete.mode copy-on-write, merge-on-read 设置delete时的模式：cow或mor。 Iceberg write.update.mode copy-on-write, merge-on-read 设置update时的模式：cow或mor。 write.merge.mode copy-on-write, merge-on-read 设置merge时的模式：cow或mor。 write.parquet.compression-codec zstd, zlib, lz4, snappy, gzip parquet文件的压缩方式。 write.merge.isolation-level snapshot, serializable merge命令的隔离级别。 write.metadata.delete-after-commit.enabled true, false 控制提交后是否删除最旧的跟踪版本元数据文件。 write.update.isolation-level snapshot, serializable update命令的隔离级别。 write.delete.isolation-level snapshot, serializable delete命令的隔离级别。 write.metadata.previous-versions-max 大于0的整数 要保留的旧元数据文件的数 table_format 表存储格式，支持ORC、PARQUET、ICEBERG三种存储格式。 table_path 表存储路径，必须为合法OBS路径，支持OBS对象桶和并行文件系统。如果该路径为OBS对象桶路径，则该表只读，否则该表支持读写。 select_stmt 查询语句。

语法格式 1 2 3 4 5 6 7 8 9 CREATE EXTERNAL TABLE [ IF NOT EXISTS ] [schema_name.]table_name [ ( col_name col_type [ COMMENT col_comment ] [, ... ] ) ] [ COMMENT table_comment ] [ PARTITION BY ( col_name col_type COMMENT col_comment [, ... ] ) ] [ CLUSTERED BY (col_name [,...]) INTO ( bucket_num ) BUCKETS ] [ TABLEPROPERTIES ( option_key = option_value [, ... ] ) ] [ STORE AS table_format ] [ LOCATION table_path ] AS select_stmt;

调优流程 调优流程如图1所示。 图1 Fabric SQL性能调优流程 调优各阶段说明，如表1所示。 表1 Fabric SQL性能调优流程说明 阶段 描述 系统调优 进行系统级的调优，更充分地利用机器的CPU、内存、I/O和网络资源，提升查询的吞吐量。 SQL调优 审视业务所用SQL语句是否存在可优化空间，包括： 通过ANALYZE语句生成表统计信息：ANALYZE语句可收集与数据库中表内容相关的统计信息，统计结果存储在系统表PG_STATISTIC中。执行计划生成器会使用这些统计数据，以确定最有效的执行计划。 分析执行计划：EXPLAIN语句可显示SQL语句的执行计划，EXPLAIN PERFORMANCE语句可显示SQL语句中各算子的执行时间。 查找问题根因并进行调优：通过分析执行计划，找到可能存在的原因，进行针对性的调优，通常为调整数据库级SQL调优参数。 编写更优的SQL：介绍一些复杂查询中的中间临时数据缓存、结果集缓存、结果集合并等场景中的更优SQL语法。

javax.sql.DataSource javax.sql.DataSource是数据源接口。 表1 对javax.sql.DataSource接口的支持情况 方法名 返回值类型 支持JDBC 4 getConneciton() Connection Yes getConnection(String username,String password) Connection Yes getLoginTimeout() int Yes getLogWriter() PrintWriter Yes setLoginTimeout(int seconds) void Yes setLogWriter(PrintWriter out) void Yes 父主题： JDBC接口参考

二进制类型 Fabric SQL支持的二进制类型请参见表1。 表1 二进制类型 名称 描述 存储空间 BYTEA 变长的二进制字符串 4字节加上实际的二进制字符串。最大为1G-8023B（即1073733621B）。 除了每列的大小限制以外，每个元组的总大小也不可超过1G-8203字节。 示例 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 --创建表。 CREATE EXTERNAL TABLE binary_type_t1 ( BT_COL1 INTEGER, BT_COL2 BYTEA ) STORE AS orc; --插入数据。 INSERT INTO binary_type_t1 VALUES(10, E'\\xDEADBEEF'); --查询表中的数据。 SELECT * FROM binary_type_t1; bt_col1 | bt_col2 ---------+------------ 10 | \xdeadbeef (1 row) --删除表。 DROP TABLE binary_type_t1; 父主题： 数据类型

PG_ATTRDEF PG_ATTRDEF系统表存储字段的默认值。 表1 PG_ATTRDEF字段 名称 类型 描述 adrelid oid 该字段所属的表。 adnum smallint 字段编号。 adbin pg_node_tree 字段缺省值的内部表现形式。 adsrc text 人类可读的缺省值的内部表现形式。 adbin_on_update pg_node_tree 字段on_update_expr值的内部表现形式。 adsrc_on_update text 人类可读的on_update_expr值的内部表现形式。 父主题： 系统表

pg_collation_actual_version (oid) 描述：返回当前安装在操作系统中的该排序规则对象的实际版本，目前仅对case_insensitive有效。 返回值类型：text 示例： 1 2 3 4 5 6 7 8 9 10 11 SELECT oid FROM pg_collation WHERE collname ='case_insensitive'; oid ------ 3300 (1 row) SELECT pg_collation_actual_version(3300); pg_collation_actual_version ----------------------------- 153.14 (1 row)

示例 显示用字母t和f输出boolean值。 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 --创建表。 CREATE EXTERNAL TABLE bool_type_t1 ( BT_COL1 BOOLEAN, BT_COL2 TEXT ) STORE AS orc; --插入数据。 INSERT INTO bool_type_t1 VALUES (TRUE, 'sic est'); INSERT INTO bool_type_t1 VALUES (FALSE, 'non est'); --查看数据。 SELECT * FROM bool_type_t1; bt_col1 | bt_col2 ---------+--------- t | sic est f | non est (2 rows) SELECT * FROM bool_type_t1 WHERE bt_col1 = 't'; bl_col1 | bt_col2 ---------+--------- t | sic est (1 row) --删除表。 DROP TABLE bool_type_t1;

pg_shared_chunk_dump(contextname char(64)) 描述：将指定共享内存下内存上下文申请的所有chunk信息打印成文件。 参数contextname，表示内存上下文名称。 返回值类型：boolean 示例： 1 2 3 4 5 SELECT * FROM pg_shared_chunk_dump('pgstat file hash table'); pg_shared_chunk_dump ---------------------- t (1 row)

pv_session_chunk_dump(tid int, contextname char(64)) 描述：将指定线程创建的某个内存上下文申请的所有chunk信息打印成文件。 参数tid，表示线程ID；参数contextname，表示内存上下文名称。 返回值类型：boolean 示例： 1 2 3 4 5 SELECT * FROM pv_session_chunk_dump(140472797325280, 'Timezones'); pv_session_chunk_dump ----------------------- t (1 row)

pv_session_chunk_detail(tid int, contextname char(64)) 描述：查询指定线程创建的某个内存上下文申请的所有chunk信息。 参数tid，表示线程ID；参数contextname，表示内存上下文名称。 使用该函数需使用pv_session_chunk_dump(tid int, contextname char(64))函数将相关信息打印成文件。 返回值类型：record 示例： 1 2 3 4 5 6 7 8 9 SELECT * FROM pv_session_chunk_detail(140178810990936, 'Timezones'); parent | level | file_name | line_number | chunk_size | requested_number | total_size ------------------+-------+---------------+-------------+------------+------------------+------------ TopMemoryContext | 1 | dynahash.cpp | 158 | 1280 | 2 | 2560 TopMemoryContext | 1 | dynahash.cpp | 158 | 160 | 1 | 160 TopMemoryContext | 1 | dynahash.cpp | 158 | 2560 | 2 | 5120 TopMemoryContext | 1 | localtime.cpp | 1965 | 128 | 1 | 128 TopMemoryContext | 1 | localtime.cpp | 1965 | 448 | 1 | 448 (5 rows)

pg_shared_chunk_detail(contextname char(64)) 描述：查询指定共享内存下内存上下文申请的所有chunk信息。 参数contextname，表示内存上下文名称。 使用该函数需先使用pg_shared_chunk_dump(contextname char(64))函数将相关信息打印成文件。 返回值类型：record 示例： 1 2 3 4 5 6 7 8 SELECT * FROM pg_shared_chunk_detail('pgstat file hash table'); parent | level | file_name | line_number | chunk_size | requested_number | total_size ---------------------+-------+--------------+-------------+------------+------------------+------------ pgstat file context | 2 | dynahash.cpp | 158 | 2048 | 1 | 2048 pgstat file context | 2 | dynahash.cpp | 158 | 256 | 1 | 256 pgstat file context | 2 | dynahash.cpp | 158 | 4096 | 9 | 36864 pgstat file context | 2 | dynahash.cpp | 158 | 8192 | 4 | 32768 (4 rows)

javax.sql.PooledConnection javax.sql.PooledConnection是由连接池创建的连接接口。 表1 对javax.sql.PooledConnection的支持情况 方法名 返回值类型 支持JDBC 4 addConnectionEventListener (ConnectionEventListener listener) void Yes close() void Yes getConnection() Connection Yes removeConnectionEventListener (ConnectionEventListener listener) void Yes addStatementEventListener (StatementEventListener listener) void Yes removeStatementEventListener (StatementEventListener listener) void Yes 父主题： JDBC接口参考

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)