系统变量
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) 在查询中设置仅在单个语句内生效的会话变量。举例:
SELECT /*+ SET_VAR(query_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
标记的变量为全局变量,仅支持全局生效。其余变量既可以设置全局生效,也可设置会话级别生效。
activate_all_roles_on_login(global)(3.0 及以后)
用于控制是否在用户登录时默认激活所有角色(包括默认角色和授予的角色)。
-
开启后,在用户登录时默认激活所有角色,优先级高于通过 SET DEFAULT ROLE 设置的角色。
-
如果不开启,则会默认激活 SET DEFAULT ROLE 中设置的角色。
默认值:false,表示不开启。
如果要在当前会话中激活一个角色,可以使用 SET ROLE。
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。
default_table_compression (3.0 及以后)
存储表格数据时使用的 默认压缩算法,支持 LZ4、Zstandard(或 zstd)、zlib 和 Snappy。默认值:lz4_frame。如果您建表时在 PROPERTIES 设置了 compression
,则 compression
指定的压缩算法生效。
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_spill(3.0 及以后)
是否启用中间结果落盘。默认值:false
。如果将其设置为 true
,StarRocks 会将中间结果落盘,以减少在查询中处理聚合、排序或连接算子时的内存使用量。
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 版本起,StarRocks 支持该参数。
enable_scan_block_cache(2.5 及以后)
是否开启 Data Cache 特性。该特性开启之后,StarRocks 通过将外部存储系统中的热数据缓存成多个 block,加速数据查询和分析。更多信息,参见 Data Cache。该特性从 2.5 版本开始支持。
enable_populate_block_cache(2.5 及以后)
StarRocks 从外部存储系统读取数据时,是否将数据进行缓存。如果只想读取,不进行缓存,可以将该参数设置为 false
。默认值为 true
。
enable_tablet_internal_parallel
是否开启自适应 Tablet 并行扫描,使用多个线程并行分段扫描一个 Tablet,可以减少 Tablet 数量对查询能力的限制。默认值为 true
。自 2.3 版本起,StarRocks 支持该参数。
enable_query_cache (2.5 及以后)
是否开启 Query Cache。取值范围:true 和 false。true 表示开启,false 表示关闭(默认值)。开启该功能后,只有当查询满足Query Cache 所述条件时,才会启用 Query Cache。
enable_adaptive_sink_dop (2.5 及以后)
是否开启导入自适应并行度。开启后 INSERT INTO 和 Broker Load 自动设置导入并行度,保持和 pipeline_dop
一致。新部署的 2.5 版本默认值为 true
,从 2.4 版本升级上来为 false
。
enable_pipeline_engine
是否启用 Pipeline 执行引擎。true:启用(默认),false:不启用。
enable_sort_aggregate (2.5 及以后)
是否开启 sorted streaming 聚合。true
表示开启 sorted streaming 聚合功能,对流中的数据进行排序。
enable_global_runtime_filter
Global runtime filter 开关。Runtime Filter(简称 RF)在运行时对数据进行过滤,过滤通常发生在 Join 阶段。当多表进行 Join 时,往往伴随着谓词下推等优化手段进行数据过滤,以减少 Join 表的数据扫描以及 shuffle 等阶段产生的 IO,从而提升查询性能。StarRocks 中有两种 RF,分别是 Local RF 和 Global RF。Local RF 应用于 Broadcast Hash Join 场景。Global RF 应用于 Shuffle Join 场景。
默认值 true
,表示打开 global runtime filter 开关。关闭该开关后, 不生成 Global RF, 但是依然会生成 Local RF。
enable_multicolumn_global_runtime_filter
多列 Global runtime filter 开关。默认值为 false,表示关闭该开关。
对于 Broadcast 和 Replicated Join 类型之外的其他 Join,当 Join 的等值条件有多个的情况下:
- 如果该选项关闭: 则只会产生 Local RF。
- 如果该选项打开, 则会生成 multi-part GRF, 并且该 GRF 需要携带 multi-column 作为 partition-by 表达式.
event_scheduler
用于兼容 MySQL 客户端。无实际作用。
force_streaming_aggregate
用于控制聚合节点是否启用流式聚合计算策略。默认为 false,表示不启用该策略。
forward_to_master
用于设置是否将一些命令转发到 Leader FE 节点执行。默认为 false,即不转发。StarRocks 中存在多个 FE 节点,其中一个为 Leader 节点。通常用户可以连接任意 FE 节点进行全功能操作。但部分信息查看指令只有从 Leader FE 节点才能获取详细信息。
如 SHOW BACKENDS;
命令,如果不转发到 Leader FE 节点,则仅能看到节点是否存活等一些基本信息,而转发到 Leader FE 则可以获取包括节点启动时间、最后一次心跳时间等更详细的信息。
当前受该参数影响的命令如下:
-
SHOW FRONTENDS;
转发到 Leader 可以查看最后一次心跳信息。
-
SHOW BACKENDS;
转发到 Leader 可以查看启动时间、最后一次心跳信息、磁盘容量信息。
-
SHOW BROKER;
转发到 Leader 可以查看启动时间、最后一次心跳信息。
-
SHOW TABLET;
-
ADMIN SHOW REPLICA DISTRIBUTION;
-
ADMIN SHOW REPLICA STATUS;
转发到 Leader 可以查看 Leader FE 元数据中存储的 tablet 信息。正常情况下,不同 FE 元数据中 tablet 信息应该是一致的。当出现问题时,可以通过这个方法比较当前 FE 和 Leader FE 元数据的差异。
-
SHOW PROC;
转发到 Leader 可以查看 Leader FE 元数据中存储的相关 PROC 的信息。主要用于元数据比对。
group_concat_max_len
group_concat 函数返回的字符串的最大长度,单位为字符. 默认值 :1024。最小值:4。
hash_join_push_down_right_table
用于控制在 Join 查询中是否可以使用针对右表的过滤条件来过滤左表的数据,可以减少 Join 过程中需要处理的左表的数据量。取值为 true 时表示允许该操作,系统将根据实际情况决定是否能对左表进行过滤;取值为 false 表示禁用该操作。默认值为 true。
init_connect (global)
用于兼容 MySQL 客户端。无实际作用。
interactive_timeout
用于兼容 MySQL 客户端。无实际作用。
io_tasks_per_scan_operator (2.5 及以后)
每个 Scan 算子能同时下发的 I/0 任务的数量。如果使用远端存储系统(比如 HDFS 或 S3)且时延较长,可以增加该值。但是值过大会增加内存消耗。
取值为整数。默认值:4。