@Rocky what is the difference between enable_query_queue and enable_query_queue_v2

In StarRocks, the difference between the legacy query queue (often referred to via session variables like

enable_query_queue_select

) and

enable_query_queue_v2

(an FE configuration) lies in the underlying scheduling architecture and the sophistication of how queries are prioritized. *1. Core Purpose* * Query Queue (V1/Legacy): This refers to the original queuing mechanism introduced in v2.5. It monitors resource thresholds (CPU, memory, and concurrency) on BE nodes. When these thresholds are exceeded, new queries are placed in a queue. It primarily uses a basic "First-In-First-Out" (FIFO) approach for global queues. * Query Queue V2 (

enable_query_queue_v2

): This is an FE-level configuration (in

fe.conf

) that upgrades the internal slot-based scheduler. It was introduced to provide more intelligent and fair scheduling of queries waiting in that queue. *2. Key Technical Differences* Feature | Legacy Query Queue (V1) | Query Queue V2 Config Type | Session Variables (

enable_query_queue_select

, etc.) | FE Configuration (

fe.conf

) Scheduling Strategy | Simple FIFO (mostly) | Advanced: SWRR or SJF Resource Management | Threshold-based (BE reports usage) | Slot-based (Centralized FE management) Fairness | Limited | High (Weighted Round Robin) Default | Disabled by default |

true

(from v4.1 onwards) *3. What V2 Adds* When you enable

enable_query_queue_v2 = true

in your FE configuration, you gain access to advanced scheduling policies controlled by the

query_queue_v2_schedule_strategy

parameter: * SWRR (Smooth Weighted Round Robin): The default in V2. It ensures that different resource groups or workloads get a fair share of the available slots based on their weights, preventing large queries from completely starving smaller ones. * SJF (Short Job First + Aging): Prioritizes shorter, faster queries to reduce overall latency, while using an "aging" mechanism to ensure long-running queries aren't stuck in the queue forever. *4. How they work together* They are not mutually exclusive; rather, V2 improves how the queue behaves once it is active. 1. Activation: You still use session variables like

SET GLOBAL enable_query_queue_select = true;

to tell StarRocks to queue queries when the system is busy. 2. Execution Logic: If

enable_query_queue_v2

is

true

in your

fe.conf

, StarRocks uses the new slot-manager and SWRR/SJF strategies to decide which query from the queue gets to run next as resources become available. Summary * Use the legacy variables (

enable_query_queue_select/load

) to turn the queuing feature on or off for specific query types. * Use

enable_query_queue_v2

(v3.3.4+) to enable the more modern, slot-based scheduling engine that handles mixed workloads more efficiently than the original implementation. References • administration/management/FE_configuration.md • administration/management/resource_management/query_queues.md • sql-reference/System_variable.md

@Rocky is there any documentation that explains this more clearly?

Hi! I'm Rocky. I'd love to help you find the right documentation! Since I'm not sure which specific topic or feature you're referring to, here are some of the most helpful sections of the StarRocks Documentation that explain core concepts clearly: * Best Practices Overview: This is a great starting point for understanding efficient table design, including partitioning, bucketing, and sort keys. * Primary Key Tables: Explains how StarRocks handles real-time updates and deletes with high performance. * Query Tuning Guide: A comprehensive guide on how to analyze and optimize your SQL queries. * Data Ingestion Overview: Explains the various ways to get data into StarRocks (Stream Load, Broker Load, Routine Load, etc.). * Quick Start Guide: If you are just getting started and want to see how everything fits together. Could you please let me know what specific feature, error, or syntax you're looking into? I can then search for a more detailed technical explanation for you! References • best_practices/overview.md • quick_start/quick_start.mdx • best_practices/bucketing.md • best_practices/table_clustering.md • table_design/StarRocks_table_design.md • quick_start/iceberg.md • developers/mac-compile-run-test.md • introduction/StarRocks_intro.md

@Rocky is there any specific documentation around

enable_query_queue_v2

that explains how it works more clearly?

Hi! I'm Rocky. While there isn't a single "Query Queue V2" chapter in the main user guide yet, the functionality is extensively documented via the FE Configuration parameters which detail exactly how this slot-based scheduler operates.

enable_query_queue_v2

(introduced in v3.3.4 and enabled by default from v4.1 onwards) switches StarRocks from a simple concurrency-based threshold to a more sophisticated Slot-based Query Scheduler. Here is a breakdown of how it works: 1. The Concept of "Slots" Instead of just counting the number of queries, V2 views the cluster's capacity as a pool of Logical Slots. * Total Slots calculation: The total capacity is calculated based on your cluster size:

Total Slots = query_queue_v2_concurrency_level _ number_of_BEs _ CPU_cores_per_BE

* By default,

query_queue_v2_concurrency_level

is 4. This means if you have 2 BEs with 16 cores each, your cluster has $4 \times 2 \times 16 = 128$ slots. 2. Slot Estimation (How much "weight" is a query?) When a query arrives, the FE estimates how many slots it requires before allowing it to run. This is governed by the `query_queue_slots_estimator_strategy`: * MBE (Memory-Based Estimation): Calculates slots based on predicted memory or plan costs. * PBE (Parallelism-Based Estimation): Calculates slots based on fragment parallelism (how many scan ranges it hits) and CPU costs. * MAX (Default): Takes the higher of the two. A heavy query with high parallelism or high memory will consume more slots, naturally limiting how many such queries can run at once. 3. Scheduling Strategies When the slots are full and queries begin to queue, you can choose how they are prioritized via `query_queue_v2_schedule_strategy`: * SWRR (Smooth Weighted Round Robin): The default. It ensures fair resource distribution among different users/resource groups. * SJF (Short Job First + Aging): Prioritizes smaller, faster queries to improve interactive performance, while using an "aging" mechanism to ensure large queries aren't stuck forever. 4. Key Configuration Parameters If you want to tune this behavior, keep an eye on these FE configurations: * `query_queue_v2_concurrency_level`: Increase this if you have high-concurrency small queries and want to pack more in; decrease it if you are hitting memory issues. * `query_queue_v2_cpu_costs_per_slot`: Controls how many "CPU cost units" equal one slot. * `query_queue_v2_num_rows_per_slot`: Controls how many source rows correspond to one slot (default is 4096). Why use V2? The legacy query queue (v1) relied on BEs reporting their status back to the FE, which often had a delay. V2 is managed directly by the Leader FE, making the scheduling much more "real-time" and preventing resource exhaustion before it happens by accurately weighing queries during the planning phase. Do you have a specific version you're running, or are you seeing queries queue unexpectedly? I can help you tune these parameters! References • administration/management/FE_configuration.md • administration/management/resource_management/query_queues.md

@Rocky what is the minimum config settings I need to run for

enable_query_queue_v2

if I want to prioritize stopping cpu saturation on BEs?

To prioritize stopping CPU saturation on the BEs using the Query Queue V2 (introduced in v3.3.4 and enabled by default in v4.1+), you need to configure the slot-based scheduling system. Unlike the legacy queue which relies on reactive CPU usage thresholds, V2 uses a "slot" model to manage resources proactively based on a query's estimated cost. The minimum configuration settings to prioritize CPU protection are: 1. Enable Query Queuing and V2 Scheduler First, you must enable the query queue for your query type (e.g.,

SELECT

) and ensure the V2 scheduler is active.

sql
-- Enable queuing for SELECT queries
SET GLOBAL enable_query_queue_select = true;

-- Ensure V2 scheduler is enabled (default in v4.1+)
-- This replaces the legacy V1 logic with the slot-based V2 logic.
ADMIN SET FRONTEND CONFIG ("enable_query_queue_v2" = "true");

2. Configure CPU-Based Slot Calculation To prioritize CPU saturation, you need to tune how many "slots" a query consumes based on its estimated CPU cost. The scheduler calculates slots as

max(CPU_slots, Memory_slots)

. To make CPU the bottleneck: *

query_queue_v2_concurrency_level

: This determines the total number of slots available in the cluster. * Calculation:

Total Slots = concurrency_level * total_BE_cores

. * Recommendation: Keep this at the default (

4

) or lower if you want to be more conservative. A lower value reduces the total "capacity" for concurrent work. *

query_queue_v2_cpu_costs_per_slot

: This is the most critical setting for CPU prioritization. * Logic:

CPU Slots = Query Planner CPU Cost / query_queue_v2_cpu_costs_per_slot

. * Action: Decrease this value to make queries "heavier" in terms of CPU slots. This forces high-CPU queries to take up more slots, causing subsequent queries to queue earlier and preventing the BEs from being overwhelmed by too many intensive tasks.

sql
-- Example: Make queries consume more slots per unit of CPU cost
-- Default is 1,000,000,000. Lowering it increases CPU-based queuing.
ADMIN SET FRONTEND CONFIG ("query_queue_v2_cpu_costs_per_slot" = "500000000");

3. Summary of Minimum Settings (FE Config) To effectively stop CPU saturation, adjust these parameters in your

fe.conf

or via `ADMIN SET FRONTEND CONFIG`: Parameter | Purpose for CPU Protection

enable_query_queue_v2

| Switches to the advanced slot-based scheduler.

query_queue_v2_concurrency_level

| Limits total system concurrency relative to available cores.

query_queue_v2_cpu_costs_per_slot

| Controls how much estimated CPU cost equals one "concurrency slot." Proactive Tip: Resource Groups While

enable_query_queue_v2

manages global concurrency, for the strongest CPU protection, use Resource Groups with a

max_cpu_cores

limit. This allows the system to hard-limit the CPU cores a specific group of queries can use, preventing them from ever saturating the entire BE node regardless of the queue.

sql
CREATE RESOURCE GROUP heavy_queries
PROPERTIES (
    "cpu_core_limit" = "16", -- Hard limit on cores used
    "concurrency_limit" = "10"
);

References • administration/management/FE_configuration.md • administration/management/resource_management/query_queues.md • sql-reference/System_variable.md