Iceberg

This is the central index for MatrixOne and Iceberg documentation. Use the links below to find setup instructions, SQL references, and tutorials.

Get Started

Manage Catalogs and Table Mappings

For example, use SHOW ICEBERG TABLES FROM my_catalog.sales to list mappings under a catalog and namespace. SHOW ICEBERG NAMESPACES and SHOW ICEBERG TABLES report mappings registered in MatrixOne; they do not discover every namespace or table in a remote catalog.

Read and Write Data

  • INSERT — insert rows and use Iceberg INSERT OVERWRITE.

  • UPDATE — update rows in a writable Iceberg mapping.

  • DELETE — delete rows from a writable Iceberg mapping.

  • MERGE INTO — merge source rows into an Iceberg table mapping.

  • Delete and verify Iceberg rows — test a merge_on_read mapping and confirm deleted rows are no longer returned.

Scope, Configuration, and Schema Notes

  • The release notes introduce the native Iceberg integration in MatrixOne v4.2.0. The orders tutorial targets v4.2.0 or later and demonstrates a local, single-machine Tier A setup; it is not a production deployment recipe. See v26.4.2.0 release notes.

  • CREATE ICEBERG CATALOG takes the REST catalog uri and can take a warehouse location. The access procedure separately records a principal and residency policy, with endpoint, region, and bucket values. The docs do not provide a general recipe for deployments that use separate catalog and object-store credentials or endpoints.

  • The catalog reference documents auth_mode (default none) and a token secret reference for token-based catalog credentials. It does not enumerate every supported auth mode or explain object-store credential configuration; confirm those details for the deployed catalog and storage service.

  • Access policies and table write modes serve different purposes. iceberg_register_access registers a principal mapping and a residency policy. The external table’s write_mode defaults to read_only; append_only and merge_on_read are the documented writable modes. Read, write, DML, and delete configuration gates are separate prerequisites. The docs do not describe a catalog-level read-only policy option.

  • The documented delete verification uses a merge_on_read mapping. The basic orders tutorial uses append_only, and the delete tutorial explicitly says that DELETE is not valid through that mapping; enabling DML gates does not change the mapping’s write-mode limits.

  • The local MatrixOne database/table name is specified in CREATE EXTERNAL TABLE; the remote catalog, namespace, and table are specified in its ENGINE = ICEBERG options. They can be named independently. Declare the exposed columns explicitly: MatrixOne does not materialize the remote schema automatically. The docs do not provide a complete Iceberg-to-MatrixOne type compatibility table or an automatic remote-schema comparison command.

  • If catalog access is rejected, check that the catalog exists and that iceberg_register_access has registered both the principal mapping and residency policy with the deployment’s allowed endpoint, region, and bucket. For the local tutorial, the documented checks are the Nessie REST curl request and SELECT 1 through the MySQL client; the docs do not give a general production remote-error troubleshooting procedure.

  • Dropping the MatrixOne table mapping, database, or catalog removes the MatrixOne demo metadata; it does not delete the remote Iceberg table or its data. Check remote data separately before removing it.

Iceberg behavior and setup details can vary by version and deployment. Follow the prerequisites and scope stated on the specific tutorial and SQL reference pages.