系统变量
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 exec_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;
,否则返回错误。
- 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) 在查询中设置仅在单个语句内生效的会话变量。举例:
SELECT /*+ SET_VAR(exec_mem_limit = 8589934592) */ name FROM people ORDER BY name;
SELECT /*+ SET_VAR(query_timeout = 1) */ sleep(3);
注意
SET_VAR
只能跟在 SELECT 关键字之后,必须以/*+
开头,以*/
结束。
StarRocks 同时支持在单个语句中设置多个变量,参考如下示例:
SELECT /*+ SET_VAR
(
exec_mem_limit = 515396075520,
query_timeout=10000000,
batch_size=4096,
parallel_fragment_exec_instance_num=32
)
*/ * FROM TABLE;
支持的变量
本节以字母顺序对变量进行解释。带 global
标记的变量为全局变量,仅支持全局生效。其余变量既可以设置全局生效,也可设置会话级别生效。
auto_increment_increment
用于兼容 MySQL 客户端。无实际作用。默认值为 1。
autocommit
用于兼容 MySQL 客户端。无实际作用。默认值为 true。
batch_size
用于指定在查询执行过程中,各个节点传输的单个数据包的行数。默认一个数据包的行数为 1024 行,即源端节点每产生 1024 行数据后,打包发给目的节点。较大的行数,会在扫描大数据量场景下提升查询的吞吐率,但可能会在小查询场景下增加查询延迟。同时,也会增加查询的内存开销。建议设置范围 1024 至 4096。
cbo_enable_low_cardinality_optimize
是否开启低基数全局字典优化。开启后,查询 STRING 列时查询速度会有 3 倍左右提升。默认值:true。
cbo_eq_base_type (2.5.14 及以后)
用来指定 DECIMAL 类型和 STRING 类型的数据比较时的强制类型,默认按照 VARCHAR
类型进行比较,可选 DECIMAL
(按数值进行比较)。
character_set_database(global)
StarRocks 数据库支持的字符集,当前仅支持 UTF8 编码 (utf8
)。
connector_io_tasks_per_scan_operator(2.5 及以后)
外表查询时每个 Scan 算子能同时下发的 I/O 任务的最大数量。取值为整数,默认值 16。目前外表查询时会使用自适应算法来调整并发 I/O 任务的数量,通过 enable_connector_adaptive_io_tasks
开关来控制,默认打开。
count_distinct_column_buckets(2.5 及以后)
group-by-count-distinct 查询中为 count distinct 列设置的分桶数。该变量只有在 enable_distinct_column_bucketization
设置为 true
时才会生效。默认值:1024。
default_rowset_type (global)
全局变量,仅支持全局生效。用于设置计算节点存储引擎默认的存储格式。当前支持的存储格式包括:alpha/beta。
disable_colocate_join
控制是否启用 Colocate Join 功能。默认为 false,表示启用该功能。true 表示禁用该功能。当该功能被禁用后,查询规划将不会尝试执行 Colocate Join。
disable_streaming_preaggregations
控制是否开启流式预聚合。默认为 false
,即开启。
div_precision_increment
用于兼容 MySQL 客户端,无实际作用。
enable_connector_adaptive_io_tasks(2.5 及以后)
外表查询时是否使用自适应策略来调整 I/O 任务的并发数。默认打开。如果未开启自适应策略,可以通过 connector_io_tasks_per_scan_operator
变量来手动设置外表查询时的 I/O 任务并发数。
enable_distinct_column_bucketization(2.5 及以后)
是否在 group-by-count-distinct 查询中开启对 count distinct 列的分桶优化。在类似 select a, count(distinct b) from t group by a;
的查询中,如果 group by 列 a 为低基数列,count distinct 列 b 为高基数列且发生严重数据倾斜时,会引发查询性能瓶颈。可以通过对 count distinct 列进行分桶来平衡数据,规避数据倾斜。
默认值:false,表示不开启。该变量需要与 count_distinct_column_buckets
配合使用。
您也可以通过添加 skew
hint 来开启 count distinct 列的分桶优化,例如 select a,count(distinct [skew] b) from t group by a;
。
enable_insert_strict
用于设置通过 INSERT 语句进行数据导入时,是否开启严格模式 (Strict Mode)。默认为 true
,即开启严格模式。关于该模式的介绍,可以参阅严格模式。
enable_materialized_view_for_insert
- 含义:是否允许 StarRocks 改写 INSERT INTO SELECT 语句中的查询。
- 默认值:false,即默认关闭该场景下的物化视图查询改写。
- 引入版本:v2.5.18, v3.0.9, v3.1.7, v3.2.2
enable_materialized_view_union_rewrite(2.5 及以后)
是否开启物化视图 Union 改写。默认值:true
。
enable_rule_based_materialized_view_rewrite(2.5 及以后)
是否开启基于规则的物化视图查询改写功能,主要用于处理单表查询改写。默认值:true
。
enable_strict_order_by
是否校验 ORDER BY 引用列是否有歧义。设置为默认值 TRUE
时,如果查询中的输出列存在不同的表达式使用重复别名的情况,且按照该别名进行排序,查询会报错,例如 select distinct t1.* from tbl1 t1 order by t1.k1;
。该行为和 2.3 及之前版本的逻辑一致。如果取值为 FALSE
,采用宽松的去重机制,把这类查询作为有效 SQL 处理。
该变量从 2.5.18,3.1.7 版本开始支持。
enable_profile
用于设置是否需要查看查询的 profile。默认为 false
,即不需要查看 profile。2.5 版本之前,该变量名称为 is_report_success
,2.5 版本之后更名为 enable_profile
。
默认情况下,只有在查询发生错误时,BE 才会发送 profile 给 FE,用于查看错误。正常结束的查询不会发送 profile。发送 profile 会产生一定的网络开销,对高并发查询场景不利。当用户希望对一个查询的 profile 进行分析时,可以将这个变量设为 true
后,发送查询。查询结束后,可以通过在当前连接的 FE 的 web 页面(地址:fe_host:fe_http_port/query)查看 profile。该页面会显示最近 100 条开启了 enable_profile
的查询的 profile。
enable_query_queue_load (global)
布尔值,用于控制是否为导入任务启用查询队列。默认值:false
。
enable_query_queue_select (global)
布尔值,用于控制是否为 SELECT 查询启用查询队列。默认值:false
。
enable_query_queue_statistic (global)
布尔值,用于控制是否为统计信息查询启用查询队列。默认值:false
。
enable_query_tablet_affinity(2.5 及以后)
布尔值,用于控制在多次查询同一个 tablet 时是否倾向于选择固定的同一个副本。
如果待查询的表中存在大量 tablet,开启该特性会对性能有提升,因为会更快的将 tablet 的元信息以及数据缓存在内存中。但是,如果查询存在一些热点 tablet,开启该特性可能会导致性能有所退化,因为该特性倾向于将一个热点 tablet 的查询调度到相同的 BE 上,在高并发的场景下无法充分利用多台 BE 的资源。
默认值:false
,表示使用原来的机制,即每次查询会从多个副本中选择一个。自 2.5.6、3.0.8、3.1.4 版本起,StarRocks 支持该参数。
enable_scan_block_cache(2.5 及以后)
是否开启 Data Cache 特性。该特性开启之后,StarRocks 通过将外部存储系统中的热数据缓存成多个 block,加速数据查询和分析。更多信息,参见 Data Cache。该特性从 2.5 版本开始支持。