RonJay
03/20/2026, 12:30 AMRocky
03/20/2026, 12:30 AMVARCHAR type in StarRocks (starting from version 2.1) exists primarily due to internal storage architecture and memory management efficiency.
Here are the key reasons why this limit is in place:
1. Maximum Row Size Constraint
In StarRocks' internal storage format, there is a limit on the maximum size of a single row, which is approximately 1,048,578 bytes.
* A VARCHAR value uses a 2-byte length prefix to store the actual size of the string.
* $1,048,578 \text{ (Max Row)} - 2 \text{ (Prefix)} = 1,048,576 \text{ bytes (1MB)}$.
Because of this row-level limit, a single VARCHAR field cannot exceed this capacity.
2. Memory Pre-allocation and Query Performance
StarRocks is a high-performance OLAP engine that uses vectorized execution. To achieve extreme speed, the execution engine often pre-allocates memory blocks during query processing.
* In many query scenarios, memory is allocated based on the defined length of the VARCHAR column rather than the actual data length of each row.
* If VARCHAR were allowed to be massive (e.g., several hundred MBs), a query involving multiple such columns could easily cause an Out of Memory (OOM) error, as the system would attempt to reserve huge chunks of memory for data that might not even be there.
3. OLAP Optimization
StarRocks is optimized for analytical workloads (aggregations, joins, etc.) rather than serving as a BLOB or document store. Columnar storage and vectorized processing work best when data fits within certain bounds. Extremely large text fields can degrade performance by:
* Increasing I/O overhead.
* Reducing the efficiency of the CPU cache.
* Making the "short-key index" less effective if large strings are placed early in the schema.
Important Notes:
* Before Version 2.1: The limit was even smaller—only 65,533 bytes (approx. 64KB).
* Best Practice: Always set your VARCHAR length to the smallest necessary value. For example, if an address field only needs 200 bytes, use VARCHAR(200) instead of the maximum. This helps the query optimizer manage memory more efficiently.
* STRING Type: In StarRocks, the STRING type is essentially an alias for VARCHAR with a large default length, but it is still subject to these same underlying architectural limits.
If you have data larger than 1MB, it is usually recommended to store the large content in an external object store (like S3) and keep the URI/link in StarRocks, or split the data if appropriate for your analysis.
References
• faq/table_design_faq.md
• knowledge/usage/best-practice.md
• sql-reference/System_limit.md
• faq/Others.md
• sql-reference/data-types/string-type/BINARY.md