IcebergRestCatalogService — Apache Iceberg REST APIs¶
IcebergRestCatalogService is a Unity Catalog API service to handle HTTP requests at /api/2.1/unity-catalog/iceberg URL.
| Method | URL | Handler | Params |
|---|---|---|---|
| GET | /v1/config | config | warehouse |
| GET | /v1/catalogs/[catalog]/namespaces | listNamespaces | catalogparentpageTokenpageSize |
| HEAD | /v1/catalogs/[catalog]/namespaces/[namespace] | namespaceExists | catalognamespace |
| GET | /v1/catalogs/[catalog]/namespaces/[namespace] | getNamespace | catalognamespace |
| POST | /v1/catalogs/[catalog]/namespaces | createNamespace | catalog |
| DELETE | /v1/catalogs/[catalog]/namespaces/[namespace] | dropNamespace | catalognamespace |
| POST | /v1/catalogs/[catalog]/namespaces/[namespace]/properties | updateNamespaceProperties | catalognamespace |
| GET | /v1/catalogs/[catalog]/namespaces/[namespace]/tables | listTables | catalognamespacepageTokenpageSize |
| POST | /v1/catalogs/[catalog]/namespaces/[namespace]/tables | createTable | catalognamespace |
| HEAD | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] | tableExists | catalognamespacetable |
| GET | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] | loadTable | catalognamespacetable |
| POST | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] | updateTable | catalognamespacetable |
| DELETE | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] | dropTable | catalognamespacetablepurgeRequested |
| GET | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table]/credentials | loadCredentials | catalognamespacetable |
| POST | /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table]/metrics | reportMetrics | catalognamespacetable |
| POST | /v1/catalogs/[catalog]/tables/rename | renameTable | catalog |
| GET | /v1/catalogs/[catalog]/namespaces/[namespace]/views/[view] | loadView | catalognamespaceview |
server.iceberg-table.enabled
createNamespace, dropNamespace, updateNamespaceProperties, createTable, updateTable, dropTable and renameTable fail with an INVALID_ARGUMENT error when server.iceberg-table.enabled is disabled.
IcebergRestCatalogService uses Hibernate.
Create Instance¶
IcebergRestCatalogService takes the following to be created:
IcebergRestCatalogService is created when:
UnityCatalogServeris requested to add the API services
MetadataService¶
IcebergRestCatalogService is given a MetadataService when created.
This MetadataService is used to load an iceberg table.
CatalogService¶
IcebergRestCatalogService is given a CatalogService when created.
This CatalogService is used for the following:
- listNamespaces with no parent
- getNamespace with the catalog only (the first layer of Unity Catalog's three-level namespace)
SessionFactory¶
IcebergRestCatalogService creates a SessionFactory when created.
This SessionFactory is used for the following:
Config¶
ConfigResponse config(
Optional<String> catalogOpt)
config expects the warehouse query parameter (the name of a catalog) and fails with a BadRequestException when it is not given.
config requests the catalog repository to look up the catalog (so a non-existent catalog is a 404).
config responds with the following:
prefixoverride set tocatalogs/[catalog]- The REST endpoints this server supports:
- Read endpoints only when server.iceberg-table.enabled is disabled
- Read and write endpoints otherwise
Load Table¶
LoadTableResponse loadTable(
String namespace,
String table)
loadTable expects the given namespace to be two-part and splits it into catalog and schema parts (using . as the separator).
loadTable requests the TableRepository to get the table metadata (by the given namespace and table separated using .).
loadTable requests the TableRepository for the uniform metadata location (by the catalog, schema and the given table).
loadTable requests the MetadataService for the TableMetadata for the uniform metadata location.
In the end, loadTable responds with the TableMetadata.