Kenneth Oh
07/28/2026, 1:20 AMRocky
07/28/2026, 1:21 AMINSERT INTO
StarRocks supports sinking data into external catalogs (Iceberg, Hive) using the INSERT INTO command.
* You can schedule a job (via StarRocks' internal task manager or an external orchestrator like Airflow) to run:
sql
INSERT INTO iceberg_catalog.db.mirror_table
SELECT * FROM internal_catalog.db.upsert_table;
* This is effective for batch-style mirroring but is not "streaming" or "automatic."
3. Native Upserts on Iceberg Tables (StarRocks 4.1 Feature)
StarRocks 4.1 has significantly improved its ability to perform DML on external Iceberg tables.
* Position Deletes: StarRocks supports writing position delete files for Iceberg v2 tables.
* Capability: You can perform INSERT, UPDATE, and DELETE directly on an Iceberg table managed by Glue.
* Caveat: While functional, performing high-frequency upserts directly on Iceberg is generally slower than using a StarRocks native Primary Key table due to the overhead of generating Iceberg snapshots and manifest files.
Summary of Support in 4.1
Feature | Supported in 4.1
Direct DML on Glue/Iceberg | Yes (Insert, Update, Delete)
Sinking to Iceberg via INSERT INTO | Yes
Materialized Views on External Catalogs | Yes
Real-time "Mirror" Property | No (Requires AMV or scheduled task)
Recommendation: For a fast-upsert use case, keep your ingestion target as a StarRocks native Primary Key table. Then, use an Asynchronous Materialized View targeting your Glue-backed Iceberg catalog to periodically "export" or "mirror" the data to the lakehouse for external consumption.
References
• data_source/catalog/hive_catalog.md
• data_source/catalog/unified_catalog.mdKenneth Oh
07/28/2026, 1:23 AMRocky
07/28/2026, 1:24 AMdefault_catalog that receives fast upserts. You want to mirror it to an external iceberg_glue catalog.
1. Define the External Catalog (if not already done)
sql
CREATE EXTERNAL CATALOG iceberg_glue
PROPERTIES (
"type" = "iceberg",
"iceberg.catalog.type" = "glue",
"aws.glue.region" = "us-east-1",
"aws.s3.endpoint" = "<http://s3.us-east-1.amazonaws.com|s3.us-east-1.amazonaws.com>"
);
2. Create the Materialized View in the External Catalog
You can create the MV by using the three-part name: catalog.database.mv_name.
sql
CREATE MATERIALIZED VIEW iceberg_glue.target_db.mirror_table
PARTITION BY (dt) -- Partitioning helps with incremental mirroring
DISTRIBUTED BY HASH(id)
REFRESH ASYNC EVERY (INTERVAL 10 MINUTE) -- Set your sync frequency
PROPERTIES (
"storage_format" = "parquet"
)
AS
SELECT
id,
user_name,
event_time,
date_trunc('day', event_time) as dt
FROM default_catalog.native_db.fast_upsert_table;
Key Considerations for Your Use Case
* Performance: You perform your high-frequency upserts on the Native Primary Key table. This avoids the latency and metadata overhead of writing directly to S3/Glue for every small change.
* Asynchronous Sync: The Glue/Iceberg table is updated asynchronously based on the REFRESH schedule you define (e.g., every 5 minutes, 1 hour, etc.).
* External Access: Once the refresh task finishes, the data is visible to any other engine (Spark, Athena, Trino) that reads from your Glue Data Catalog.
* Partitioning: It is highly recommended to partition the Materialized View if your native table is large. This allows StarRocks to refresh only the changed partitions, making the "mirroring" process much faster.
* Manual Refresh: If you need an immediate sync after a specific batch of upserts, you can trigger it manually:
sql
REFRESH MATERIALIZED VIEW iceberg_glue.target_db.mirror_table;
Why use this over INSERT INTO?
While you can manually run INSERT INTO iceberg_glue.target_db.table SELECT ..., a Materialized View is superior for mirroring because it tracks data changes. If your native table is partitioned, StarRocks can detect which partitions were modified and only sync those to Iceberg, significantly reducing S3 I/O costs.
References
• using_starrocks/async_mv/Materialized_view.md
• using_starrocks/async_mv/use_cases/data_lake_query_acceleration_with_materialized_views.md
• data_source/catalog/iceberg/iceberg_catalog.md
• using_starrocks/async_mv/feature-support-asynchronous-materialized-views.mdKenneth Oh
07/28/2026, 3:42 AMRocky
07/28/2026, 3:42 AMstarrocks/cn-ubuntu:4.1.3 (and corresponding FE/BE images) indicates that this version is now the latest recommended patch for the 4.1 series, particularly for users in containerized environments.
Known Focus of the 4.1.x Series
If you are upgrading from 4.0 or an early 4.1.x version, the 4.1 series introduces:
* Native Semi-Structured Data in Iceberg: Support for the VARIANT type when querying Iceberg tables.
* Enhanced CN Stability: Specific fixes for Compute Node (CN) crashes during physical split scans and startup initialization issues (e.g., hash_util static order).
* Security Hardening: Significant CVE patches, including upgrades to Netty (4.1.133.Final), pgjdbc, and BouncyCastle to address potential vulnerabilities.
* Primary Key Table Optimizations: Continued improvements to the persistence and performance of the Primary Key engine.
Recommendations
* Check GitHub Releases: For the full list of bug fixes included in 4.1.3, the StarRocks GitHub Releases page is the most authoritative source for the changelog.
* Upgrading: If you are currently on 4.1.0, upgrading to 4.1.3 is highly recommended due to a known "unstable load order" bug in the 4.1.0 container images that can cause BE/CN processes to fail on start.
* Downgrade Note: If you upgrade to 4.1.3, you should not downgrade to any 4.0 version earlier than 4.0.6 due to metadata compatibility changes regarding tablet splitting.
If you are looking for a specific bug fix or feature within 4.1.3, it is best to check the release tag details on GitHub or wait for the updated release notes on the official documentation site.Kenneth Oh
07/28/2026, 4:15 AMRocky
07/28/2026, 4:15 AMsql
CREATE EXTERNAL CATALOG iceberg_glue
PROPERTIES (
"type" = "iceberg",
"iceberg.catalog.type" = "glue",
"aws.glue.region" = "us-east-1"
);
2. Create the "Mirror" (Asynchronous Materialized View)
Create the AMV in your native StarRocks database. This command creates a native table on your BE local disks and initializes the data sync.
sql
CREATE MATERIALIZED VIEW native_db.app_mirror_table
-- Optimize for your query patterns
DISTRIBUTED BY HASH(user_id)
-- Partition by the same column as Iceberg for incremental refreshes
PARTITION BY (event_date)
REFRESH ASYNC EVERY (INTERVAL 5 MINUTE)
PROPERTIES (
"replication_num" = "3",
"storage_medium" = "SSD"
)
AS
SELECT
user_id,
event_time,
payload,
CAST(event_time AS DATE) as event_date
FROM iceberg_glue.source_db.raw_data;
Why this setup meets your requirements:
* High QPS & Low Latency: Because the data is stored in StarRocks' proprietary columnar format on local BE disks (Shared-Nothing), you benefit from Primary Key indexes (if applicable), Bloom filters, and Bitmap indexes. Queries will hit local memory and SSDs instead of S3.
* Automatic Incremental Mirroring: For Iceberg (v3.1.4+), StarRocks detects partition-level changes. When the Iceberg table gets new data, StarRocks only refreshes the affected partitions in the AMV, making the "mirroring" process highly efficient and cost-effective.
* Application Transparency: Your application queries native_db.app_mirror_table just like a standard SQL table. You can also enable Transparent Rewrite, so queries against the external Iceberg catalog are automatically routed to this local mirror for speed.
* Shared Nothing Performance: By setting "storage_medium" = "SSD" and a high "replication_num", you ensure the data is distributed and replicated across your BE nodes, providing the high throughput needed for application-facing workloads.
Troubleshooting & Tuning
* Manual Sync: If you need to force a mirror update after a batch job completes in Iceberg:
sql
REFRESH MATERIALIZED VIEW native_db.app_mirror_table;
* Monitoring: Check the status of your "mirror" sync tasks:
sql
SELECT * FROM information_schema.task_runs
WHERE task_name = 'mv_app_mirror_table'
ORDER BY create_time DESC;
Note on Upserts: If your Iceberg source contains frequent updates/deletes and you need the mirror to reflect these accurately, ensure you are using StarRocks 4.x, which has enhanced support for syncing Iceberg equality/position deletes into the Materialized View.
References
• using_starrocks/async_mv/use_cases/data_lake_query_acceleration_with_materialized_views.md
• using_starrocks/async_mv/use_cases/create_partitioned_materialized_view.md
• using_starrocks/async_mv/Materialized_view.md
• using_starrocks/async_mv/troubleshooting_asynchronous_materialized_views.mdKenneth Oh
07/28/2026, 4:28 AMCREATE MATERIALIZED VIEW iceberg.db.test_mirror
DISTRIBUTED BY HASH(id)
REFRESH ASYNC EVERY (INTERVAL 1 MINUTE) -- Set your sync frequency
PROPERTIES (
"storage_format" = "parquet"
)
AS
SELECT
*
FROM default_catalog.starrocks.test_mirror;
Query 1 ERROR at Line 1: : Getting analyzing error from line 1, column 25 to line 1, column 40. Detail message: Materialized view can only be created in default_catalog. You could either create it with default_catalog.<database>.<mv>, or switch to default_catalog through set catalog <default_catalog> statement.Rocky
07/28/2026, 4:28 AMdefault_catalog. You cannot create an MV object inside an external catalog like iceberg.
In StarRocks, Materialized Views are primarily used to accelerate queries by bringing external data into StarRocks' local storage. To achieve the opposite—mirroring data from a StarRocks native table to an external Iceberg table—the recommended approach is to use a scheduled Task with an INSERT INTO statement.
The Correct Way: Use a Scheduled Task
StarRocks supports sinking data to Iceberg tables via INSERT INTO (since v3.1). You can wrap this in a TASK to create an automated "mirroring" pipeline.
1. Create the target table in your Iceberg catalog
You must first define the schema of the destination table in the Iceberg catalog.
sql
-- Switch to your iceberg catalog
SET CATALOG iceberg_glue;
CREATE TABLE target_db.mirrored_table (
id BIGINT,
data STRING,
dt DATE
) PARTITION BY (dt);
2. Create a Task to mirror the data
A TASK acts like a scheduled job. It can run a SELECT from your native StarRocks table and INSERT it into the Iceberg table.
sql
-- Tasks must be created in the default_catalog
CREATE TASK task_mirror_to_iceberg
SCHEDULE EVERY 1 MINUTE -- Set your sync frequency here
AS
INSERT INTO iceberg_glue.target_db.mirrored_table
SELECT
id,
data,
dt
FROM default_catalog.native_db.native_table
-- Optional: Add logic here to only sync new data (Incremental sync)
-- WHERE update_time > (SELECT max(update_time) FROM iceberg_glue.target_db.mirrored_table)
;
3. Start the Task
Tasks are created in a DEFERRED state by default.
sql
ALTER TASK task_mirror_to_iceberg RESUME;
Why use a Task instead of an MV?
* Storage Location: Materialized Views are designed to store data in StarRocks' proprietary internal format for sub-second query performance. They do not currently support "sinking" their internal data directly into a user-managed Iceberg table in an external catalog.
* External Compatibility: By using INSERT INTO with a Task, StarRocks writes standard Parquet files and updates the Iceberg metadata in your Glue/Hive catalog, making the data immediately available to Spark, Trino, or Athena.
* Flexibility: Tasks allow you to write custom incremental logic (e.g., using a WHERE clause with a timestamp) which is more efficient for large datasets than a full table rewrite.
Monitoring your Mirroring
You can check the progress of your mirroring task using:
sql
SELECT * FROM information_schema.task_runs
WHERE task_name = 'task_mirror_to_iceberg'
ORDER BY create_time DESC;
References
• data_source/catalog/iceberg/iceberg_catalog.md
• sql-reference/sql-statements/task/CREATE_TASK.md
• using_starrocks/async_mv/Materialized_view.md
• sql-reference/sql-statements/loading_unloading/INSERT.md
References
• data_source/External_table.md
• data_source/catalog/iceberg/iceberg_catalog.md
• quick_start/iceberg.md
• data_source/catalog/iceberg/iceberg_rest_s3.mdKenneth Oh
07/28/2026, 4:30 AMRocky
07/28/2026, 4:31 AM1785201840.698829), I was answering your first question:
*"How could i stand up a starrocks shared nothing database that mirrors data i have in an external iceberg catalog..."*The recommendation for Asynchronous Materialized Views (AMVs) was for mirroring data from Iceberg into StarRocks. This "Data Lake Acceleration" use case is where StarRocks shines for high QPS/low latency by physicalizing the data locally on BE nodes. In your second question, you reversed the direction:
*"i want to have a table in my iceberg catalog be mirrored from a starrocks native table..."*This is "Sinking to the Lakehouse" (StarRocks -> Iceberg). The "Materialized View" object in StarRocks is currently designed strictly as an internal object. Why you see that error: 1. Storage Engine: StarRocks Materialized Views use a proprietary internal storage format on the BE nodes to achieve sub-millisecond performance. They cannot (yet) store their data in an external Iceberg format/catalog directly. 2. Catalog Restriction: Because MVs are managed by the StarRocks FE (metadata) and BE (data storage), they must reside in the
default_catalog. An external catalog like iceberg is a "read-only" or "metadata-mount" catalog from StarRocks' perspective for everything except INSERT INTO operations.
The solution for your current requirement (SR -> Iceberg):
To "mirror" or sync data from a native StarRocks table to an external Iceberg table, you use a Task with an INSERT INTO statement. This is the equivalent of a "scheduled sink":
sql
-- This creates the automation you are looking for
CREATE TASK mirror_to_iceberg
SCHEDULE EVERY 5 MINUTE -- Your desired sync interval
AS
INSERT INTO iceberg.db.test_mirror
SELECT * FROM default_catalog.starrocks.test_mirror;
-- Start the background process
ALTER TASK mirror_to_iceberg RESUME;
Summary of Mirroring Mechanisms
Direction | Mechanism | Purpose
Iceberg $\rightarrow$ StarRocks | Asynchronous Materialized View | Query Acceleration: High QPS, sub-second latency for apps.
StarRocks $\rightarrow$ Iceberg | Task + INSERT INTO | Data Export/Archival: Mirroring data back to the lakehouse.
Regarding StarRocks 4.1.3: While 4.1 enhances the ability to query Iceberg and refresh MVs faster, it does not change the fundamental architecture where an MV is an internal StarRocks object. The "Incremental Materialized Views for Iceberg" feature mentioned in recent 4.1 blogs refers specifically to the ability of StarRocks to detect changes in Iceberg partitions and refresh a local StarRocks MV incrementally.
References
• using_starrocks/async_mv/use_cases/query_rewrite_with_materialized_views.md
• using_starrocks/async_mv/use_cases/data_lake_query_acceleration_with_materialized_views.md
• using_starrocks/async_mv/Materialized_view.md
• using_starrocks/async_mv/feature-support-asynchronous-materialized-views.md