系统变量
StarRocks 提供多个系统变量(system variables),方便您根据业务情况进行调整。本文介绍 StarRocks 支持的变量。您可以在 MySQL 客户端通过命令 SHOW VARIABLES 查看当前变量。也可以通过 SET 命令动态设置或 者修改变量。您可以设置变量在系统全局 (global) 范围内生效、仅在当前会话 (session) 中生效、或者仅在单个查询语句中生效。
StarRocks 中的变量参考 MySQL 中的变量设置,但部分变量仅用于兼容 MySQL 客户端协议,并不产生其在 MySQL 数据库中的实际意义。
说明
任何用户都有权限通过 SHOW VARIABLES 查看变量。任何用户都有权限设置变量在 Session 级别生效。只有拥有 System 级 OPERATE 权限的用户才可以设置变量为全局生效。设置全局生效后,后续所有新的会话都会使用新配置,当前会话仍然使用老的配置。
查看变量
可以通过 SHOW VARIABLES [LIKE 'xxx'];
查看所有或指定的变量。例如:
-- 查看系统中所有变量。
SHOW VARIABLES;
-- 查看符合匹配规则的变量。
SHOW VARIABLES LIKE '%time_zone%';
变量层级和类型
StarRocks 支持三种类型(层级)的变量:全局变量、Session 变量和 SET_VAR
Hint。它们的层级关系如下:
- 全局变量在全局级别生效,可以被 Session 变量和
SET_VAR
Hint 覆盖。 - Session 变量仅在当前会话中生效,可以被
SET_VAR
Hint 覆盖。 SET_VAR
Hint 仅在当前查询语句中生效。
设置变量
设置变量全局生效或在会话中生效
变量一般可以设置为全局生效或仅当前会话生效。设置为全局生效后,后续所有新的会话连接中会使用新设置的值,当前会话还会继续使用之前设置的值;设置为仅当前会话生效时,变量仅对当前会话产生作用。
通过 SET <var_name> = xxx;
语句设置的变量仅在当前会话生效。如:
SET query_mem_limit = 137438953472;
SET forward_to_master = true;
SET time_zone = "Asia/Shanghai";
通过 SET GLOBAL <var_name> = xxx;
语句设置的变量全局生效。如:
SET GLOBAL query_mem_limit = 137438953472;
以下变量仅支持全局生效,不支持设置为会话级别生效。您必须使用 SET GLOBAL <var_name> = xxx;
,不能使用 SET <var_name> = xxx;
,否则返回错误。
- activate_all_roles_on_login
- character_set_database
- default_rowset_type
- enable_query_queue_select
- enable_query_queue_statistic
- enable_query_queue_load
- init_connect
- lower_case_table_names
- license
- language
- query_cache_size
- query_queue_fresh_resource_usage_interval_ms
- query_queue_concurrency_limit
- query_queue_mem_used_pct_limit
- query_queue_cpu_used_permille_limit
- query_queue_pending_timeout_second
- query_queue_max_queued_queries
- system_time_zone
- version_comment
- version
Session 级变量既可以设置全局生效也可以设置 session 级生效。
此外,变量设置也支持常量表达式,如 :
SET query_mem_limit = 10 * 1024 * 1024 * 1024;
SET forward_to_master = concat('tr', 'u', 'e');
设置变量在单个查询语句中生效
在一些场景中,可能需要对某些 查询专门设置变量。可以使用 SET_VAR 提示 (Hint) 在查询中设置仅在单个语句内生效的会话变量。
当前,StarRocks 支持在以下语句中使用 SET_VAR
Hint:
- SELECT
- INSERT(自 v3.1.12 和 v3.2.0 起支持)
- UPDATE(自 v3.1.12 和 v3.2.0 起支持)
- DELETE(自 v3.1.12 和 v3.2.0 起支持)
SET_VAR
只能跟在以上关键字之后,必须以 /*+
开头,以 */
结束。
举例:
SELECT /*+ SET_VAR(query_mem_limit = 8589934592) */ name FROM people ORDER BY name;
SELECT /*+ SET_VAR(query_timeout = 1) */ sleep(3);
UPDATE /*+ SET_VAR(query_timeout=100) */ tbl SET c1 = 2 WHERE c1 = 1;
DELETE /*+ SET_VAR(query_mem_limit = 8589934592) */
FROM my_table PARTITION p1
WHERE k1 = 3;
INSERT /*+ SET_VAR(query_timeout = 10000000) */
INTO insert_wiki_edit
SELECT * FROM FILES(
"path" = "s3://inserttest/parquet/insert_wiki_edit_append.parquet",
"format" = "parquet",
"aws.s3.access_key" = "XXXXXXXXXX",
"aws.s3.secret_key" = "YYYYYYYYYY",
"aws.s3.region" = "us-west-2"
);
StarRocks 同时支持在单个语句中设置多个变量,参考如下示例:
SELECT /*+ SET_VAR
(
exec_mem_limit = 515396075520,
query_timeout=10000000,
batch_size=4096,
parallel_fragment_exec_instance_num=32
)
*/ * FROM TABLE;
支持的变量
本节以字母顺序对变量进行解释。带 global
标记的变量为全局变量,仅支持全局生效。其余变量既可以设置全局生效,也可设置会话级别生效。
activate_all_roles_on_login (global)
- 描述:用于控制是否在用户登录时默认激活所有角色(包括默认角色和授予的角色)。
- 开启后,在用户登录时默认激活所有角色,优先级高于通过 SET DEFAULT ROLE 设置的角色。
- 如果不开启,则会默认激活 SET DEFAULT ROLE 中设置的角色。
- 默认值:false,表示不开启。
- 引入版本:v3.0
如果要在当前会话中激活一个角色,可以使用 SET ROLE。
auto_increment_increment
- 描述:用于兼容 MySQL 客户端。无实际作用。
- 默认值:1
- 类型:Int
autocommit
- 描述:用于兼容 MySQL 客户端。无实际作用。
- 默认值:true
chunk_size
用于指定在查询执行过程中,各个节点传输的单个数据包的行数。默认一个数据包的行数为 4096 行,即源端节点每产生 4096 行数据后,打包发给目的节点。较大的行数,会在扫描大数据量场景下提升查询的吞吐率,但可能会在小查询场景下增加查询延迟。同时,也会增加查询的内存开销。建议设置范围 1024 至 4096。
big_query_profile_threshold
-
描述:用于设定大查询的阈值。当会话变量
enable_profile
设置为false
且查询时间超过big_query_profile_threshold
设定的阈值时,则会生成 Profile。NOTE:在 v3.1.5 至 v3.1.7 以及 v3.2.0 至 v3.2.2 中,引入了
big_query_profile_second_threshold
参数,用于设定大查询的阈值。而在 v3.1.8、v3.2.3 及后续版本中,此参数被big_query_profile_threshold
替代,以便提供更加灵活的配置选项。 -
默认值:0
-
单位:秒
-
类型:String
-
引入版本:v3.1
catalog(3.2.4 及以后)
- 描述:用于指定当前会话所在的 Catalog。
- 默认值:default_catalog
- 类型:String
- 引入版本:v3.2.4
cbo_decimal_cast_string_strict
- 描述:用于优化器控制 DECIMAL 类型转为 STRING 类型的行为。取值为
true
时,使用 v2.5.x及之后版本的处理逻辑,执行严格转换(按 Scale 截断补0
);取值为false
时,保留 v2.5.x 之前版本的处理逻辑(按有效数字处理)。默认值是true
。 - 默认值:true
- 引入版本:v2.5.14
cbo_enable_low_cardinality_optimize
- 描述:是否开启低基数全局字典优化。开启后,查询 STRING 列时查询速度会有 3 倍左右提升。
- 默认值:true
cbo_eq_base_type
- 描述:用来指定 DECIMAL 类型和 STRING 类型的数据比较时的强制类型,默认按照
VARCHAR
类型进行比较,可选DECIMAL
(按数值进行比较)。该变量仅在进行=
和!=
比较时生效。 - 类型:String
- 引入版本:v2.5.14
cbo_materialized_view_rewrite_related_mvs_limit
- 描述:用于指定查询在 Plan 阶段最多拥有的候选物化视图个数。
- 默认值:64
- 类型:Int
- 引入版本:v3.1.9, v3.2.5
enable_sync_materialized_view_rewrite
- 描述:是否启用基于同步物化视图的查询改写。
- 默认值:true
- 引入版本:v3.1.11,v3.2.5
enable_datacache_async_populate_mode
- 描述:是否使用异步方式进行 Data Cache 填充。系统默认使用同步方式进行填充,即在查询数据时同步填充进行缓存填充。
- 默认值:false
- 引入版本:v3.2.7
query_including_mv_names
- 描述:指定需要在查询执行过程中包含的异步物化视图的名称。您可以使用此变量来限制候选物化视图的数量,并提高优化器中的查询改写性能。此项优先于
query_excluding_mv_names
生效。 - 默认值:空字符串
- 类型:String
- 引入版本:v3.1.11,v3.2.5
query_excluding_mv_names
- 描述:指定需要在查询执行过程中排除的异步物化视图的名称。您可以使用此变量来限制候选物化视图的数量,并提高优化器中的查询改写性能。
query_including_mv_names
优先于此项生效。 - 默认值:空字符串