http://starrocks.io logo
Join Slack
Powered by
<@U0A71G31CDV> can I know what all tables cached i...
# questions-and-troubleshooting
m
@Rocky can I know what all tables cached in specific compute nodes?
r
In StarRocks (specifically for Shared-data clusters or when using the Data Cache for external catalogs), the Data Cache is a block-level cache that operates on demand. Because it caches data blocks (sub-segments) rather than entire tables, there is no single SQL command to list "all tables currently in the cache" on a specific compute node. However, you can observe cache status and configuration using the following methods: 1. View Cache Usage per Node To see how much data (total) is cached in memory and on disk for each Compute Node (CN) or Backend (BE), use:
Copy code
sql
SELECT * FROM information_schema.be_datacache_metrics;
* DISK_USED_BYTES: Amount of data cached on the local disk. * MEM_USED_BYTES: Amount of data cached in local RAM. 2. Check Cache Configuration for Tables/Partitions You can check which tables or partitions are eligible to be cached and their priority using the 
partitions_meta
view:
Copy code
sql
SELECT DB_NAME, TABLE_NAME, PARTITION_NAME, ENABLE_DATACACHE 
FROM information_schema.partitions_meta;
* ENABLE_DATACACHE: 
1
means the partition is allowed to use the local cache. 3. Check Tablet Assignment (Shared-data) In a shared-data cluster, tablets are assigned to specific nodes. To see which tablets are managed by a specific node, you can query:
Copy code
sql
SELECT * FROM information_schema.be_tablets WHERE BE_ID = <your_node_id>;
While this doesn't guarantee the data is fully in the local cache (it might still be in S3/Remote storage), these are the tablets that the node is responsible for caching and serving. 4. Verify Cache Hits via Query Profile The most reliable way to see if a specific table's data is actually being served from the cache on a node is to check the Query Profile after running a query: * Look for `DataCacheReadBytes`: Data read from the local cache (disk/memory). * Look for `DataCacheWriteBytes`: Data that was missed and had to be fetched from remote storage and written to cache. 5. Proactive Caching (Warmup) If you want to ensure specific tables or partitions are cached on the compute nodes, you can use the Cache Warmup feature (introduced in v3.3+):
Copy code
sql
CACHE SELECT * FROM table_name;
This command proactively pulls the table's data into the Data Cache of the nodes assigned to those tablets. Summary There is no direct "list tables" command for the cache because the cache is dynamic and block-based. You can monitor overall usage per node via 
be_datacache_metrics
and query-specific behavior via profiles. References • using_starrocks/caching/block_cache.md • knowledge/admin_and_operation/shared_data_compaction.md
m
@Rocky this query is not loading data at all, giving timeout of 1min, SELECT * FROM information_schema.be_tablets WHERE BE_ID = 10001; even with limit as well. I'm using 4.0.8 shared data architecture
r
In StarRocks 4.0 Shared-data architecture, the 
information_schema.be_tablets
view is the primary way to map tablets to specific nodes. However, because this view aggregates metadata for every tablet in the cluster, it can easily time out (default 60s) if you have a large number of tables or partitions. Here is how you can resolve the timeout and find the cached tables: 1. Increase Query Timeout The simplest fix is to allow the FE more time to process the massive tablet metadata set. Run this in your session before the query:
Copy code
sql
-- Increase timeout to 10 minutes
SET query_timeout = 600;

-- Query for table IDs assigned to the specific node
SELECT DISTINCT TABLE_ID 
FROM information_schema.be_tablets 
WHERE BE_ID = 10001;
2. Join with Table Names Since 
be_tablets
only contains 
TABLE_ID
, use a join to get human-readable names. Using a subquery for the node-specific tablets is usually more efficient:
Copy code
sql
SET query_timeout = 600;
SELECT t.TABLE_SCHEMA, t.TABLE_NAME
FROM information_schema.tables t
JOIN (
    SELECT DISTINCT TABLE_ID 
    FROM information_schema.be_tablets 
    WHERE BE_ID = 10001
) b ON t.TABLE_ID = b.TABLE_ID;
3. Verify via 
SHOW COMPUTE NODES
 To check if the node actually has tablets assigned (or if the 
BE_ID
is correct), use:
Copy code
sql
SHOW COMPUTE NODES;
Look for the TabletNum column for your node. In shared-data, this indicates the number of tablets currently managed/cached by that specific Compute Node. 4. Direct Node Inspection (Shell Access) If you have access to the compute node's terminal, you can see the raw cached data. In StarRocks 4.0, the Data Cache is stored in the path defined by 
storage_root_path
in `cn.conf`: * Path: 
<storage_root_path>/datacache/
* Inside this folder, data is stored in blocks. While you won't see table names directly, the presence of files indicates active caching. 5. Why is this slow? In Shared-data, compute nodes (CNs) are stateless. The mapping of which tablets are "cached" on which node is dynamic and managed by the StarMgr (part of the FE). When you query 
be_tablets
, the FE must scan its entire StarMgr metadata to filter for that specific 
BE_ID
. If your cluster has millions of tablets, this metadata scan exceeds the default 1-minute window. Note: If you are specifically interested in whether a table is allowed to be cached, check the 
ENABLE_DATACACHE
column in 
information_schema.partitions_meta
. References • sql-reference/information_schema/be_tablets.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_PROC.md • using_starrocks/caching/block_cache.md References • sql-reference/sql-statements/table_bucket_part_index/SHOW_TABLET.md • faq/shared_data_faq.md • knowledge/admin_and_operation/shared_data_compaction.md
m
@Rocky even if I remove the filter conditon and just run select * from be_tablets limit 2 it is also timing oout of 2mins as well
r
The fact that 
SELECT * FROM information_schema.be_tablets LIMIT 2
is timing out even with a 2-minute limit indicates that the FE is likely struggling to collect or process the metadata from the StarMgr (the component managing shared-data shards) or is waiting on a response from a specific node. In a shared-data cluster (StarRocks 4.0), the metadata for all tablets is centralized. When you query 
be_tablets
, the FE scans this entire metadata set to determine which tablets are assigned to which Compute Node. If you have a large number of tablets (e.g., hundreds of thousands or millions), this operation is extremely expensive. Here are the best ways to bypass this timeout and identify the tables: 1. Prune the search by Database Instead of scanning the entire cluster's metadata, try to filter by a specific database. This allows the FE to limit the metadata it needs to load:
Copy code
sql
SET query_timeout = 300; -- Set to 5 mins

SELECT DISTINCT t.TABLE_NAME
FROM information_schema.tables t
JOIN information_schema.be_tablets bt ON t.TABLE_ID = bt.TABLE_ID
WHERE bt.BE_ID = 10001 
  AND t.TABLE_SCHEMA = 'your_database_name';
2. Check the "TabletNum" per Node To quickly verify if a node is actually "holding" data (has tablets assigned to it), use this command. It is much faster than `be_tablets`:
Copy code
sql
SHOW COMPUTE NODES;
Check the TabletNum column for 
ComputeNodeId: 10001
. If this number is 
0
, no tables are currently assigned to (or cached on) this node. If it is high, it confirms the node is responsible for those tablets. 3. Use 
SHOW PROC
(The "Manual" way) If the 
information_schema
views are timing out, you can navigate the internal metadata directory. This is usually faster because it doesn't try to build a massive table in memory. 1. Run 
SHOW PROC '/dbs';
to get your database ID. 2. Run 
SHOW PROC '/dbs/<db_id>';
to get the IDs of the tables in that DB. 3. Run 
SHOW PROC '/dbs/<db_id>/<table_id>/partitions';
to see the tablet distribution for that specific table. * This will show which Backend/Compute Node is responsible for each partition/tablet. 4. Why is 
LIMIT
not helping? In StarRocks, for certain system views like 
be_tablets
, the FE often needs to materialize the underlying metadata collection before it can apply the 
LIMIT
. In a shared-data (lake) architecture, this involves fetching shard information from StarMgr. If your cluster has millions of tablets, the "collection" phase itself exceeds 2 minutes. 5. Troubleshooting the Timeout If you cannot run any query against 
be_tablets
, please check: * FE Logs: Check 
fe.log
and 
fe.warn.log
for any "RPC timeout" or "StarMgr" errors during your query. It might be that one node is unresponsive and the FE is waiting for it. * Node Status: Ensure all nodes in 
SHOW COMPUTE NODES
are 
Alive: true
. A single dead node can cause metadata queries to hang as the FE tries to reconcile tablet locations. Summary for your goal: Since you want to know what tables are on a node, start with Method 1 (filtering by one database at a time). If that still fails, use 
SHOW COMPUTE NODES
to see the tablet count, and then use 
SHOW TABLET FROM <table_name>
for your most important tables to see which node they are assigned to. References • sql-reference/information_schema/be_tablets.md • sql-reference/sql-statements/cluster-management/nodes_processes/SHOW_COMPUTE_NODES.md • faq/shared_data_faq.md References • sql-reference/information_schema/be_tablets.md • deployment/shared_data/feature-support-shared-data.md
m
@Rocky I can see a query running with 10compute nodes cluster and scans almost evenly distributed but network received over a specific node is too high compared to other nodes(50x), what could be happening here, netowrk transferred is almost similar under 1-1.2x?
r
In a StarRocks shared-data (lake) cluster, if one node shows 50x higher network reception (RX) while scans and network transmission (TX) are evenly balanced, you are most likely seeing a Data Cache Miss on that specific node. The Most Likely Cause: Remote Storage Fetching In the shared-data architecture, compute nodes cache data from remote storage (like S3 or HDFS) onto their local disks. * Why RX is high: If a query needs to scan a table but that specific compute node does not have the data in its local cache, it must pull the data from S3. This download counts as Network Received traffic at the OS level. * Why scans are even: The query plan has assigned work (tablets/morsels) evenly to all 10 nodes. They are all "scanning" the same amount of data. * Why TX is balanced: Once the data is fetched (either from cache or S3), the nodes process it and shuffle the results. If the results are evenly distributed, the "Network Transferred" (inter-node shuffle traffic) will remain similar across all nodes. How to Confirm Check the Query Profile for that specific query. Look for the following metrics under the 
OLAP_SCAN_OPERATOR
for the high-RX node: 1. 
DataCacheWriteBytes
: If this is high on the specific node, it confirms that the node was fetching data from remote storage and writing it into its local cache during the query. 2. 
DataCacheReadBytes
: On the other 9 nodes, this should be high, indicating they served the data from their local disk/memory cache. 3. 
CompressedBytesReadRemote
: This explicitly tracks how many bytes were pulled from the cloud bucket (S3/GCS/Azure). Other Possible (but less likely) Scenarios * Final Result Gathering: If the query ends with a large 
LIMIT
or a global aggregation that doesn't reduce data much, the final result is "gathered" to a single node (the one hosting the root fragment). However, in this case, you would typically see the other 9 nodes having higher TX (sending to the gatherer). Since your TX is balanced, this is unlikely. * Large Broadcast Join: If the optimizer chose a 
BROADCAST
join for a table that was larger than expected, it would send that table to all nodes. However, this would cause high RX on all nodes, not just one. Recommendation * Check Cache Balance: If this happens consistently on the same node, it might have a smaller cache disk or a different 
datacache.partition_duration
setting, causing it to evict data more frequently than the others. * Warmup the Cache: If you want to avoid this spike, you can use the cache warmup feature:
Copy code
sql
    CACHE SELECT * FROM your_table;
This will pre-fill the caches across all nodes so that the next query doesn't trigger a massive remote fetch. References • data_source/data_cache.md • faq/shared_data_faq.md • best_practices/query_tuning/query_profile_operator_metrics.md References • administration/management/monitoring/metrics-shared-data.md • administration/management/monitoring/metrics.md • deployment/shared_data/s3.md
m
@Rocky I've given 150GB for datacache and I can see this in cn metrics Status: Normal, DiskUsage: 109.9GB/110GB, MemUsage: 9.9GB/10GB. what happened to rest of the disk? it is summing to 120GB only right?
r
The discrepancy you are seeing—where you allocated 150GB but only 120GB is appearing in the metrics (110GB Disk + 10GB Memory)—is due to the default safety reservation and how StarRocks splits the cache in the shared-data architecture. In StarRocks 4.0 (and 3.x), the Data Cache (managed by the Starlet component) uses a default safety limit of 80%. 1. The 80% Rule (
starlet_star_cache_disk_size_percent
) By default, StarRocks reserves 20% of the disk space as a safety buffer. This is controlled by the parameter 
starlet_star_cache_disk_size_percent
(default: 80) or, in StarRocks 4.0, the renamed 
disk_safe_level
(default: 80). Even if you explicitly provide a 150GB quota or have a 150GB disk partition, the system will cap the usable cache at: * $150\text{ GB} \times 0.8 = 120\text{ GB}$ usable total. 2. The Disk and Memory Split The 120GB usable capacity is then divided into the two pools you see in your metrics: * Memory Cache (10GB): This is used for caching metadata and small data blocks in RAM (managed by 
datacache_mem_size
). * Disk Cache (110GB): The remaining space ($120 - 10 = 110\text{ GB}$) is allocated to the physical disk blocks on your 
storage_root_path
. This explains exactly why your metrics show 
110GB
and 
10GB
as the denominators: * DiskUsage: $109.9 / 110\text{ GB}$ (Your disk cache is essentially full/saturated). * MemUsage: $9.9 / 10\text{ GB}$ (Your memory cache is also saturated). How to use the full 150GB? If you want StarRocks to use more of the disk and reduce that 30GB "missing" buffer, you can adjust the following in your 
cn.conf
(requires a restart): 1. Increase the safe level percentage:
Copy code
properties
    # Increase from 80 to 95 to use more of the 150GB disk
    disk_safe_level = 95
2. Explicitly set the disk size: In shared-data clusters, the system takes the greater of 
datacache_disk_size
and the percentage-calculated value. However, the 
disk_safe_level
can still act as a hard ceiling for the filesystem safety. Summary of where the 30GB went: * 20% Reservation (30GB): Held as a safety margin to prevent the physical disk from hitting 100% (which would cause OS errors and instability). * Result: 120GB total usable, split into 110GB Disk and 10GB RAM. Tip: If you see 
DiskUsage: 109.9/110
, the cache is currently performing LRU eviction. This is normal behavior—StarRocks keeps the cache as full as possible to maximize performance. Old data is only evicted when new data needs to be cached. References • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md • administration/management/BE_configuration.md • deployment/shared_data/s3.md • deployment/shared_data/minio.md
m
@Rocky if a table bocks are cached in specific compute node, is there a chance the query fragments goes to same compute nodes as cache is hitting? Then which cases cache sharing will be valid and used? Is it case that everytime one table is hit and it goes to same compute node even if it is busy? How is the compute node decided?
r
In a StarRocks shared-data (lake) cluster, query scheduling is cache-aware, but it is designed to balance performance with cluster health. 1. How is the Compute Node decided? StarRocks uses a Consistent Hashing algorithm to map tablets (shards) to specific Compute Nodes (CN). * Fixed Mapping: For a given tablet, the FE will always prefer to schedule the query fragment to the same CN node. This ensures that the node can build and maintain a "hot" local cache for that specific data. * Locality Priority: The system tries to maximize "data locality." If Node A has the cache for Tablet 1, Tablet 1 will almost always be sent to Node A. 2. Does it always go to the same node even if it's busy? Not necessarily. StarRocks 3.x/4.0 introduces logic to prevent "hotspot" nodes from bottlenecking the cluster: * Load Balancing: If a node is significantly more "busy" (measured by CPU load, queue length, or if the node is down), the FE can "spill" or reschedule tasks to other available nodes. * Morsel-driven Scheduling: The work is broken into small units called "morsels." While the first preference is the "home" node (for cache), if that node's task queue is too long, the scheduler can assign morsels to other idle nodes. * Result: In a healthy cluster, it goes to the same node. In a congested or scaling cluster, it will redistribute to keep query latency low, even if it means a temporary cache miss on the new node. 3. When is "Cache Sharing" valid and used? Cache sharing (introduced in later 3.x versions) is specifically designed for the "redistribution" scenarios mentioned above. Valid Cases for Cache Sharing: * Elastic Scaling: When you add a new CN, it has an empty cache. If a query is scheduled to it, it can pull the "hot" blocks from the old nodes over the network instead of downloading them from S3/Remote Storage. * Node Failure/Busy-ness: If Node A is too busy and the FE sends its task to Node B, Node B can "ask" Node A for the cached blocks. * Why use it? Reading from a peer node's RAM/Disk over a 10Gbps/25Gbps local network is often much faster and cheaper than fetching from remote object storage (S3). How to enable it: To make this active, you must set these configurations: * FE: 
SET GLOBAL enable_datacache_sharing = true;
* FE: 
admin set frontend config ("enable_trace_historical_node" = "true");
Summary for your scenario: * Is there a chance query fragments go to the same node? Yes, it is the default behavior to ensure high cache hits. * Which cases is it valid? It is always valid for "Cloud Native" (shared-data) tables and External Catalog tables. * Is it always the same node? It prefers the same node for cache consistency but will bypass it if the node is unresponsive or heavily overloaded to ensure the query actually finishes. References • data_source/data_cache.md • introduction/Architecture.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md References • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md
m
@Rocky how can I verify a select few columns on a table query is hitting cache ? I checked with explain and explain verbose,couldn't find cache related info anywhere
r
Cache hits for the Data Cache (block cache) are not visible in the 
EXPLAIN
or 
EXPLAIN VERBOSE
output. Those commands only show the execution plan and whether the query is eligible to populate the cache. To verify if your query is actually hitting the cache, you must check the Query Profile. 1. Enable and View the Profile Run these commands in your session before executing your query:
Copy code
sql
SET enable_profile = true;
-- Run your query here
-- Then retrieve the profile ID
SHOW PROFILELIST;
-- Get the detailed profile (replace <profile_id> with the ID from above)
SELECT get_query_profile('<profile_id>');
2. Key Metrics to Look For In the profile, look for the 
SCAN
operator (e.g., 
OLAP_SCAN_OPERATOR
or 
HdfsScanNode
). Under that section, check these specific metrics: * 
DataCacheReadBytes
: If this number is high and matches the total data scanned, you had a 100% cache hit. It means data was read from the local disk/memory cache. * 
DataCacheWriteBytes
: If this is high, you had a cache miss. The node was fetching data from S3/HDFS and writing it into the local cache for the first time. * 
BytesRead
: The total data processed. * Full Hit: 
DataCacheReadBytes
≈ 
BytesRead
* Full Miss: 
DataCacheWriteBytes
≈ 
BytesRead
3. Verification for "Select Few Columns" StarRocks uses a columnar storage format (like Parquet or its native format). The Data Cache caches data at the block/page level. If you query only 2 columns out of a 100-column table: 1. StarRocks only reads the blocks belonging to those 2 columns. 2. The 
DataCacheReadBytes
will only reflect the size of the data for those specific columns. 3. To verify: Run the query twice. The first time, 
DataCacheWriteBytes
will be high. The second time, 
DataCacheWriteBytes
should be 
0
and 
DataCacheReadBytes
should be high. 4. What 
EXPLAIN VERBOSE
actually tells you The only cache-related info in 
EXPLAIN VERBOSE
is the `dataCacheOptions`:
Copy code
text
|   0:HdfsScanNode                        |
|      ...                                |
|      dataCacheOptions={populate: true}  |
_ `populate: true`: The query _will* save data to the cache if it’s not already there. * `populate: false`: The query is bypassing the cache population (often due to 
populate_datacache_mode
settings or query size). Summary: If you don't see 
DataCacheReadBytes
in your Query Profile, it means either the Data Cache is not enabled for that catalog/table type, or you are looking at a version/configuration where cache metrics are named differently (some older versions used 
BlockCacheReadBytes
). References • data_source/data_cache.md • data_source/data_cache_troubleshooting.md • using_starrocks/caching/query_cache.md
m
@Rocky I don't see DataCacheBytes as well, I'm just running select few cols from table where start_stamp>='' limit 10
r
If you have already looked at the Query Profile (and not just the 
EXPLAIN
output) and still don't see 
DataCacheReadBytes
, it is usually due to one of the following three reasons: 1. You are querying a "Local" (Shared-Nothing) Table The 150GB Data Cache you configured is specific to the Starlet component. This component is only utilized for: * Shared-data (Lake) tables (tables created in a cluster where storage is S3/HDFS). * External Catalog tables (Hive, Iceberg, Hudi, etc.). If your table is a standard Shared-Nothing (OLAP) table (where data is stored on the BE's local disks directly, not on S3), StarRocks uses the Page Cache instead of the Data Cache. Page Cache is memory-only and will show up in the profile as 
PageCacheHitBytes
or similar, but it won't use the 110GB disk space you see in the CN metrics. 2. The Metric Name varies by Version Depending on your StarRocks version, the metric might be named differently in the profile. Look for any of these under the 
SCAN
or 
OLAP_SCAN
operator: * 
BlockCacheReadBytes
(Common in v2.5 - v3.0) * 
DataCacheReadBytes
(Common in v3.1+) * 
RemoteReadBytes
(If this is high and the others are 0, you are missing the cache entirely). 3. The Query is too small for the "Populate" Threshold With 
LIMIT 10
, the query might be completing so fast that it doesn't trigger the standard caching logic, or it might be hitting the Query Cache (Result Cache) if you've run it before. * Check for Query Cache: If you see 
QueryCacheHit: true
or a 
CacheOperator
at the top of the profile, the query didn't even reach the scan node because the result was already cached in memory. * Check the Scan Node: Look for the section titled 
OLAP_SCAN_OPERATOR
or 
HdfsScanNode
. If that section exists but lacks 
DataCache
metrics, it means the Data Cache was bypassed. How to Force Verification To rule out the "small query" or "mode" issues, try this: 1. Force Cache Population:
Copy code
sql
    SET populate_datacache_mode = 'always';
    SELECT count(*) FROM your_table; -- Run a full scan to ensure data is pulled
2. Check 
EXPLAIN VERBOSE
again: Even if it doesn't show hits, 
EXPLAIN VERBOSE
must show 
dataCacheOptions
. Look very closely at the 
ScanNode
section. If you don't see 
dataCacheOptions={populate: ...}
, then the Data Cache is not active for this table type. Example of what to look for:
Copy code
text
    0:OLAP_SCAN_OPERATOR
       ...
       dataCacheOptions={populate: true}
Summary Checklist: * Is it a Lake Table or External Table? (Data Cache only works for these). * Are you looking at the Profile? (Use 
SELECT get_query_profile('<id>');
). * Search the profile text for the word 
Cache
. If you find 
PageCache
, you are using a local table. If you find nothing, the Data Cache is likely disabled for that session or table. Can you confirm: Is this an internal table (created with 
ENGINE=OLAP
) or an external table (Hive/Iceberg)? And what is your StarRocks version? References • knowledge/admin_and_operation/shared_data_compaction.md
m
@Rocky I tried this SET populate_datacache_mode = 'always'; but I don't see any specific cache related info in the query profile as well. I'm in 4.0.8 shared data version
r
Since you are using a shared-data (lake) cluster, you should definitely see cache metrics in the Query Profile if the feature is active. If you don't see 
DataCacheReadBytes
, it usually indicates the query is bypassing the Data Cache or the metrics are being obscured. Here is a step-by-step checklist to find where the cache info is hidden: 1. Confirm the Scan Operator in the Profile In version 4.0.x (and 3.x), the metrics are located inside the Scan Operator. * Generate the profile: 
SET enable_profile = true;
* Run your query. * Get the profile: 
SELECT get_query_profile('<id>');
* Search for a block labeled 
LAKE_SCAN_OPERATOR
or 
OLAP_SCAN_OPERATOR
. Inside that block, look specifically for: * 
DataCacheReadBytes
: Data read from local SSD/HDD cache. * 
DataCacheWriteBytes
: Data fetched from S3/Remote and written to local cache (a miss). * 
BytesRead
: Total data read. 2. Check for Query Cache Interference With a 
LIMIT 10
query, StarRocks might be using the Query Cache (Result Cache), which stores the final result set in memory. If this happens, the query never even hits the scan node, so you won't see Data Cache metrics. * How to tell: Look for 
CacheOperator
or 
CacheProbe
metrics at the top of the profile. * How to bypass: Run 
SET enable_query_cache = false;
and try the query again. 3. Verify 
EXPLAIN VERBOSE
 You mentioned you checked 
EXPLAIN VERBOSE
. Please look for the 
LAKE_SCAN
or 
OLAP_SCAN
node in the output. You should see a line like this:
Copy code
text
dataCacheOptions={populate: true}
* If this line is missing: The Data Cache is likely disabled at the table or cluster level. * If it says `populate: false`: Use 
SET populate_datacache_mode = 'always';
(which you already tried) to force it. 4. Check Table and BE Configuration If the metrics are still missing, check these settings: * Table Property: Run 
SHOW CREATE TABLE <name>;
. Ensure it doesn't have 
"datacache.enable" = "false"
. (Default is true). * CN/BE Config: Check if the cache is actually enabled on the nodes. Run:
Copy code
sql
    ADMIN SHOW FRONTEND CONFIG LIKE '%starlet_use_star_cache%';
    -- Or check CN/BE conf file for:
    -- starlet_use_star_cache = true
* Cache Status API: You can verify the health of the cache directly from a CN node:
Copy code
bash
    curl http://<CN_IP>:<CN_HTTP_PORT>/api/datacache/app_stat
This will show you the global hit/miss rate for that specific node. Why 
LIMIT 10
might be tricky In some versions, a 
LIMIT
query that finishes extremely fast might not report full metrics if the "ScanRange" is too small to trigger the standard block cache logic. Try running a 
SELECT COUNT(*)
on the table; this forces a full scan and will definitely populate and show 
DataCache
metrics in the profile if everything is configured correctly. Summary: If 
EXPLAIN VERBOSE
does not show 
dataCacheOptions
, the cache is not active. If it does show them but the profile is empty, disable the Query Cache (
enable_query_cache = false
) and run a larger scan like 
COUNT(*)
to see the metrics. References • data_source/data_cache.md • using_starrocks/caching/block_cache.md • data_source/data_cache_observe.md • using_starrocks/caching/query_cache.md • deployment/shared_data/feature-support-shared-data.md
m
@Rocky there is no config added olike this ADMIN SHOW FRONTEND CONFIG LIKE '%starlet_use_star_cache%'; Empty set (0.01 sec)
r
In StarRocks 4.0.8 (Shared-Data), the reason you aren't seeing those metrics or configurations via 
ADMIN SHOW FRONTEND CONFIG
is that Data Cache is a Backend/CN-level feature, not a Frontend (FE) one. Here is exactly how to verify cache hits for specific columns in your version: 1. Correct way to check the Configuration 
ADMIN SHOW FRONTEND CONFIG
only shows FE-specific settings (like metadata handling). Since Data Cache runs on the CN/BE nodes, use this query instead:
Copy code
sql
-- Check if Data Cache is enabled (should be 'true' by default in 4.0.8)
SELECT * FROM information_schema.be_configs 
WHERE NAME = 'starlet_use_star_cache';

-- Check where the cache is stored
SELECT * FROM information_schema.be_configs 
WHERE NAME = 'storage_root_path';
_Note: If 
starlet_use_star_cache
is 
true
, the cache is active._ 2. Finding the Metrics in the Profile For a "Shared Data" cluster, the scan node in your query profile will be named 
LAKE_SCAN_OPERATOR
. 1. Run your query with 
LIMIT 10
. 2. Get the profile: 
SELECT get_query_profile('<query_id>');
. 3. Search for the 
LAKE_SCAN_OPERATOR
 section. 4. Look for these specific lines: * 
DataCacheReadBytes
: If this is greater than 0, you hit the disk/memory cache. * 
DataCacheWriteBytes
: If this is greater than 0, it was a cache miss (the data was fetched from S3/HDFS and written to the local cache). * 
BytesRead
: The total data processed for those specific columns. 3. Why it might be "hidden" with 
LIMIT 10
 If you still don't see these metrics, one of two things is happening: * Query Cache (Result Cache) is hitting: If you run the exact same 
LIMIT 10
query twice, StarRocks might be returning the final result from memory without even touching the disks. * Fix: Run 
SET enable_query_cache = false;
before your query to force it to go to the Scan layer. * Asynchronous Population: By default, StarRocks sometimes populates the cache asynchronously to avoid slowing down the first query. * Fix: Run the query 2-3 times. On the first run, you should see 
DataCacheWriteBytes
. On subsequent runs, you should see 
DataCacheReadBytes
and 
DataCacheWriteBytes
should be 
0
. 4. Verify Column-Level caching StarRocks caches data in blocks (usually 1MB). When you select only a "few columns," StarRocks only fetches the blocks associated with those specific columns. To prove it: 1. Run 
SELECT col_a FROM table WHERE ... LIMIT 10;
. Check the profile for 
DataCacheReadBytes
. 2. Run 
SELECT col_b FROM table WHERE ... LIMIT 10;
. You will likely see 
DataCacheWriteBytes
because 
col_b
hasn't been cached yet, even though 
col_a
was. Summary for 4.0.8 Shared Data: * Check 
be_configs
for 
starlet_use_star_cache
. * Disable 
enable_query_cache
to ensure you aren't hitting the result cache. * Look for 
DataCacheReadBytes
inside the 
LAKE_SCAN_OPERATOR
 in the profile. References • data_source/data_cache.md • best_practices/query_tuning/query_profile_operator_metrics.md
m
@Rocky both are true and active but in profile nothing like 
DataCacheReadBytes
is there
r
In StarRocks 4.0.8 (and 3.3+), a significant refactor occurred to unify the Data Cache across internal Lake tables and external tables. If you have confirmed that 
starlet_use_star_cache
is 
true
in 
be_configs
but don't see 
DataCacheReadBytes
, it is likely due to one of the following: 1. New Metric Names (Refactored Metrics) In very recent versions, especially after the "Unified DataCache" refactor, metrics in the profile may have been renamed or grouped differently. Look for these instead: * 
BlockCacheReadBytes
: Some builds use this instead of 
DataCache
. * 
AppIOBytesRead
 vs. 
FSBytesRead
: * If 
AppIOBytesRead
is larger than 
FSBytesRead
, the difference is what came from the Data Cache. * 
FSBytesRead
specifically tracks what was pulled from remote storage (S3/HDFS). * 
DiskCacheReadBytes
 / 
MemCacheReadBytes
: Since the cache was split into disk and memory engines in 4.0, these specific metrics may appear in the 
LAKE_SCAN_OPERATOR
section. 2. The 
LIMIT 10
Short-Circuit With such a small query, StarRocks might be performing a Short-Circuit Read. If the query finishes in a few milliseconds, the BE might not flush the asynchronous counter metrics into the profile for that specific fragment. * Test: Run 
SELECT count(*) FROM table
or 
SELECT sum(some_col) FROM table
. This forces a full scan of at least one column and will definitely trigger the metric reporting. 3. Check for the "LAKE_SCAN_OPERATOR" In Shared-Data mode, do not look for the generic 
OLAP_SCAN
. You must find the block starting with: 
LAKE_SCAN_OPERATOR  (id=0)
 If you see this block but it only shows 
BytesRead
and no cache metrics, it means the query is fetching data directly from the object storage (S3) and either failing to cache it or bypassing it. 4. Verification via "EXPLAIN ANALYZE" Instead of a regular profile, try running:
Copy code
sql
EXPLAIN ANALYZE SELECT ... LIMIT 10;
This provides a more structured view of where the time and data are going. Look for the 
Scan
node in the output and see if it explicitly lists Remote Read vs Local Read. 5. Check "SHOW BACKENDS" To see if the cache is actually being used globally (not just for your query), run:
Copy code
sql
SHOW BACKENDS\G
Look at the 
DataCacheMetrics
 column. If the 
DiskUsed
or 
HitRate
is 0 across all nodes, then the cache is active but not actually "warm" or being written to. Summary Checklist: 1. Is the table actually in the Lake? (Ensure 
ENGINE=OLAP
and it's a shared-data cluster). 2. Disable Result Cache: Run 
SET enable_query_cache = false;
to ensure you aren't hitting the memory result cache. 3. Check for `populate: true`: Run 
EXPLAIN VERBOSE
and verify 
dataCacheOptions={populate: true}
appears under the scan node. If it says 
false
, the query won't use the cache regardless of other settings. Note on version 4.0.8: This version is at the very leading edge of the StarRocks release cycle. If you still see no metrics after a full 
COUNT(*)
scan, it may be worth checking the BE logs (
<http://be.INFO|be.INFO>
) for any errors starting with 
StarCache
or 
DataCache
, which might indicate the cache failed to initialize on disk. References • best_practices/query_tuning/query_profile_operator_metrics.md • administration/management/monitoring/metrics.md
m
@Rocky I dont see cache info in profile for starocks cloud native tables but I see for hudi external catalog tables, anythig missing ?
r
In StarRocks 4.0.8 (Shared-Data), even though both external (Hudi) and internal (Cloud-Native) tables use the same unified Data Cache system, they often report their cache hits differently in the Query Profile due to the underlying storage operators. If you see cache metrics for Hudi but not for Cloud-Native tables, please check the following: 1. Check Table-Level Properties Unlike external tables, Cloud-Native (Lake) tables have a specific table property that controls whether they are allowed to use the local disk cache. If this is disabled, session variables like 
populate_datacache_mode
will have no effect. Run:
Copy code
sql
SHOW CREATE TABLE <your_cloud_native_table>;
Look for 
"datacache.enable" = "true"
. If it is missing or set to 
false
, the table will bypass the Data Cache entirely. You can enable it via:
Copy code
sql
ALTER TABLE <name> SET ("datacache.enable" = "true");
2. Metric Name Difference: 
DataCache
vs 
PageCache
 For internal/Cloud-Native tables, StarRocks heavily utilizes the Page Cache (in-memory) in addition to the Block Cache (disk). External tables usually report everything under 
DataCacheReadBytes
. In your Query Profile, look inside the 
LAKE_SCAN_OPERATOR
(the operator used for cloud-native tables) for these specific metrics: * 
PageCacheHitBytes
: Data served from the in-memory cache. * 
PageCacheMissBytes
: Data that had to be fetched from disk or remote. * 
DataCacheReadBytes
: Data served specifically from the local SSD/disk block cache. If your query is small (
LIMIT 10
), it is very likely hitting the Page Cache (memory) entirely, which may be why you aren't seeing 
DataCache
(disk) metrics incremented. 3. Verify with 
EXPLAIN VERBOSE
 Run 
EXPLAIN VERBOSE
on your query against the cloud-native table. Look for the 
LAKE_SCAN
node. * Confirm: 
dataCacheOptions={populate: true, ...}
appears in the output. * If it shows `populate: false`: The optimizer has decided the query shouldn't be cached (common for very small scans). Setting 
SET populate_datacache_mode = 'always';
usually fixes this, but it must be applied to the session correctly. 4. Check for Short-Circuit/Metacache For Cloud-Native tables, StarRocks also caches metadata (tablet/segment info). * If your query is hitting the Metacache, it might resolve the scan so quickly that the standard IO metrics aren't fully flushed to the profile for a 
LIMIT 10
query. * Test: Run a 
SELECT COUNT(*)
or a larger scan. This forces a full scan of the data and will guarantee that if the cache is working, the metrics appear in the profile. 5. Backend Global Status To ensure the cache is actually functioning for internal tables at the system level, check:
Copy code
sql
SHOW BACKENDS\G
Look at the 
DataCacheMetrics
 column. If 
DiskUsed
is increasing when you query the cloud-native table but the profile is empty, it's a reporting issue in the 
LAKE_SCAN_OPERATOR
for that specific build, and you should look for 
AppIOBytesRead
or 
FSBytesRead
(where 
AppIO > FS
implies a cache hit). References • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache_troubleshooting.md • best_practices/query_tuning/query_profile_operator_metrics.md References • data_source/data_cache.md • data_source/data_cache_troubleshooting.md • best_practices/query_tuning/query_profile_operator_metrics.md
m
@Rocky datacache is already enabled and I set "datacache.partition_duration" = "10 DAY", to table and itis partitioned on start_stamp and I'm running query on table with this filter
Copy code
`start_stamp` >= DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -2 month))    AND `start_stamp` < DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL 15 day))
I can see readdisk along with readremote as I should see disk should be 0 right?
Copy code
"CompressedBytesReadLocalDisk": "5.402 MB",
              "__MAX_OF_CompressedBytesReadLocalDisk": "922.970 KB",
              "__MIN_OF_CompressedBytesReadLocalDisk": "0.000 B",
              "CompressedBytesReadRemote": "1.833 GB",
              "__MAX_OF_CompressedBytesReadRemote": "43.489 MB",
              "__MIN_OF_CompressedBytesReadRemote": "0.000 B",
r
The reason you see 1.833 GB being read from Remote storage instead of 0 is due to your 
datacache.partition_duration
 setting. 1. The Conflict: 10 Days vs. 2 Months You set 
"datacache.partition_duration" = "10 DAY"
. This property tells StarRocks: "Only store data in the local disk cache for partitions that fall within the last 10 days." * Your Query Filter: 
start_stamp
>= -2 months to +15 days. * Your Cache Window: Only the last 10 days. * Result: Any data older than 10 days (which is the bulk of your 2-month range) is strictly forbidden from using the disk cache. StarRocks will pull that data directly from S3/HDFS every time, resulting in the high 
CompressedBytesReadRemote
value you are seeing. The 5.402 MB you see in 
CompressedBytesReadLocalDisk
represents the small portion of data from the partitions that actually fall within that 10-day window. 2. How to fix this If you want that 1.8 GB to come from the local disk, you must extend the partition duration to cover your query range:
Copy code
sql
ALTER TABLE <table_name> SET ("datacache.partition_duration" = "65 DAY");
After running this, the first query will still show 
CompressedBytesReadRemote
as it fetches the data to fill the cache. The second query (and subsequent ones) should then show 
CompressedBytesReadRemote
near 0. 3. Other reasons for "Remote Reads" If you increase the duration and still see remote reads, check these two factors: * Cache Capacity: If your BE/CN local disks are full, StarRocks will evict old data to make room for new data. Check 
SHOW BACKENDS\G
and look at 
DataCacheMetrics
to see if 
DiskUsed
is at its limit. * Cold Start: As mentioned, the very first time you query a specific "block" of data after enabling the cache or changing the duration, it must be fetched from remote storage to populate the local disk. Summary of your Profile Metrics: * 
CompressedBytesReadRemote
(1.833 GB): Data from partitions older than 10 days (ignored by cache) + any "new" data within the 10-day window not yet cached. * 
CompressedBytesReadLocalDisk
(5.402 MB): Data from partitions within the last 10 days that was already present on your local SSD. Recommendation: Increase your 
datacache.partition_duration
to at least 
60 DAY
to match your typical query patterns. References • data_source/data_cache.md • deployment/shared_data/feature-support-shared-data.md • best_practices/query_tuning/query_profile_operator_metrics.md • sql-reference/sql-statements/data-definition/ALTER_TABLE.md • data_source/data_cache.md • best_practices/query_tuning/query_profile_operator_metrics.md • data_source/data_cache_troubleshooting.md
m
@Rocky I tried now running query with
Copy code
`start_stamp` >= DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -2 month))    AND `start_stamp` < DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -15 day))
with profile cache info
Copy code
"CompressedBytesReadLocalDisk": "3.598 KB",
              "__MAX_OF_CompressedBytesReadLocalDisk": "192.000 B",
              "__MIN_OF_CompressedBytesReadLocalDisk": "0.000 B",
              "CompressedBytesReadRemote": "1.538 GB",
              "__MAX_OF_CompressedBytesReadRemote": "43.267 MB",
              "__MIN_OF_CompressedBytesReadRemote": "4.475 MB",
              "CompressedBytesReadRequest": "125.191 MB",
              "__MAX_OF_CompressedBytesReadRequest": "3.279 MB",
              "__MIN_OF_CompressedBytesReadRequest": "923.492 KB",
              "CompressedBytesReadTotal": "1.538 GB",
              "__MAX_OF_CompressedBytesReadTotal": "43.267 MB",
              "__MIN_OF_CompressedBytesReadTotal": "4.475 MB",
r
This profile confirms exactly why you are seeing remote reads: your query is looking at "Cold Data" that falls outside your cache window. Why this is happening: 1. Your Setting: 
"datacache.partition_duration" = "10 DAY"
* This tells StarRocks: "Only cache data where the partition (
start_stamp
) is within the last 10 days." 2. Your Query Range: From 60 days ago to 15 days ago. * All of the data in this query is older than 10 days. * Because the data is older than your 10-day limit, StarRocks considers it Cold. * To save local disk space, StarRocks refuses to cache it and pulls it directly from remote storage (S3/HDFS). This is why 
CompressedBytesReadRemote
is 1.538 GB (everything) and 
CompressedBytesReadLocalDisk
is essentially 0 (3.5 KB is likely just a small metadata footer). How to Fix It: You need to expand your "Hot Data" window to include the dates you are querying. If you want to query data from 2 months ago and have it hit the cache, you must set the duration to at least 60 days. Run this command:
Copy code
sql
ALTER TABLE <your_table_name> SET ("datacache.partition_duration" = "65 DAY");
What to expect after the change: 1. First Run: You will still see 
CompressedBytesReadRemote
as 1.5 GB because StarRocks has to fetch it from the cloud to bring it onto the local disk for the first time. 2. Second Run: You should see 
CompressedBytesReadRemote
drop to near 0 and 
CompressedBytesReadLocalDisk
rise to ~1.5 GB. Summary of the metrics in your profile: * 
CompressedBytesReadRemote
(1.538 GB): The actual data pulled from S3/HDFS. * 
CompressedBytesReadTotal
(1.538 GB): The total data processed (all remote). * 
CompressedBytesReadLocalDisk
(3.598 KB): Metadata only; no actual table data was found in or allowed into the cache. Note: Ensure your BE nodes have enough disk space allocated for the cache to hold 60+ days of data. You can check cache capacity and usage by running 
SHOW BACKENDS\G
and looking at the 
DataCacheMetrics
column.
m
@Rocky I am testing by running query falling outside of cache and see if it is hitting cache outside partition duration and within partition duration filters, still both remote and disk being read even though small data. "datacache.partition_duration" = "10 DAY", 
start_stamp
>= DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -5 day)) AND 
start_stamp
< DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -2 day)) this should hit cache but the table is not hitting cache fully but local is very less and remote is more
Copy code
"CompressedBytesReadLocalDisk": "624.000 B",
              "__MAX_OF_CompressedBytesReadLocalDisk": "112.000 B",
              "__MIN_OF_CompressedBytesReadLocalDisk": "0.000 B",
              "CompressedBytesReadRemote": "79.849 MB",
              "__MAX_OF_CompressedBytesReadRemote": "13.377 MB",
              "__MIN_OF_CompressedBytesReadRemote": "0.000 B",
              "CompressedBytesReadRequest": "6.154 MB",
              "__MAX_OF_CompressedBytesReadRequest": "1.027 MB",
              "__MIN_OF_CompressedBytesReadRequest": "0.000 B",
              "CompressedBytesReadTotal": "79.849 MB",
              "__MAX_OF_CompressedBytesReadTotal": "13.377 MB",
              "__MIN_OF_CompressedBytesReadTotal": "0.000 B",
r
Even though your query filter (last 5 to 2 days) is now inside the 
"datacache.partition_duration" = "10 DAY"
window, you are seeing a cache miss (80MB Remote / 0MB Disk) because of how StarRocks populates the cache. For Cloud-Native (Shared-Data) tables, the data cache follows these behaviors: 1. Asynchronous Cache Population (Default) By default, StarRocks uses asynchronous population. When you run a query that misses the cache: 1. StarRocks reads the data directly from Remote Storage (S3/HDFS) to return your results as fast as possible. 2. Simultaneously, it triggers a background task to pull that data into the Local Disk Cache. 3. The first query will always show Remote Reads. You must run the same query (or a query hitting the same data) 2 or 3 times to see the 
CompressedBytesReadLocalDisk
metric increase and the Remote metric drop to zero. 2. Verify with 
CACHE SELECT
(Manual Warmup) If you want to force the data into the cache without "guessing" if a query hit it, use the warmup command:
Copy code
sql
CACHE SELECT * FROM <table_name> 
WHERE start_stamp >= DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -5 day)) 
  AND start_stamp < DATE_TRUNC('day', DATE_ADD(CURRENT_TIMESTAMP(), INTERVAL -2 day));
Wait for this to finish, then run your query. You should see it hit the disk cache immediately. 3. Check "I/O Adaptation" StarRocks has a feature called I/O Adaptation. If the system detects that your local disks are under high I/O pressure, it will "short-circuit" and read from Remote storage even if the data could be cached, to prevent the disk from becoming a bottleneck. You can try disabling this in your session to see if it forces a cache hit:
Copy code
sql
SET enable_datacache_io_adapter = false;
4. Synchronous Population (Not Recommended for Production) If you want the very first query to wait until data is cached before returning (ensuring a 100% "hit" or "populate" in the profile), you can set:
Copy code
sql
SET enable_datacache_async_populate_mode = false;
Note: This will make the first query significantly slower because it has to write to local disk before finishing. 5. Confirm Cache Space If you have run the query multiple times and it is still reading from Remote, your local cache might be full and evicting data immediately. Check the status:
Copy code
sql
SHOW BACKENDS\G
Look at 
DataCacheMetrics
. If 
DiskUsage
is at 100% (e.g., 
999GB/1000GB
), your 10-day window might be larger than your physical disk can hold, causing constant eviction. Summary Checklist: 1. Run the query 2-3 times. The first run populates; subsequent runs read. 2. Increase 
partition_duration
 if you plan to query older data (as discussed previously). 3. Check 
SHOW BACKENDS
 to ensure you aren't out of disk space for the cache. References • data_source/data_cache_troubleshooting.md • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache.md References • using_starrocks/caching/block_cache.md • deployment/shared_data/s3.md • deployment/shared_data/feature-support-shared-data.md • data_source/data_cache_troubleshooting.md • deployment/shared_data/minio.md
m
@Rocky how can I remove the set parameter of partition_duration for table?
r
To remove the 
datacache.partition_duration
constraint from your table so that all partitions are eligible for the local disk cache, you should set the property to an empty string. In StarRocks, there is no 
UNSET
command for table properties. Instead, you overwrite the existing property with an empty value:
Copy code
sql
ALTER TABLE <table_name> SET ("datacache.partition_duration" = "");
How to verify: After running the command, you can verify that the property has been removed or cleared by checking the table definition:
Copy code
sql
SHOW CREATE TABLE <table_name>;
What happens next: 1. Cache Eligibility: Now, data from any partition (even those older than 10 days) is allowed to be stored in the local disk cache. 2. First Run (Populating): The very next time you run a query for old data, it will still show 
CompressedBytesReadRemote
because StarRocks must fetch the data from S3/HDFS one last time to fill the local cache. 3. Subsequent Runs: Once the cache is "warmed up" for those old partitions, you should see 
CompressedBytesReadRemote
drop to 0 and 
CompressedBytesReadLocalDisk
increase. Note: If you want to force the data into the cache immediately without waiting for a real query, you can use the manual warmup command:
Copy code
sql
CACHE SELECT * FROM <table_name> WHERE <your_range_filter>;
References • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • table_design/data_distribution/dynamic_partitioning.md • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md
m
Copy code
alter table call_dispose_20260812 set ("datacache.partition_duration" = "");
ERROR 5064 (42000): Getting analyzing error. Detail message: Cannot parse text to Duration.
mysql>
@Rocky giving above error
r
The error occurs because the parser for the 
datacache.partition_duration
property is strict and expects a valid duration format (like 
10 DAY
, 
1 MONTH
). Once this property is set on a table, StarRocks currently does not support "unsetting" or deleting it via the empty string 
""
. Solution: Set a very large duration The standard way to effectively "remove" the restriction is to set the duration to a value so large that it covers all your historical data. This ensures that any data, no matter how old, is eligible for the cache. Run the following command:
Copy code
sql
ALTER TABLE call_dispose_20260812 SET ("datacache.partition_duration" = "100 YEAR");
Why this works: * By setting it to 100 years, you are telling the cache: "Keep any data that is less than 100 years old." * This removes the "Cold Data" restriction for your 2-month-old data without needing to find a specific "unset" command. * The property will still exist in your 
SHOW CREATE TABLE
output, but it will no longer block any of your queries from hitting the cache. Verification: 1. Run the 
ALTER
command above. 2. Run your query once to populate the cache (it will still show 
RemoteRead
). 3. Run the query a second time. 4. Check the profile: 
CompressedBytesReadLocalDisk
should now be high, and 
CompressedBytesReadRemote
should be near zero or 
CompressedBytesReadTotal
should show the data is being served from the local disk. Note: If you ever need to disable the cache entirely for the table, you can use:
Copy code
sql
ALTER TABLE call_dispose_20260812 SET ("datacache.enable" = "false");
References • table_design/data_distribution/Temporary_partition.md • knowledge/usage/best-practice.md • sql-reference/sql-statements/table_bucket_part_index/ALTER_TABLE.md • table_design/data_distribution/Data_distribution.md • sql-reference/sql-statements/table_bucket_part_index/TRUNCATE_TABLE.md • sql-reference/sql-statements/table_bucket_part_index/DELETE.md • data_source/catalog/hive_catalog.md
m
@Rocky how does it look at old data, if I ingest 10days old date data the to table , does it look based on current time load or it goes to 10days ago date when considering duration of partition duration cache?
r
The 
datacache.partition_duration
property is based on the Partition Key value (the actual date in your data), not the time the data was ingested. StarRocks calculates the duration by comparing the Upper Bound of the Partition to the Current System Time. How it works with your example: If you ingest data today (August 13) that contains a date from 10 days ago (August 3): 1. Partition Key Benchmark: StarRocks looks at the partition containing "August 3". 2. Comparison: It calculates: 
Current Time (Aug 13) - 10 Days = Aug 3
. 3. Result: Since the data is exactly 10 days old based on the calendar date, it is right on the edge of the "cold" threshold. If the partition's upper bound is older than the current time minus 10 days, it is considered Cold Data. Key Behaviors to Note: * Load Time vs. Data Time: It does not care that you loaded the data "just now." It only cares what "time" the data represents according to your partition column. * Ingestion Caching: Interestingly, for Cloud-Native (Shared-Data) tables, data being currently loaded is often written to the local cache as a side effect of the write process, regardless of the 
partition_duration
. However, once that data is evicted from the cache (due to space), it will not be re-cached by future queries if it falls outside the 
partition_duration
window. * The "Moving Window": Because it is relative to the 
CURRENT_TIMESTAMP
, a partition that is "Hot" today (9 days old) will automatically become "Cold" tomorrow (10 days old) without you changing any settings. Recommendation: If you are frequently loading and querying "historical" data that is 10+ days old, you should either: 1. Increase the duration: 
SET ("datacache.partition_duration" = "15 DAY")
. 2. Remove the restriction entirely (as suggested previously) by setting it to a very large value like 
"100 YEAR"
. References • table_design/data_distribution/expression_partitioning.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md • table_design/data_distribution/dynamic_partitioning.md References • best_practices/partitioning.md • table_design/data_distribution/expression_partitioning.md • sql-reference/System_variable.md • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md • table_design/data_distribution/dynamic_partitioning.md
m
@Rocky If I have some transaction data with day partition and partition duration - 10days and some data inserted to 20days ago partition now , will it be considered as hot to cache or not?
r
It will be considered Cold, but with one important technical exception regarding how ingestion works in StarRocks. 1. The Logic (The "Cold" Rule) StarRocks determines "Hot" vs "Cold" by comparing the Partition's Upper Bound to the Current Time. * Current Time: Aug 13 * Partition Duration: 10 Days (Limit = Aug 3) * Your Data's Partition: 20 Days ago (July 24) Because July 24 is older than Aug 3, this partition is logically Cold. 2. The Ingestion Exception (The "Free Pass") Even though the partition is "Cold," StarRocks has a special behavior during data loading: * Automatic Cache Population: When you load data into a Shared-Data (Cloud-Native) table, StarRocks automatically writes that data to the local disk cache as it writes it to S3/Object Storage. * The Benefit: This means your 20-day-old data will actually be in the cache immediately after you load it, even though it is technically "cold." * The Catch: The 
partition_duration
rule does not apply to the initial write, but it does apply to future reads. 3. What happens next? * Immediate Queries: If you query that 20-day-old data right after loading, it will be fast because it’s still in the local cache from the load. * After Eviction: If that data is eventually pushed out of the cache (e.g., because the disk got full or the BE restarted), StarRocks will see it is "Cold" (outside the 10-day window). * The "Cold" Behavior: The next time you query it, StarRocks will fetch it from S3 but will not save it back to the local disk cache because it falls outside your 10-day duration. Summary Table Scenario | Behavior for 20-day-old data (10-day limit) At moment of Ingestion | Cached. Written to local disk during the load process. Querying right after load | Cache Hit. Served from the local disk. Querying after cache eviction | Cache Miss. Read from S3 and NOT re-cached. Recommendation: If you need this 20-day-old data to stay "Hot" and be re-cached if it ever drops out, you must increase your duration:
Copy code
sql
ALTER TABLE your_table SET ("datacache.partition_duration" = "25 DAY");
References • using_starrocks/caching/block_cache.md • deployment/shared_data/feature-support-shared-data.md • table_design/data_distribution/dynamic_partitioning.md • best_practices/partitioning.md • table_design/data_distribution/Data_distribution.md • knowledge/usage/best-practice.md References • deployment/shared_data/feature-support-shared-data.md • knowledge/admin_and_operation/shared_data_compaction.md
m
@Rocky how much time the ingestion data will be stored in cache?
r
There is no fixed time that ingested data stays in the cache. Instead, its duration in the cache depends on space availability and access frequency. Here is how the cache lifecycle works for your ingested data: 1. The "Space-First" Rule The Data Cache is managed by a disk-space quota (typically set by the BE configuration 
starlet_star_cache_disk_size_percent
, which defaults to 90% of the disk). * Data stays in the cache as long as there is enough free space on the disk. * When the cache disk becomes full, StarRocks must remove (evict) old data to make room for new data. 2. The Eviction Policy (LRU/SLRU) StarRocks uses LRU (Least Recently Used) or SLRU (Segmented LRU) to decide what to delete: * SLRU (Default in v3.4+): This policy is more advanced; it protects "frequently accessed" data from being evicted by a one-time large load or a one-time large query. * If you stop querying the data: If other newer data is being loaded or more popular data is being queried, your 20-day-old data will eventually be the "least recently used" and will be deleted from the disk to make space. 3. Special Case: Data outside 
partition_duration
 For your specific case (data that is 20 days old with a 10-day duration limit): * Ingestion: It is written to the cache immediately. * While it's there: It stays as long as there is space (just like "Hot" data). * After Eviction: Once it is pushed out of the cache due to space limits, it cannot come back. Because it is outside the 10-day window, StarRocks will never re-cache it from S3. How to see if it's still there? You can monitor the cache status using the Query Profile. Look for: * 
DataCacheReadBytes
: If this is high, the data is being served from the cache. * 
CompressedBytesReadRemote
: If this is high, the data has been evicted (or was never cached) and is being pulled from S3. Summary: Your data stays in the cache until the disk fills up and other data becomes "more popular" than it. If it's outside your 
partition_duration
, it only gets one life in the cache (the ingestion life). References • deployment/shared_data/feature-support-shared-data.md • sql-reference/System_variable.md • data_source/data_cache.md • using_starrocks/caching/block_cache.md • administration/management/BE_configuration.md • faq/shared_data_faq.md
m
@Rocky is there any config to control the cache from ingestion either size or duration? and this ingestion cache is also under same 90% of cache capacity?
r
For StarRocks cloud-native (shared-data) tables, the "ingestion cache" (also called write-through cache) is tightly integrated with the general Data Cache. Here is how you can control it and how it behaves: 1. Control via 
datacache.enable
 The primary way to control if data is cached during ingestion is the table property 
datacache.enable
. * 
"datacache.enable" = "true"
(Default): Data is written to both the object storage (S3/GCS) and the local disk cache simultaneously during the load. * `"datacache.enable" = "false"`: Data is written only to the object storage. No local cache is generated during ingestion, and no future queries will be cached for this table. There is currently no built-in property to enable caching for queries while disabling it for ingestion; they are controlled by the same toggle. 2. Is there a "Duration" or "Size" limit for Ingestion Cache? * No Duration Limit: The 
datacache.partition_duration
property does not apply to the initial ingestion. Even if you load data that is 100 days old into a table with a 10-day duration, it will be cached during the load. * No Separate Size Limit: The ingestion cache is not a separate "bucket." It uses the same shared pool as your query cache. * Capacity: It is governed by the same BE configuration: * 
starlet_star_cache_disk_size_percent
(Default: 80% or 90% of disk, depending on version). * 
datacache_disk_size
(Can be used to set a fixed byte limit instead of a percentage). 3. How Eviction Works Because ingestion cache and query cache share the same pool, they compete for space: 1. Shared Pool: When you load a massive amount of data, it can "push out" (evict) older cached data from previous queries if the disk reaches the capacity limit. 2. LRU/SLRU Logic: StarRocks uses a Least Recently Used (LRU) or Segmented LRU (SLRU) policy. If the ingested data is not queried, it will eventually become the "coldest" data and be the first to be evicted when new data needs space. 3. The "One Life" Rule: As mentioned before, if you ingest data that is outside your 
partition_duration
, once it is evicted due to space pressure, it will never be re-cached by future queries. Summary of Configurations Control Goal | Configuration / Property Enable/Disable Ingestion Cache | 
PROPERTIES ("datacache.enable" = "true/false")
Total Cache Size (Ingestion + Query) | BE Config: 
starlet_star_cache_disk_size_percent
Re-cache Duration (After eviction) | 
PROPERTIES ("datacache.partition_duration" = "X DAY")
Rocky's Tip: If you are worried about large loads wiping out your query cache, you can lower the 
starlet_star_cache_disk_size_percent
to leave more breathing room on the disk, or use the SLRU eviction policy (
datacache_eviction_policy = SLRU
in BE config) which is better at protecting frequently-read "hot" data from being evicted by a one-time large ingestion "burst. References • deployment/shared_data/feature-support-shared-data.md • using_starrocks/caching/block_cache.md • administration/management/BE_configuration.md • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md References • deployment/shared_data/feature-support-shared-data.md • deployment/shared_data/s3.md • deployment/shared_data/azure.md • sql-reference/sql-statements/table_bucket_part_index/CREATE_TABLE.md
5 Views
Open in Slack
PreviousNext
Powered by