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¶
Read and write an Iceberg orders table with MatrixOne — a local end-to-end tutorial using Nessie, MinIO, and Spark.
CREATE ICEBERG CATALOG — register a REST catalog and configure access prerequisites.
CREATE EXTERNAL TABLE — map a catalog table to a MatrixOne external table.
Manage Catalogs and Table Mappings¶
ALTER ICEBERG CATALOG — change catalog connection options.
DROP ICEBERG CATALOG — remove a catalog after dropping its dependent mappings.
SHOW ICEBERG CATALOGS — list registered catalogs.
SHOW ICEBERG NAMESPACES — list namespaces in a catalog.
SHOW ICEBERG TABLES — list Iceberg 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_readmapping 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 CATALOGtakes the REST cataloguriand can take awarehouselocation. 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(defaultnone) 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_accessregisters a principal mapping and a residency policy. The external table’swrite_modedefaults toread_only;append_onlyandmerge_on_readare 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_readmapping. The basic orders tutorial usesappend_only, and the delete tutorial explicitly says thatDELETEis 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 itsENGINE = ICEBERGoptions. 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_accesshas 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 RESTcurlrequest andSELECT 1through 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.