@Rocky we want to bump starrocks version from 3.5.14 to 4.0.16, can we do it in 1 step? Or we should bump to some intermediate version first?

Yes, you can upgrade from StarRocks v3.5.14 to v4.0.16 in one step. In StarRocks versioning, the 4.0 series is the direct successor to the 3.5 series. Since you are already on a high patch version of 3.5 (v3.5.14), you satisfy the requirements for a direct upgrade. Key Considerations for the Upgrade: 1. JDK Requirement: Since you are already on 3.5.14, you should already be using JDK 17, which is required for both v3.5 and v4.0. 2. Upgrade Path: StarRocks recommends upgrading consecutively between minor versions (e.g., 3.4 → 3.5 → 4.0). Since 4.0 follows 3.5, no intermediate version is needed. 3. Metadata Backup: Before upgrading, it is a best practice to create a new metadata image to ensure a clean state:

sql
    ALTER SYSTEM CREATE IMAGE;

Verify the image is synchronized to all Follower FEs by checking the

fe.log

for "push image... push successful" before proceeding. 4. Standard Procedure: * Disable Balancer: Disable tablet scheduling/balancing before starting:

sql
        ADMIN SET FRONTEND CONFIG ("disable_balance" = "true");
        ADMIN SET FRONTEND CONFIG ("disable_colocate_balance" = "true");

* Order: Upgrade all BEs (and CNs) first, then upgrade Follower FEs, and finally the Leader FE. * Test: Perform an upgrade availability test on one BE and one FE before upgrading the entire cluster. Downgrade Note: If you need to downgrade back to 3.5 for any reason, v4.0 is compatible with v3.5.2 and later. Since you are on v3.5.14, your metadata will remain compatible if a rollback is necessary. For more details on specific behavior changes in v4.0 (such as Data Cache configuration changes or materialized view behavior), refer to the StarRocks v4.0 Release Notes. References • release_notes/release-4.0.md • deployment/upgrade.md • release_notes/release-3.5.md

What if I want to move further and try 4.1.6? @Rocky

Moving from v3.5.14 to v4.1.6 requires an intermediate step. According to the official StarRocks upgrade policy, you should always upgrade consecutively between minor versions (the second digit in the version number) to ensure metadata compatibility and a safe transition. Recommended Upgrade Path To reach v4.1.6, you should follow this sequence: 1. v3.5.14 $\rightarrow$ v4.0.16 (Intermediate) 2. v4.0.16 $\rightarrow$ v4.1.6 (Target) Why an intermediate step is required: * Minor Version Continuity: StarRocks documentation strongly recommends not skipping minor versions (e.g., skipping 4.0 to go directly from 3.5 to 4.1). * Metadata Safety: Each minor version often introduces fundamental metadata changes. Moving through 4.0 allows the system to migrate your metadata safely before the next set of changes in 4.1. * Rollback Capability: Downgrading from v4.1 is only supported back to v4.0.6 or later. If you jump directly from 3.5 to 4.1 and encounter an issue, you cannot safely downgrade back to your original 3.5 version. Steps for the two-stage upgrade: 1. Upgrade to v4.0.x first: * Follow the standard rolling upgrade (BEs first, then Follower FEs, then Leader FE). * Crucial: Once on v4.0.x, run

ALTER SYSTEM CREATE IMAGE;

and verify in the

fe.log

that the new metadata image has successfully synchronized to all Follower FEs before proceeding to the next minor version. 2. Upgrade to v4.1.6: * Once the cluster is stable on 4.0 and the metadata image is fresh, repeat the rolling upgrade process using the v4.1.6 binaries. Note on 4.1.6 Behavior Changes: * Adaptive Layout: v4.1 introduces significant changes to how data is distributed (automatic tablet splitting and distribution). * AWS SDK: The default HTTP client for the AWS SDK has switched from Poco back to the SDK's native client. If you rely on specific Poco configurations for S3/Object storage, you may need to set

enable_poco_client_for_aws_sdk = true

. References • deployment/upgrade.md • release_notes/release-4.1.md • release_notes/release-4.0.md References • deployment/upgrade.md • release_notes/release-4.0.md • release_notes/release-3.5.md

@Rocky I have question about data cache. In 3.5.14 we had storage_page_cache_limit = 40% datacache_enable = false and in 4.0 version storage_page_cache_limit was deprecated. So in for example 4.0.16 I need to use: datacache_enable = true datacache_mem_size = 40% ?

In StarRocks v4.0.16, your proposed configuration is essentially correct, but there are a few important details to ensure you maintain the same behavior as in v3.5.14. Starting with StarRocks v4.0, the caching architecture has been unified under the Data Cache umbrella, and several legacy parameters have been deprecated. 1. The Configuration Change In v3.5.14, you had "Data Cache" (the block cache for remote storage) disabled, but "Page Cache" (the memory cache for local storage) enabled and limited to 40%. To replicate this in v4.0.16, you should use: *

datacache_enable = true

: In v4.0, this is the "master switch." If set to

false

, it disables both the Page Cache (local) and Block Cache (remote). To keep your local Page Cache working, this must now be

true

. *

datacache_mem_size = 40%

: This is the direct replacement for

storage_page_cache_limit

. It accepts percentage strings (e.g.,

40%

) or specific sizes (e.g.,

32GB

). *

block_cache_enable = false

(Optional): Since you previously had

datacache_enable = false

, you likely were not using the disk-based cache for remote data (Data Lake/Shared-data). In v4.0, if you only want the memory-based Page Cache and want to ensure no disk space is used for caching, you can explicitly disable the Block Cache component. 2. Summary of Deprecations The following parameters are deprecated in v4.0 and should be removed from your `be.conf`: *

storage_page_cache_limit

(Use

datacache_mem_size

instead) *

block_cache_mem_size

(Use

datacache_mem_size

instead) *

block_cache_disk_size

(Use

datacache_disk_size

instead) 3. Recommended

be.conf

for your case:

properties
# Enable the unified Data Cache framework
datacache_enable = true

# Set the memory limit (replaces storage_page_cache_limit)
datacache_mem_size = 40%

# If you want to keep the "remote data" disk cache disabled 
# to match your old 'datacache_enable = false' setting:
block_cache_enable = false

Pro-Tip: Dynamic Adjustment In v4.0, you can adjust these settings at runtime without restarting the BE by using the

UPDATE be_configs

command:

sql
UPDATE be_configs SET VALUE="40%" WHERE NAME="datacache_mem_size";

Note: Changes made via SQL are not persistent across restarts unless you also update the

be.conf

file. References • release_notes/release-4.0.md • data_source/data_cache.md • administration/management/BE_configuration.md References • administration/management/BE_configuration.md • release_notes/release-2.4.md • data_source/data_cache.md • release_notes/release-4.0.md

@Rocky what about datacache_disk_size , should I set it to 0?

In StarRocks v4.0.16, you can set

datacache_disk_size = 0

to ensure no disk space is used for caching, but the most direct way to replicate your v3.5.14 behavior is to use the component toggle. In v3.5.14, your configuration meant: * Page Cache (Memory): Enabled (at 40%). * Data Cache (Disk/Block): Disabled. In v4.0.16, these are unified. If you want to keep the memory-based cache but completely avoid using disk space for caching, use the following configuration in your `be.conf`:

properties
# 1. Enable the unified Data Cache framework (the "master switch")
datacache_enable = true

# 2. Set your memory limit (replaces storage_page_cache_limit)
datacache_mem_size = 40%

# 3. Explicitly disable the disk-based "Block Cache" component
# This effectively replaces your old 'datacache_enable = false'
block_cache_enable = false

Why this is the recommended approach: 1. Component Control:

block_cache_enable = false

explicitly tells the system not to initialize the disk-based caching logic, which is cleaner than setting a size to 0. 2. Auto-scaling: v4.0 introduced

datacache_auto_adjust_enable

(which defaults to

true

). If you leave this enabled and don't set a size, StarRocks might attempt to automatically allocate disk space for the cache. Disabling

block_cache_enable

prevents this. 3. Verification: After upgrading and applying these settings, you can run the following command to verify that only the memory cache is active:

sql
    SHOW BACKENDS\G

Look for the

DataCacheMetrics

field. It should show

DiskUsage: 0B/0B

(or similar indicating no disk quota) and your allocated memory usage. Summary of Parameter Mapping: v3.5.14 Parameter | v4.0.16 Equivalent

storage_page_cache_limit = 40%

|

datacache_mem_size = 40%

datacache_enable = false

|

block_cache_enable = false

(Not available) |

datacache_enable = true

(Must be true to use the above) References • data_source/data_cache.md • release_notes/release-4.0.md • administration/management/BE_configuration.md References • using_starrocks/caching/block_cache.md • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache_troubleshooting.md