2

Iceberg REST Catalog API

Chris Lu edited this page 2026-08-16 13:00:07 -07:00

Table of Contents

• Endpoint
• Supported APIs
• Configuration and OAuth
• Namespace
• Table
• View
• Transaction
• Notes
• See Also

SeaweedFS implements the Iceberg REST Catalog API, so any Iceberg REST client (Spark, Trino, PyIceberg, iceberg-go, DuckDB, Dremio, RisingWave, Doris) can manage namespaces, tables, and views directly against SeaweedFS while data and metadata files live in SeaweedFS S3 buckets.

For setup, authentication, and client integrations, see SeaweedFS Iceberg Catalog.

Endpoint

The catalog listens on its own port (default 8181, set with -s3.port.iceberg). A catalog is a table bucket; address it either by URL prefix (/v1/{bucket}/...) or with ?warehouse=s3://{bucket}/. With neither, requests default to the bucket named warehouse. See SeaweedFS Iceberg Catalog for the bucket relationship.

Supported APIs

The tables below list the Iceberg REST Catalog operations and their support status, using the operation names from the REST catalog OpenAPI spec.

Configuration and OAuth

API Operation	Method & Path	Supported	Notes
GetConfig	GET /v1/config	Yes	Echoes overrides.prefix for a ?warehouse= query
GetToken	POST /v1/oauth/tokens	Yes	client_credentials grant; S3 access/secret key as client id/secret

Namespace

API Operation	Method & Path	Supported	Notes
ListNamespaces	GET /v1/{prefix}/namespaces	Yes	parent and pagination supported
CreateNamespace	POST /v1/{prefix}/namespaces	Yes
LoadNamespaceMetadata	GET /v1/{prefix}/namespaces/{ns}	Yes
NamespaceExists	HEAD /v1/{prefix}/namespaces/{ns}	Yes
DropNamespace	DELETE /v1/{prefix}/namespaces/{ns}	Yes	Rejects a non-empty namespace
UpdateNamespaceProperties	POST /v1/{prefix}/namespaces/{ns}/properties	Yes	Returns the removed/updated/missing summary

Table

API Operation	Method & Path	Supported	Notes
ListTables	GET /v1/{prefix}/namespaces/{ns}/tables	Yes
CreateTable	POST /v1/{prefix}/namespaces/{ns}/tables	Yes	Includes stage-create
LoadTable	GET /v1/{prefix}/namespaces/{ns}/tables/{table}	Yes	Vends S3 FileIO config so clients read data files directly; ?snapshots=refs returns only the snapshots refs point at
TableExists	HEAD /v1/{prefix}/namespaces/{ns}/tables/{table}	Yes
UpdateTable	POST /v1/{prefix}/namespaces/{ns}/tables/{table}	Yes	Commit with assert-* requirements
DropTable	DELETE /v1/{prefix}/namespaces/{ns}/tables/{table}	Yes
RegisterTable	POST /v1/{prefix}/namespaces/{ns}/register	Yes	Registers an existing metadata.json location
RenameTable	POST /v1/{prefix}/tables/rename	Yes	Catalog-only; data and metadata files do not move
ReportMetrics	POST /v1/{prefix}/namespaces/{ns}/tables/{table}/metrics	Yes	Accepted and discarded; the catalog keeps no metrics store
LoadCredentials	GET /v1/{prefix}/namespaces/{ns}/tables/{table}/credentials	No	Credentials come back on LoadTable instead, see S3 Tables Security
PlanTableScan / FetchScanTasks	.../tables/{table}/plan	No	Server-side scan planning

View

API Operation	Method & Path	Supported	Notes
ListViews	GET /v1/{prefix}/namespaces/{ns}/views	Yes
CreateView	POST /v1/{prefix}/namespaces/{ns}/views	Yes
LoadView	GET /v1/{prefix}/namespaces/{ns}/views/{view}	Yes
ViewExists	HEAD /v1/{prefix}/namespaces/{ns}/views/{view}	Yes
ReplaceView	POST /v1/{prefix}/namespaces/{ns}/views/{view}	Yes	Commit with assert-view-uuid requirements
DropView	DELETE /v1/{prefix}/namespaces/{ns}/views/{view}	Yes
RenameView	POST /v1/{prefix}/views/rename	Yes	Catalog-only, like RenameTable

Transaction

API Operation	Method & Path	Supported	Notes
CommitTransaction	POST /v1/{prefix}/transactions/commit	Yes	Multi-table commit; requirements validated together, applied best-effort (not crash-atomic)

Notes

• Naming: namespace and table/view names use the S3 Tables charset — lowercase a-z, 0-9, _ and -, starting and ending alphanumeric. Names with other characters (uppercase, dots) are rejected with 400 BadRequestException.
• Table and view names share a namespace: a name is unique across both within a namespace.
• Metadata storage: the catalog entry is a pointer; the Iceberg metadata.json is an object at s3://{bucket}/{ns}/{table}/metadata/vN.metadata.json. A commit writes a new metadata file and flips the pointer.
• Concurrent commits: the metadata file is written exclusively and the pointer is flipped conditionally, so two engines committing from the same base cannot lose each other's snapshot. The loser retries against the winner's metadata and, out of attempts, gets 409 CommitFailedException — which Iceberg clients handle by re-reading and retrying. A commit that finds its vN.metadata.json name taken stages under vN-{uuid}.metadata.json.

See Also

• SeaweedFS Iceberg Catalog
• Iceberg Table Maintenance

Introduction

• Quick Start with weed mini
• Simplest S3 Bucket and User Setup
• Components
• Blob Store Architecture
• Getting Started
• Production Setup
• A typical step‐by‐step example
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• EC Bitrot Detection
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Admin UI OIDC
• Worker
• Plugin Worker Scheduling

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture
• Filer Operation Serialization

FUSE Mount

• Mount on Windows
• FIO benchmark
• fstab and systemd mount
• POSIX Compliance
• Distributed POSIX Locks
• P2P reading in weed mount
• Mount over the Internet

WebDAV

SFTP Server

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Azure Blob Storage Authentication
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• Supported APIs vs Minio
• S3 Lifecycle
  • S3 Lifecycle Recipes
  • S3 Lifecycle Operator Guide
  • S3 Lifecycle Monitoring
  • S3 Lifecycle Troubleshooting
  • S3 Lifecycle Architecture
• S3 Lifecycle vs Volume TTL
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 RenameObject
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket
• S3 Table Bucket Commands
• S3 Tables Security
• SeaweedFS Iceberg Catalog
• Iceberg REST Catalog API
• Iceberg Table Maintenance
• SeaweedFS Lance Catalog
• Lance Maintenance Worker

Iceberg Integrations

• Spark Iceberg Integration
• Trino Iceberg Integration
• Dremio Iceberg Integration
• DuckDB Iceberg Integration
• Doris Iceberg Integration
• RisingWave Iceberg Integration
• Lakekeeper Iceberg Integration

Lance Integrations

• LanceDB Integration
• Spark Lance Integration
• DuckDB Lance Integration

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• Kubernetes ServiceAccount Authentication (IRSA-style)
• S3 Policy Variables
• S3 Policy Conditions
• S3 Bucket Policies
• Amazon IAM API
• AWS IAM CLI
• weed shell - Shell IAM Commands

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS
• Distributing AI Model Files for Multi-GPU Loading

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• Run Trino on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube
• Helm Chart Recipes
• Deployment with seaweed-up
  • seaweed-up Command Reference
  • Cluster Plan Workflow
  • Cluster Plan Inventory Reference
  • Cluster Plan Day 2 Operations

Rust Volume Server

• Rust Volume Server

Advanced

• Large File Handling
• Optimization
• Optimization for Many Small Buckets
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware