RonJay
04/01/2026, 10:16 AMRocky
04/01/2026, 10:16 AMmem_limit (which is typically 90% of the pod's memory).
Here are the best ways to handle and resolve these memory issues:
1. Enable "Spill to Disk"
The most effective way to prevent OOM (Out Of Memory) errors for large queries is to enable the "Spill to Disk" feature. This allows StarRocks to move intermediate results (from joins, sorts, or aggregations) to the disk instead of keeping everything in memory.
* Step 1: Configure a storage directory in your `cn.conf`:
properties
spill_local_storage_dir=/path/to/fast/ssd/spill
* Step 2: Enable it in your session or globally:
sql
SET enable_spill = true;
-- Optional: 'auto' (default) or 'force'
SET spill_mode = 'auto';
Note: Using a fast local NVMe/SSD for spilling is highly recommended to minimize performance impact.
2. Control Scan Concurrency
When querying Iceberg tables, StarRocks may spawn many I/O tasks to read data in parallel. This can consume a lot of memory. You can try reducing the concurrency of the scan:
* Reduce I/O tasks per scan:
sql
-- Default is 4. Lowering this reduces memory usage during the scan phase.
SET io_tasks_per_scan_operator = 2;
* Adjust Pipeline Parallelism:
sql
-- Lowering this can reduce the overall memory footprint of the query execution.
SET pipeline_dop = 8; -- Adjust based on your CN core count
3. Check and Limit Query Memory
By default, a single query might try to use all available memory on the node. You can cap it to ensure it doesn't crash the pod:
* Set a per-query memory limit:
sql
-- For example, limit a single query to 20GB on each node
SET query_mem_limit = 21474836480;
4. Optimize Iceberg Metadata Planning
If the memory spike happens during the planning phase (on the FE or when CN is doing distributed planning), it might be due to a massive amount of Iceberg manifest files.
* Check the plan_mode variable:
sql
-- 'distributed' is better for very large tables to spread metadata parsing across CNs.
-- 'local' is faster for small/medium tables.
SET plan_mode = 'distributed';
* Ensure metadata caching is configured efficiently in fe.conf (e.g., iceberg_metadata_memory_cache_capacity).
5. CN Pod Configuration
If your pod has a 30GB limit and StarRocks is hitting 27GB (90%), it may be getting killed by the Kubernetes OOM killer before StarRocks can react.
* Lower the internal limit: Set mem_limit = 80% in cn.conf to give the system/OS more breathing room.
* Increase Pod Resources: If your dataset is truly massive ("bit data set"), you might simply need to scale your CN pods vertically (more RAM) or horizontally (more pods) to distribute the load.
Let me know if you'd like more details on any of these steps!
References
• data_source/catalog/iceberg/iceberg_catalog.md
• administration/management/resource_management/Memory_management.md
• sql-reference/System_variable.md
• data_source/feature-support-data-lake-analytics.md