Skip to content

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 catalog
parent
pageToken
pageSize
HEAD /v1/catalogs/[catalog]/namespaces/[namespace] namespaceExists catalog
namespace
GET /v1/catalogs/[catalog]/namespaces/[namespace] getNamespace catalog
namespace
POST /v1/catalogs/[catalog]/namespaces createNamespace catalog
DELETE /v1/catalogs/[catalog]/namespaces/[namespace] dropNamespace catalog
namespace
POST /v1/catalogs/[catalog]/namespaces/[namespace]/properties updateNamespaceProperties catalog
namespace
GET /v1/catalogs/[catalog]/namespaces/[namespace]/tables listTables catalog
namespace
pageToken
pageSize
POST /v1/catalogs/[catalog]/namespaces/[namespace]/tables createTable catalog
namespace
HEAD /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] tableExists catalog
namespace
table
GET /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] loadTable catalog
namespace
table
POST /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] updateTable catalog
namespace
table
DELETE /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table] dropTable catalog
namespace
table
purgeRequested
GET /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table]/credentials loadCredentials catalog
namespace
table
POST /v1/catalogs/[catalog]/namespaces/[namespace]/tables/[table]/metrics reportMetrics catalog
namespace
table
POST /v1/catalogs/[catalog]/tables/rename renameTable catalog
GET /v1/catalogs/[catalog]/namespaces/[namespace]/views/[view] loadView catalog
namespace
view

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:

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:

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:

  • prefix override set to catalogs/[catalog]
  • The REST endpoints this server supports:

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.