Query queues
This topic describes how to manage query queues in StarRocks.
From v2.5, StarRocks supports query queues. With query queues enabled, StarRocks automatically queues the incoming queries when the concurrency threshold or resource limit is reached, thereby avoiding the overload deteriorating. Pending queries wait in a queue until there is enough compute resources available to begin execution.
The Query Queue feature has two versions:
- Query Queue v1: Triggers queuing based on query concurrency, BE memory usage, and BE CPU usage. The original query queue configurations and behaviors in this topic belong to v1. From v3.1.4 onwards, v1 supports setting query queues on the resource group level.
- Query Queue v2: Supported from v3.3 onwards. v2 estimates the BE resources consumed by each query, represents BE resources as logical slots, and queues and schedules queries based on the number of slots each query needs.
Query Queue v1
Query Queue v1 supports setting thresholds on CPU usage, memory usage, and query concurrency to trigger query queues.
Roadmap:
| Version | Global query queue | Resource group-level query queue | Collective concurrency management | Dynamic concurrency adjustment |
|---|---|---|---|---|
| v2.5 | ✅ | ❌ | ❌ | ❌ |
| v3.1.4 | ✅ | ✅ | ✅ | ✅ |
Enable Query Queue v1
Query queues are disabled by default. You can enable global or resource group-level query queues for INSERT loading, SELECT queries, and statistics queries by setting corresponding global session variables.
Enable global query queues
- Enable query queues for loading tasks:
SET GLOBAL enable_query_queue_load = true;
- Enable query queues for SELECT queries:
SET GLOBAL enable_query_queue_select = true;
- Enable query queues for statistics queries:
SET GLOBAL enable_query_queue_statistic = true;
Enable resource group-level query queues
From v3.1.4 onwards, StarRocks supports setting query queues on the resource group level.
To enable the resource group-level query queues, you also need to set enable_group_level_query_queue in addition to the global session variables mentioned above.
SET GLOBAL enable_group_level_query_queue = true;
In shared-data clusters, these global session variables do not enable query queues. Query queues are enabled for each warehouse separately, and enable_group_level_query_queue takes effect only after the warehouse property enable_query_queue is set to true. See Query Queue v2 in shared-data clusters.
Specify resource thresholds
Specify resource thresholds for global query queues
You can set the thresholds that trigger query queues via the following global session variables:
| Variable | Default | Description |
|---|---|---|
| query_queue_concurrency_limit | 0 | The upper limit of concurrent queries on a BE. It takes effect only after being set greater than 0. Setting it to 0 indicates no limit is imposed. |
| query_queue_mem_used_pct_limit | 0 | The upper limit of memory usage percentage on a BE. It takes effect only after being set greater than 0. Setting it to 0 indicates no limit is imposed. Range: [0, 1] |
| query_queue_cpu_used_permille_limit | 0 | The upper limit of CPU usage permille (CPU usage * 1000) on a BE. It takes effect only after being set greater than 0. Setting it to 0 indicates no limit is imposed. Range: [0, 1000] |
- After Query Queue v2 is enabled,
query_queue_mem_used_pct_limitandquery_queue_cpu_used_permille_limitare no longer supported for queue triggering. - By default, BE reports resource usage to FE at one-second intervals. You can change this interval by setting the BE configuration item
report_resource_usage_interval_ms.
Specify resource thresholds for resource group-level query queues
From v3.1.4 onwards, you can set individual concurrency limits (concurrency_limit) and CPU core limits (max_cpu_cores) when creating a resource group. When a query is initiated, if any of the resource consumptions exceed the resource threshold at either the global or resource group level, the query will be placed in queue until all resource consumptions are within the threshold.
| Variable | Default | Description |
|---|---|---|
| concurrency_limit | 0 | The concurrency limit for the resource group on a single BE node. It takes effect only when it is set to greater than 0. |
| max_cpu_cores | 0 | The CPU core limit for this resource group on a single BE node. It takes effect only when it is set to greater than 0. Range: [0, avg_be_cpu_cores], where avg_be_cpu_cores represents the average number of CPU cores across all BE nodes. |
You can use SHOW USAGE RESOURCE GROUPS to view the resource usage information for each resource group on each BE node, as described in View Resource Group Usage Information.