< Rocky> I run starrocks 3 5 10 in shared data mode I have a StarRocks #questions-and-troubleshooting

<@U0A71G31CDV> I run starrocks 3.5.10 in shared-da...

Aleksandr Zakharchenko

04/07/2026, 9:06 PM

@Rocky I run starrocks 3.5.10 in shared-data mode. I have an async materialized view reading data from external iceberg catalog iceberg_catalog_hms. The materialized view currently has 0 rows. When I execute REFRESH MATERIALIZED VIEW my_mview FORCE - it returns with status SKIPPED. Materialized view still has zero rows. At the same time - if I execute underlying query directly, I do get the results

Rocky

04/07/2026, 9:07 PM

The behavior you're seeing—where a

REFRESH MATERIALIZED VIEW ... FORCE

returns with a

SKIPPED

status even though the base table has data—usually indicates that StarRocks' refresh scheduler or processor has determined there is no work to be done, or it has encountered a metadata state that prevents it from generating a refresh plan. In StarRocks 3.5.10 with an Iceberg Catalog, there are a few specific reasons why this might happen: 1. Partition Metadata Issues (Known Issue) There is a known behavior in certain 3.5.x versions where StarRocks might skip a refresh if it cannot correctly identify the partitions in the base Iceberg table. * Expired Snapshots: If the Iceberg table has snapshots that have expired or if the current snapshot is not being correctly perceived by the StarRocks FE, the refresh might skip. * Empty Partition Set: If the Materialized View (MV) is partitioned and StarRocks' metadata about the Iceberg table's partitions is out of sync, it may calculate an empty list of partitions to refresh. Even with

FORCE

, if the "partitions to refresh" list is resolved to empty, the status can be

SKIPPED

. 2. Check the MV Activity Status If the materialized view has become inactive (e.g., due to a schema change in the Iceberg table or a connection issue during a previous metadata sync), StarRocks may skip refresh tasks. * Run:

SHOW MATERIALIZED VIEWS LIKE 'my_mview'\G

* Check the

is_active

column. If it is

false

, you must reactivate it:

Copy code

sql
    ALTER MATERIALIZED VIEW my_mview ACTIVE;

Then try the

REFRESH ... FORCE

again. 3. Debugging via
task_runs
To find the exact reason for the

SKIPPED

status, you should inspect the metadata in the

information_schema

. This will provide a "hidden" message explaining the decision to skip.

Copy code

sql
SELECT 
    TASK_NAME, 
    CREATE_TIME, 
    STATE, 
    EXTRA_MESSAGE 
FROM information_schema.task_runs 
WHERE TASK_NAME LIKE '%my_mview%' 
ORDER BY CREATE_TIME DESC 
LIMIT 5;

Look closely at the EXTRA_MESSAGE
field. It often contains a JSON object with a field like

planBuilderMessage

reason

that explains why the task was skipped (e.g., "no partition to refresh" or "base table has no data"). 4. Shared-Data Mode Specifics In shared-data mode, ensure that your FE is correctly communicating with the Iceberg HMS and that the metadata cache isn't stale. * Try manually refreshing the catalog metadata before refreshing the MV:

Copy code

sql
    REFRESH EXTERNAL TABLE iceberg_catalog_hms.db_name.table_name;

* Then execute the MV refresh:

Copy code

sql
    REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

Using

WITH SYNC MODE

will make the command wait until completion and often provides a more immediate error message if the skip happens during the planning phase. 5. Potential Bug in 3.5.10 There was a specific bug fixed in very recent 3.5 patches (and upcoming 3.5.11+) where Iceberg materialized views would skip updates if the base table contained non-monotonic snapshot timestamps or if certain multi-level partitioning logic failed to resolve. Recommendation: 1. Check

is_active

via

SHOW MATERIALIZED VIEWS

. 2. Review the

EXTRA_MESSAGE

information_schema.task_runs

. 3. If the MV is partitioned, ensure the partition column in the MV exactly matches the type and transform of the Iceberg partition. 4. If the issue persists despite

FORCE

, try recreating the MV with

REFRESH MANUAL

to see if the initial population works. References • sql-reference/sql-statements/materialized_view/CREATE_MATERIALIZED_VIEW.md • deployment/shared_data/azure.md

Rocky

04/07/2026, 9:07 PM

• using_starrocks/async_mv/use_cases/data_lake_query_acceleration_with_materialized_views.md • knowledge/usage/best-practice.md

Aleksandr Zakharchenko

04/07/2026, 9:13 PM

@Rocky - materialized view is created with refresh manual. I ran REFRESH EXTERNAL TABLE for all tables joined under mview - but to no avail. Your command returns the following: {"forceRefresh":true,"mvPartitionsToRefresh":[],"refBasePartitionsToRefreshMap":{},"basePartitionsToRefreshMap":{},"processStartTime":1775596249838,"executeOption":{"priority":80,"taskRunProperties":{"FORCE":"true","mvId":"12934901","warehouse":"default_warehouse"},"isMergeRedundant":false,"isManual":true,"isSync":true,"isReplay":false},"planBuilderMessage":{}}

Rocky

04/07/2026, 9:13 PM

Based on the

EXTRA_MESSAGE

JSON you provided, the reason your refresh is skipping is clear: "mvPartitionsToRefresh": []
and "refBasePartitionsToRefreshMap": {}
. This indicates that during the planning phase, StarRocks' refresh scheduler was unable to identify any partitions (or even a single "whole table" unit) to scan from your Iceberg base tables. Even though the

forceRefresh

flag is

true

, if the planner calculates an empty set of target partitions, the task transitions immediately to

SKIPPED

. Here is how to troubleshoot and resolve this in StarRocks 3.5.10: 1. Inspect the Snapshot and Partition State Since you are using an Iceberg catalog, StarRocks tracks the

snapshot-id

and partition list of the base tables. If the refresh planner can't resolve these, it skips. Run this command to see what StarRocks thinks of the relationship between the MV and the base table:

Copy code

sql
SELECT * FROM TABLE(inspect_mv_refresh_info('my_mview'));

* What to look for: Check if

base_table_visible_version

base_table_refresh_info

shows an empty value or an outdated snapshot ID. If it does, the MV's metadata is out of sync with the Iceberg catalog. 2. Check for Partition Column Mismatch In StarRocks 3.5.x, if your Materialized View is partitioned (using

PARTITION BY

), the partition keys must align strictly with the base Iceberg table. * If the Iceberg table is partitioned by a transform (e.g.,

days(ts)

), your MV must use the same column (

ts

). * StarRocks 3.5.10 supports

identity

year

month

day

, and

hour

transforms. If you use a different transform or a column that isn't a partition key in Iceberg, the refresh planner may fail to generate a plan and return an empty partition list. * Action: If your MV is partitioned, try creating a non-partitioned version of the MV as a test. If the non-partitioned version refreshes successfully, the issue is your

PARTITION BY

clause. 3. Case Sensitivity in External Catalogs There is a known behavior where StarRocks may fail to match partitions if there is a case mismatch between the MV definition and the Hive Metastore (HMS) metadata for Iceberg. * Action: Ensure the table names and column names in your

CREATE MATERIALIZED VIEW

statement exactly match the case shown in

SHOW CREATE TABLE iceberg_catalog_hms.db.table

. 4. Shared-Data Metadata Cache Bug StarRocks 3.5.10 contains a fix for a Guava cache bug related to Iceberg tables, but in shared-data mode, the FE might still be holding onto a stale view of the table's "latest" snapshot. * Action: Force a metadata reload of the specific table and then the MV:

Copy code

sql
    REFRESH EXTERNAL TABLE iceberg_catalog_hms.db_name.table_name;
    -- Use SYNC MODE to catch any planning-time errors immediately
    REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

5. Check "is_active" Status If the MV is marked as inactive, StarRocks will skip tasks.

Copy code

sql
SHOW MATERIALIZED VIEWS LIKE 'my_mview'\G

is_active

false

, check the

inactive_reason

. You can try to reactivate it:

Copy code

sql
ALTER MATERIALIZED VIEW my_mview ACTIVE;

Summary Recommendation The fact that

refBasePartitionsToRefreshMap

is empty means the planner doesn't even see the base table as a source to be read. If your MV query involves a Join, ensure that all tables in the join are actually Tables and not Iceberg Views, as StarRocks currently has limitations on using external catalog views as base objects for MVs (which can lead to "SKIPPED" or "Table not found" errors during refresh). References • using_starrocks/async_mv/materialized_view_task_run_details.md • sql-reference/sql-statements/materialized_view/CREATE_MATERIALIZED_VIEW.md

Rocky

04/07/2026, 9:13 PM

• using_starrocks/async_mv/use_cases/data_lake_query_acceleration_with_materialized_views.md • sql-reference/sql-functions/meta-functions/inspect_mv_refresh_info.md

Aleksandr Zakharchenko

04/07/2026, 9:15 PM

@Rocky - how do I force cache wipeout for this mview refresh?

Rocky

04/07/2026, 9:16 PM

To force a complete cache "wipeout" and resolve a refresh task that is skipping even with the

FORCE

flag, you need to clear several layers of metadata that StarRocks maintains. The fact that your

refBasePartitionsToRefreshMap

is empty means the FE Planner cannot see any data in the source Iceberg table, even if the data is physically there. 1. Force Catalog-Level Metadata Refresh While

REFRESH EXTERNAL TABLE

refreshes a single table,

REFRESH CATALOG

forces the FE to discard its cached view of the entire Iceberg/HMS structure. This is more aggressive and often clears "sticky" metadata states.

Copy code

sql
REFRESH CATALOG iceberg_catalog_hms;

2. Lower the Iceberg Metadata Expiration (FE Configuration) StarRocks FE caches Iceberg manifest files and metadata for a very long time by default (86,400 seconds / 24 hours). If the metadata is corrupted or stale in the cache,

REFRESH EXTERNAL TABLE

might occasionally fail to invalidate it properly in specific 3.5.x versions. You can temporarily set the expiration to

to force an immediate bypass of the cache for the next refresh attempt:

Copy code

sql
-- Run this on the leader FE
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_memory_cache_expiration_seconds" = "0");
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_disk_cache_expiration_seconds" = "0");

-- Attempt the refresh again
REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

-- Reset them back to defaults afterward
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_memory_cache_expiration_seconds" = "86400");
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_disk_cache_expiration_seconds" = "604800");

3. Clear the MV's Internal Version State StarRocks stores the "Last Refreshed Snapshot ID" for Iceberg tables in its own internal metadata. If this state becomes inconsistent (e.g., the MV thinks it's already caught up to a snapshot that actually contains 0 rows), it might skip. To reset the MV's internal "memory" of the base table: 1. Deactivate and Reactivate: This forces the FE to reload the MV's dependency graph.

Copy code

sql
    ALTER MATERIALIZED VIEW my_mview INACTIVE;
    ALTER MATERIALIZED VIEW my_mview ACTIVE;

2. Inspect the internal state: Run this and look for the

baseExternalTableInfoVisibleVersionMap

. If it shows an old snapshot or is empty, the FE isn't "seeing" the new Iceberg snapshots.

Copy code

sql
    SELECT inspect_mv_refresh_info('my_mview');

4. Check for "Empty Result" Caching (Query Level) If you have

query_cache

enabled, StarRocks might be caching the fact that the underlying query returned 0 rows. * Wipe Query Cache:

Copy code

sql
    SET GLOBAL enable_query_cache = false;
    -- Run refresh
    REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;
    SET GLOBAL enable_query_cache = true;

5. Why is
mvPartitionsToRefresh
empty? If the above don't work, the issue is likely Partition Alignment: * If your MV is partitioned (e.g.,

PARTITION BY dt

), StarRocks performs a "Partition Discovery" phase. If it cannot match the Iceberg partitions to the MV partitions, it results in an empty list. * Troubleshooting Step: Create a temporary MV with the exact same query but without the
PARTITION BY
clause. * If the non-partitioned MV works, the problem is your partition mapping/transform. * If the non-partitioned MV also skips, the FE cannot see the Iceberg snapshots at all (likely an HMS connection or permission issue). Summary of Actions 1.

REFRESH CATALOG iceberg_catalog_hms;

ALTER MATERIALIZED VIEW my_mview ACTIVE;

(Even if already active, this re-triggers metadata sync). 3.

REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

If it still skips, check the FE Leader log (

fe.log

) immediately after the skip. Search for the string

[MV] ... skip refresh

. It will usually log a specific reason like

base table snapshot not found

partition column type mismatch

. References

Rocky

04/07/2026, 9:16 PM

• using_starrocks/async_mv/materialized_view_task_run_details.md • sql-reference/sql-functions/meta-functions/inspect_mv_refresh_info.md

Aleksandr Zakharchenko

04/07/2026, 9:26 PM

wipe out stored snapshots?

Aleksandr Zakharchenko

04/07/2026, 9:29 PM

@Rocky - can I wipe out the stored snapshots?

Rocky

04/07/2026, 9:29 PM

In StarRocks, the "stored snapshots" (the metadata that tracks which version of the Iceberg table has already been processed) are kept in an internal FE map called the

baseExternalTableInfoVisibleVersionMap

. If your

REFRESH ... FORCE

is returning

SKIPPED

with an empty

mvPartitionsToRefresh

list, it means the StarRocks planner isn't even "seeing" the data in the base table to begin with—so it thinks there is nothing to refresh, even if you force it. Here is how you can effectively "wipe out" that metadata and force a total reset: 1. Identify the Stored Snapshot First, confirm what StarRocks currently has stored as the "last seen" version:

Copy code

sql
SELECT inspect_mv_refresh_info('my_mview');

Look for the

baseExternalTableInfoVisibleVersionMap

. If the

snapshot_id

there doesn't match your current Iceberg snapshot, the FE is out of sync. 2. The "Soft" Wipe (Metadata Reload) To force StarRocks to throw away its current understanding of the Iceberg table's structure and snapshots, run these in order:

Copy code

sql
-- 1. Clear the catalog-level metadata cache
REFRESH CATALOG iceberg_catalog_hms;

-- 2. Force the MV to rebuild its dependency and version mapping
ALTER MATERIALIZED VIEW my_mview INACTIVE;
ALTER MATERIALIZED VIEW my_mview ACTIVE;

-- 3. Attempt a synchronous refresh
REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

3. The "Hard" Wipe (Bypass all Caches) If the above fails, you likely have a "sticky" cache entry in the FE memory. You can force the FE to ignore its internal Iceberg cache by setting the expiration to 0 temporarily:

Copy code

sql
-- Run on Leader FE
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_memory_cache_expiration_seconds" = "0");

-- Perform the refresh
REFRESH MATERIALIZED VIEW my_mview FORCE WITH SYNC MODE;

-- Reset to default (approx 24 hours)
ADMIN SET FRONTEND CONFIG ("iceberg_metadata_memory_cache_expiration_seconds" = "86400");

4. The "Complete" Wipe If the MV is stuck due to a metadata inconsistency that

FORCE

won't fix, the only way to completely delete the stored version pointers is to Drop and Recreate the MV. * Because your MV currently has 0 rows, this is safe and will cost nothing in terms of data loss. * This removes the entry from the internal

baseExternalTableInfoVisibleVersionMap

entirely. Why is it still skipping? If after a

DROP/CREATE

it still says

SKIPPED

with

mvPartitionsToRefresh: []

, then the problem is not "stored snapshots"—it is Discovery: 1. Partition Transform Mismatch: In 3.5.10, if your Iceberg table uses a transform like

truncate

bucket

that isn't

identity/day/month/year/hour

, StarRocks may fail to map the partitions and return an empty list. 2. Iceberg V2 Equality Deletes: If your Iceberg table has many equality deletes, 3.5.10 might struggle to plan the scan if certain FE configs are not tuned, leading to an empty plan. 3. Empty "Base" Mapping: Your log showed

refBasePartitionsToRefreshMap: {}

. This is the smoking gun. It means the query planner evaluated your

SELECT

and concluded the source table has no partitions. Check if you are querying a View inside Iceberg or if the Iceberg table's

current-snapshot-id

is actually null in the HMS. Quick Test: Try to create the MV without a

PARTITION BY

clause. If a non-partitioned MV works but a partitioned one skips, the issue is strictly with the partition column mapping between StarRocks and Iceberg. References • sql-reference/sql-functions/meta-functions/inspect_mv_refresh_info.md • data_source/catalog/iceberg/iceberg_meta_table.md • sql-reference/sql-statements/materialized_view/CREATE_MATERIALIZED_VIEW.md

Rocky

04/07/2026, 9:29 PM

• knowledge/admin_and_operation/shared_data_compaction.md

2 Views

Open in Slack

Previous Next