# Using lakeFS with Apache Iceberg

> [!NOTE]
>
> **Available in lakeFS Enterprise, in private preview. [Start a free trial](<https://lakefs.io/try/>) or [contact us](<https://lakefs.io/book-a-demo/>).**

Apache Iceberg tables have no built-in way to branch, review, or roll back changes, so teams end up copying tables to test a migration or promote data between environments. lakeFS solves this by exposing a [spec-compliant](<https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml>) Apache [Iceberg REST Catalog](<https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/iceberg/main/open-api/rest-catalog-open-api.yaml>), so any standard Iceberg client can create, manage, and query tables through it while every table gains Git-like version control, letting you branch, commit, merge, and roll back your data.

![Architecture diagram showing Iceberg clients connecting to lakeFS as a REST catalog while reading and writing data directly to object storage](<https://docs.lakefs.io/assets/img/lakefs_iceberg_rest_catalog.png>)

lakeFS serves a standard Iceberg REST Catalog: clients read and write data files directly to object storage, while lakeFS versions the table metadata and provides branching, commits, and merges.

Because it follows the Iceberg REST specification, lakeFS is a drop-in replacement for other Iceberg catalogs such as AWS Glue, Nessie, or Hive Metastore, as well as the deprecated lakeFS [HadoopCatalog](<#deprecated-iceberg-hadoopcatalog>). It also stays completely outside the data path, so clients read and write data files directly to the underlying object store while lakeFS versions only the table metadata.

## Quick Start

The catalog is served at `/iceberg/api` on your lakeFS server, with an OAuth2 token endpoint at `/iceberg/api/v1/oauth/tokens`. Authenticate with your lakeFS access key and secret, in the form `<access_key_id>:<secret_access_key>`.

Tables are addressed as `<repository>.<branch>.<namespace>.<table>`, so switching branches is as simple as changing the namespace:

```python
from pyiceberg.catalog.rest import RestCatalog

catalog = RestCatalog(name="my_catalog", **{
    "prefix": "lakefs",
    "uri": "https://lakefs.example.com/iceberg/api",
    "oauth2-server-uri": "https://lakefs.example.com/iceberg/api/v1/oauth/tokens",
    "credential": "AKIAlakefs12345EXAMPLE:abc/lakefs/1234567bPxRfiCYEXAMPLEKEY",
})

# List namespaces in a branch
catalog.list_namespaces(("repo", "main"))

# Query a table
catalog.list_tables("repo.main.inventory")
table = catalog.load_table("repo.main.inventory.books")
arrow_df = table.scan().to_arrow()
```

Configure a catalog pointing at your lakeFS server:

```properties
spark.sql.catalog.lakefs=org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.lakefs.type=rest
spark.sql.catalog.lakefs.prefix=lakefs
spark.sql.catalog.lakefs.uri=https://lakefs.example.com/iceberg/api
spark.sql.catalog.lakefs.oauth2-server-uri=https://lakefs.example.com/iceberg/api/v1/oauth/tokens
spark.sql.catalog.lakefs.credential=AKIAlakefs12345EXAMPLE:abc/lakefs/1234567bPxRfiCYEXAMPLEKEY
```

```scala
spark.sql("USE lakefs.my_repo.main.inventory")

// List available tables
spark.sql("SHOW TABLES").show()

// Query data with branch isolation
spark.sql("SELECT * FROM books").show()

// Switch to a feature branch
spark.sql("USE lakefs.my_repo.new_branch.inventory")
spark.sql("SELECT * FROM books").show()
```

See the [Spark integration guide](<https://docs.lakefs.io/integrations/spark/index.md>) for other ways to use lakeFS from Spark.

```properties
# example: /etc/trino/catalog/lakefs.properties
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://lakefs.example.com/iceberg/api
iceberg.rest-catalog.nested-namespace-enabled=true
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.oauth2.credential=${ENV:LAKEFS_CREDENTIALS}
iceberg.rest-catalog.oauth2.server-uri=https://lakefs.example.com/iceberg/api/v1/oauth/tokens
```

```sql
-- List tables in the iceberg catalog
USE "repo.main.inventory"; -- <repository>.<branch or reference>.<namespace>
SHOW TABLES;

-- Query a table
SELECT * FROM books LIMIT 100;

-- Switch to a different branch
USE "repo.new_branch.inventory";
SELECT * FROM books;
```

See the [Trino / Presto integration guide](<https://docs.lakefs.io/integrations/presto_trino/index.md>) for full setup, including storage access configuration.

```sql
LOAD iceberg;
LOAD httpfs;

CREATE SECRET lakefs_credentials (
    TYPE ICEBERG,
    CLIENT_ID 'AKIAlakefs12345EXAMPLE',
    CLIENT_SECRET 'abc/lakefs/1234567bPxRfiCYEXAMPLEKEY',
    OAUTH2_SERVER_URI 'https://lakefs.example.com/iceberg/api/v1/oauth/tokens'
);

ATTACH 'lakefs' AS main_branch (
    TYPE iceberg,
    SECRET lakefs_credentials,
    -- scope the catalog to a repository and branch (see "Relative Namespace Support" below)
    ENDPOINT 'https://lakefs.example.com/iceberg/relative_to/my-repo.main/api'
);

USE main_branch.inventory;
SELECT * FROM books;
```

See the [DuckDB integration guide](<https://docs.lakefs.io/integrations/duckdb/index.md>) for details.

Looking for a different engine? See the dedicated guides for [Dremio](<https://docs.lakefs.io/integrations/dremio/index.md>), [Starburst Galaxy](<https://docs.lakefs.io/integrations/starburst_galaxy/index.md>), [Amazon Athena](<https://docs.lakefs.io/integrations/athena/index.md>) and [AWS Glue Data Catalog](<https://docs.lakefs.io/integrations/glue_metastore/index.md>).

## Version Control for Iceberg Tables

Table and namespace changes made through the catalog (creating or dropping a table, committing new snapshots) are staged on the target branch, just like any other change in lakeFS. Commit them explicitly using lakeFS tools to record them in the branch history, and note that several Iceberg operations, potentially across multiple tables, can be grouped into a single lakeFS commit:

```python
import lakefs

repo = lakefs.repository("repo")

# Create a branch to work in isolation
branch = repo.branch("new_branch").create(source_reference="main")

# The table is immediately accessible on the new branch
table = catalog.load_table(f"repo.{branch.id}.inventory.books")

# ... modify the table using any Iceberg client ...

# Commit the staged catalog changes to lakeFS
branch.commit(message="Update inventory.books")

# Merge the changes back into main
branch.merge_into("main")

# Changes are now visible in main
main_table = catalog.load_table("repo.main.inventory.books")
```

> [!NOTE]
>
> **Merging conflicting table changes**
>
> lakeFS handles table changes as file operations during merges: table metadata files are treated as regular files, and no special merge logic is applied to conflicting table changes. If the same table was changed on both branches, the merge fails with a conflict that needs to be resolved manually. The exception is data compaction, which lakeFS can resolve automatically, as described in [Table Maintenance](<#table-maintenance>).

## Use Cases

- **Isolated data development**: Create a branch to test schema changes, migrations or backfills across multiple tables, then merge safely with conflict detection.
- **Multi-environment management**: Represent environments (dev, staging, prod) as branches and promote table changes between them through merges, gated by automated testing.
- **Collaboration**: Multiple teams work on different table features simultaneously, and review changes to data and schema using [pull requests](<https://docs.lakefs.io/guides/pull-requests/index.md>).
- **Governance and recovery**: A built-in commit log captures who changed what and how; fine-grained [RBAC policies](<#authorization>) control access; atomic rollback reduces time-to-recover.

## Namespaces and Tables

Namespaces in the Iceberg Catalog follow the pattern `"<repository>.<branch>.<namespace>(.<namespace>...)"` where:

- `<repository>` must be a valid lakeFS repository name.
- `<branch>` must be a valid lakeFS branch name.
- `<namespace>` components can be nested using unit separator (e.g., `inventory.books`).

Examples:

- `my-repo.main.inventory`
- `my-repo.feature-branch.inventory.books`

The repository and branch components must already exist in lakeFS before using them in the Iceberg catalog.

The catalog supports the standard Iceberg namespace operations: create, list and drop namespaces, and list tables within namespaces.

### Relative Namespace Support

Some Apache Iceberg clients do not support nested namespaces.

To support those, the lakeFS REST Catalog allows specifying relative namespaces: passing a partial namespace as part of the catalog URL endpoint (commonly, `<repository>.<branch>`):

```text
https://lakefs.example.com/iceberg/relative_to/<repository>.<branch>/api
```

All namespaces passed by the client are then resolved relative to the namespace in the URL. For example, DuckDB allows limited nesting in the form of `<database>.<schema>`, so a repository-and-branch-scoped endpoint lets it address tables with just `<namespace>.<table>`, as shown in the [DuckDB example](<#quick-start>) above and the [DuckDB integration guide](<https://docs.lakefs.io/integrations/duckdb/index.md>).

### Namespace Restrictions

- Repository and branch names must follow lakeFS naming conventions.
- Namespace components cannot contain special characters except dots (.) for nesting.
- The total namespace path length must be less than 255 characters.
- Namespaces are case-sensitive.
- Empty namespace components are not allowed.

### Table Operations

The Iceberg Catalog supports all standard Iceberg table operations:

- Create tables with schemas and partitioning.
- Update table schemas and partitioning.
- Commit changes to tables.
- Delete tables.
- List tables in namespaces.

## Authentication and Authorization

### Authentication

Clients authenticate using the OAuth2 token endpoint at `<lakefs-endpoint>/iceberg/api/v1/oauth/tokens`. To authenticate, clients must provide their lakeFS access key and secret in the format `access_key:secret` as the credential.

### Authorization

The Iceberg REST Catalog defines its own set of RBAC actions and resources, described below. When using lakeFS with Iceberg, permissions must be managed through Iceberg RBAC - repository or object-level permissions alone are not sufficient. Iceberg catalog permissions supersede any related object permissions. For example, having `fs:ReadObject` on a repository does not grant `catalog:ReadTable` on tables in that repository.

For general information about lakeFS RBAC, see the [RBAC documentation](<https://docs.lakefs.io/security/rbac/index.md>).

#### Resources

| Resource | ARN Structure |
| --- | --- |
| Iceberg Namespace | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` |
| Iceberg Table | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` |
| Iceberg View | `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` |

Namespaces in the ARN use dot-separated notation (e.g., `my.namespace`). Wildcards (`*`) are supported for any path component.

> [!NOTE]
>
> **Permissions are branch-agnostic**
>
> The ARN structure does not include a branch component, so only the repository and namespace are used for authorization. This means that a policy granting access to a namespace in a given repository applies to that namespace on **every branch**. For example, a policy allowing `catalog:ReadTable` on `arn:lakefs:catalog:::table/my-repo/my.namespace/*` grants read access to tables in `my.namespace` regardless of whether the client accesses branch `main`, `dev`, or any other branch.

#### Actions

| Action | Resource | Description |
| --- | --- | --- |
| `catalog:CreateNamespace` | Namespace | Create a namespace |
| `catalog:GetNamespace` | Namespace | Get namespace metadata |
| `catalog:ListNamespaces` | Namespace | List child namespaces |
| `catalog:UpdateNamespace` | Namespace | Update namespace properties |
| `catalog:DeleteNamespace` | Namespace | Delete a namespace |
| `catalog:ListTables` | Namespace | List tables within a namespace |
| `catalog:CreateTable` | Table | Create a table |
| `catalog:ReadTable` | Table | Read table metadata |
| `catalog:UpdateTable` | Table | Update or rename a table (commit, schema, etc) |
| `catalog:DeleteTable` | Table | Delete a table |
| `catalog:ReadTableData` | Table | Vend read-only credentials for the table's data (see [Credentials Vending](<#credentials-vending>)) |
| `catalog:WriteTableData` | Table | Vend read-write credentials for the table's data (see [Credentials Vending](<#credentials-vending>)) |
| `catalog:ListViews` | Namespace | List views within a namespace |
| `catalog:CreateView` | View | Create a view |
| `catalog:ReadView` | View | Read view metadata |
| `catalog:UpdateView` | View | Update, replace or rename a view |
| `catalog:DeleteView` | View | Delete a view |

#### List Operations Filtering

**Namespace filtering:**

For `ListNamespaces`, use wildcards in the resource ARN to control which namespaces are visible to the user.

**Example - Allow listing only namespaces starting with `analytics`:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": ["catalog:ListNamespaces"],
      "resource": "arn:lakefs:catalog:::namespace/my-repo/analytics*"
    }
  ]
}
```

This policy allows the user to see only namespaces starting with `analytics` in `my-repo`. Other namespaces in the same repository are filtered out of the response.

**Table and view filtering (using conditions):**

For `ListTables` and `ListViews`, the namespace ARN alone is not enough to filter individual tables or views within that namespace. Policies can use the `StringLike` condition operator with the `catalog:TableName` or `catalog:ViewName` fields to control which entities are visible.

| Condition Field | Supported Action | Description |
| --- | --- | --- |
| `catalog:TableName` | `catalog:ListTables` | The name of the table being listed |
| `catalog:ViewName` | `catalog:ListViews` | The name of the view being listed |

**Example - Allow listing only tables matching a pattern:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": ["catalog:ListTables"],
      "resource": "arn:lakefs:catalog:::namespace/my-repo/analytics",
      "condition": {
        "StringLike": {
          "catalog:TableName": ["prod-*", "staging-*"]
        }
      }
    }
  ]
}
```

This policy allows the user to see only tables starting with `prod-` or `staging-` when listing tables in the `analytics` namespace of `my-repo`. Tables that do not match the pattern are filtered out of the response.

**Example - Deny listing a specific view:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": ["catalog:ListViews"],
      "resource": "arn:lakefs:catalog:::namespace/my-repo/my.namespace"
    },
    {
      "effect": "deny",
      "action": ["catalog:ListViews"],
      "resource": "arn:lakefs:catalog:::namespace/my-repo/my.namespace",
      "condition": {
        "StringLike": {
          "catalog:ViewName": ["secret_view"]
        }
      }
    }
  ]
}
```

This policy allows the user to list all views in the `my.namespace` namespace, except for `secret_view` which is explicitly denied.

#### Example Policies

**Read-only access to all tables and namespaces:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": [
        "catalog:ReadTable",
        "catalog:ReadTableData"
      ],
      "resource": "arn:lakefs:catalog:::table/*/*/*"
    },
    {
      "effect": "allow",
      "action": ["catalog:ListNamespaces", "catalog:GetNamespace"],
      "resource": "arn:lakefs:catalog:::namespace/*/*"
    }
  ]
}
```

`catalog:ReadTableData` is required to vend read-only credentials for a table's data. `catalog:ReadTable` alone grants access to table metadata but not to the vended data credentials. See [Credentials Vending](<#credentials-vending>) for details.

**Read-write access to all tables in a repository (including data credentials):**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": [
        "catalog:ReadTable",
        "catalog:CreateTable",
        "catalog:UpdateTable",
        "catalog:ReadTableData",
        "catalog:WriteTableData"
      ],
      "resource": "arn:lakefs:catalog:::table/my-repo/*/*"
    }
  ]
}
```

> [!WARNING]
>
> **Upgrading from lakeFS Enterprise v1.91.0 or earlier**
>
> `catalog:ReadTableData` and `catalog:WriteTableData` are new actions introduced together with credential vending in lakeFS Enterprise v1.92.0. Any policy created before the upgrade — including custom or persisted catalog policies — does not grant them.
>
> - The built-in `CatalogRead` policy already includes `catalog:ReadTableData`, and `CatalogReadWrite` uses `catalog:*`, so principals attached to these managed policies get vending automatically after the upgrade.
> - **Custom / persisted policies are not updated for you.** Review them and add `catalog:ReadTableData` (read-only) and `catalog:WriteTableData` (read-write) to the relevant statements. `catalog:ReadTable` alone grants metadata access but not vended credentials.
>
> Because inline vending is best-effort, a missing data action does not fail the catalog operation — the client still loads table metadata but silently receives no credentials, which can look like a connectivity problem. Grant the data actions to restore vending (a direct credentials request returns status code `401` until then).

**Full access to tables in a specific repository:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": ["catalog:*"],
      "resource": "arn:lakefs:catalog:::table/my-repo/*/*"
    },
    {
      "effect": "allow",
      "action": ["catalog:*"],
      "resource": "arn:lakefs:catalog:::namespace/my-repo/*"
    }
  ]
}
```

**Allow reading all tables except a specific one:**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": ["catalog:ReadTable"],
      "resource": "arn:lakefs:catalog:::table/my-repo/*/*"
    },
    {
      "effect": "deny",
      "action": ["catalog:ReadTable"],
      "resource": "arn:lakefs:catalog:::table/my-repo/my.namespace/secret_table"
    }
  ]
}
```

### Multi-tenancy

> [!NOTE]
>
> **Requires the Tenants capability in the lakeFS Enterprise license**

The Iceberg REST Catalog honors the active [tenant](<https://docs.lakefs.io/security/tenants/index.md>) through the `X-LakeFS-Tenant` request header, the same header the lakeFS API, lakectl and the SDKs use. With the header set, namespaces such as `my-repo.main.analytics` resolve `my-repo` inside that tenant, and everything the catalog writes lands in the tenant's repository. Every response echoes the resolved tenant in the same header.

Without the header, the catalog operates in the root tenant, so existing configurations are unchanged.

Set the header through a catalog property, the same mechanism used for `X-Iceberg-Access-Delegation`:

```properties
spark.sql.catalog.lakefs.header.X-LakeFS-Tenant=<tenant>
```

```python
catalog = RestCatalog(name="lakefs", **{
    "uri": "https://lakefs.example.com/iceberg/api",
    "prefix": "lakefs",
    "oauth2-server-uri":
        "https://lakefs.example.com/iceberg/api/v1/oauth/tokens",
    "credential": "<lakefs-access-key>:<lakefs-secret-key>",
    "header.X-LakeFS-Tenant": "<tenant>",
})
```

```go
cat, err := rest.NewCatalog(ctx, "lakefs", "https://lakefs.example.com/iceberg/api",
    rest.WithCredential("<lakefs-access-key>:<lakefs-secret-key>"),
    rest.WithAdditionalProps(iceberg.Properties{"header.X-LakeFS-Tenant": "<tenant>"}),
)
```

The caller must be a member of the tenant. A request that fails the tenant checks responds with:

| Status | Error type | When |
| --- | --- | --- |
| `400` | `InvalidTenant` | The header value is not a well-formed tenant name. |
| `404` | `NotFound` | The tenant does not exist, or the caller is not a member of it. The two cases are indistinguishable. |
| `401` | `Unauthorized` | The license does not include the Tenants capability. |
| `501` | `NotImplemented` | The authentication backend does not support tenants. |

Clients surface these through their own error types; PyIceberg raises the `404` when the catalog loads its configuration, before any table operation.

## Credentials Vending

lakeFS can vend short-lived, table-scoped object-store credentials to Iceberg REST Catalog clients. This removes the need to configure Spark, Trino, PyIceberg, or any other compatible client with permanent credentials for the repository's physical storage.

This solves the case where an Iceberg client knows only its lakeFS credentials, while the REST Catalog returns physical object-store locations that the client must read from and write to.

Credential vending is **currently supported for S3**, and support for additional storage backends is planned.

> [!NOTE]
>
> **Info**
>
> Credential vending removes the need for permanent client-side object-store credentials; it does **not** proxy data through the lakeFS S3 Gateway. Clients still need network access to the advertised physical storage endpoint.

### How it works

The client authenticates to the catalog with its lakeFS credentials. On S3, lakeFS then:

1. Authorizes access to the table's data.
2. Calls AWS STS `AssumeRole`.
3. Restricts the STS session to that table's data and lakeFS-managed metadata prefixes.
4. Returns the temporary S3 credentials and their expiration to the Iceberg client.
5. The client accesses the physical S3 endpoint directly.

The permissions carried by the vended credentials depend on the caller's access. Read-only sessions allow:

```text
s3:GetObject
s3:ListBucket
```

Read-write sessions additionally allow:

```text
s3:PutObject
s3:DeleteObject
s3:AbortMultipartUpload
s3:ListMultipartUploadParts
```

The generated session policy restricts these actions to the table's data and metadata prefixes.

Credential vending is best-effort. When credentials cannot be vended, for example because the caller lacks the relevant table-data permission, the location is outside the repository's storage namespace, or the backend does not support vending, the catalog operation still succeeds and returns the table metadata, only without credentials. The Iceberg client handles requesting and refreshing vended credentials on its own.

### Limitations

- Vending is currently supported only for S3, with plans to support additional backends like Azure and GCS.
- Credentials are vended for locations within the repository's storage namespace. A table registered with a foreign or external location will not receive credentials for that location.

### Configuration

Credential vending is a server configuration, defined per storage backend. To enable it for an S3 backend, set a dedicated `role_arn` in the following blockstore configuration:

```yaml
blockstore:
  type: s3
  s3:
    credentials_vending:
      role_arn: arn:aws:iam::123456789012:role/lakefs-iceberg-vending
      session_duration: 1h
      external_id: optional-external-id
      endpoint: https://s3.customer-facing.example.com
```

| Field | Required | Behavior |
| --- | :---: | --- |
| `role_arn` | Yes | Enables vending and identifies the role assumed for each session. Default: empty, which disables vending. |
| `session_duration` | No | STS session lifetime. Default: `1h`. Minimum: `15m`; a shorter configured value prevents lakeFS from starting. |
| `external_id` | No | Passed to STS `AssumeRole`, normally when required by the role's trust policy. |
| `endpoint` | No | Overrides the S3 endpoint returned to clients. Useful when lakeFS and clients use different internal/external addresses. |

For [multi-storage backend](<https://docs.lakefs.io/admin/multiple-storage-backends/index.md>) installations, configure `credentials_vending` inside each relevant S3 entry under `blockstores.stores[].s3`. See the [lakeFS Enterprise configuration reference](<https://docs.lakefs.io/reference/enterprise-configuration/index.md>) for all `credentials_vending` fields and their equivalent `LAKEFS_`-prefixed environment variables.

### AWS prerequisites (S3)

Setting `role_arn` enables vending, but the AWS side must also be set up. Complete the following steps:

1. **Create or identify the IAM role** referenced by `role_arn`, and grant its identity policy the S3 operations that vending needs: `s3:GetObject` and `s3:ListBucket` for reads, plus `s3:PutObject`, `s3:DeleteObject`, `s3:AbortMultipartUpload`, and `s3:ListMultipartUploadParts` for writes. The inline session policy that lakeFS generates only **narrows** these permissions; it cannot add permissions the role does not already have.
2. **Allow the lakeFS server's AWS identity to assume the role** by granting it `sts:AssumeRole` on `role_arn`.
3. **Configure the role's trust policy** to trust the lakeFS runtime identity. If `external_id` is configured, the trust-policy condition must match it.
4. **Keep `session_duration` within limits** so it does not exceed the role's `MaxSessionDuration` or any applicable STS role-chaining limits.

Also ensure network reachability: the lakeFS server can reach STS, and Iceberg clients can reach the physical/customer-facing S3 endpoint.

### lakeFS authorization

Credential vending relies on table-data actions that are separate from the metadata actions used for normal catalog operations. The table-data actions determine whether read-only or read-write credentials are vended, while the metadata actions govern resolving the table and its physical location:

| Action | Result |
| --- | --- |
| `catalog:ReadTableData` | Vends read-only credentials for the table's data. |
| `catalog:WriteTableData` | Vends read-write credentials for the table's data. Write is checked first, so a separate read-data grant is not required. |

The user still needs the normal metadata actions for the requested catalog operation, such as `catalog:ReadTable`, `catalog:CreateTable`, or `catalog:UpdateTable`. See [Authorization](<#authorization>) for example policies that include these data actions and for upgrade guidance on existing installations.

As with other catalog permissions, table resource ARNs are branch-agnostic.

### Client configuration

Configure your Iceberg client to request vended credentials:

Spark must use the Iceberg `S3FileIO`, not Hadoop S3A with static object-store credentials.

```properties
spark.sql.catalog.lakefs=org.apache.iceberg.spark.SparkCatalog
spark.sql.catalog.lakefs.type=rest
spark.sql.catalog.lakefs.uri=https://lakefs.example.com/iceberg/api
spark.sql.catalog.lakefs.oauth2-server-uri=https://lakefs.example.com/iceberg/api/v1/oauth/tokens
spark.sql.catalog.lakefs.credential=<lakefs-access-key>:<lakefs-secret-key>
spark.sql.catalog.lakefs.prefix=lakefs
spark.sql.catalog.lakefs.header.X-Iceberg-Access-Delegation=vended-credentials
spark.sql.catalog.lakefs.io-impl=org.apache.iceberg.aws.s3.S3FileIO
```

```python
catalog = RestCatalog(name="lakefs", **{
    "uri": "https://lakefs.example.com/iceberg/api",
    "prefix": "lakefs",
    "oauth2-server-uri":
        "https://lakefs.example.com/iceberg/api/v1/oauth/tokens",
    "credential": "<lakefs-access-key>:<lakefs-secret-key>",
    "header.X-Iceberg-Access-Delegation": "vended-credentials",
})
```

```properties
connector.name=iceberg
iceberg.catalog.type=rest
iceberg.rest-catalog.uri=https://lakefs.example.com/iceberg/api
iceberg.rest-catalog.prefix=lakefs
iceberg.rest-catalog.security=OAUTH2
iceberg.rest-catalog.oauth2.server-uri=https://lakefs.example.com/iceberg/api/v1/oauth/tokens
iceberg.rest-catalog.oauth2.credential=<lakefs-access-key>:<lakefs-secret-key>
iceberg.rest-catalog.vended-credentials-enabled=true
fs.native-s3.enabled=true
```

For S3-compatible services, keep the appropriate client S3 endpoint, region, and path-style options.

### Troubleshooting

| Symptom | Likely cause and resolution |
| --- | --- |
| The catalog operation succeeds but the client receives no credentials | The caller lacks `catalog:ReadTableData` / `catalog:WriteTableData`. Grant the appropriate data action (see [Authorization](<#authorization>)). |
| Vending fails with status code `500` | STS `AssumeRole` failed. Verify the lakeFS identity may assume `role_arn`, the role's trust policy trusts lakeFS (and matches `external_id` if set), and the role's identity policy allows the required S3 actions. |
| The client receives credentials but cannot read or write S3 | The client cannot reach the physical/customer-facing S3 endpoint. Check network connectivity and, if applicable, the configured `endpoint` override. |
| Vending fails with status code `403` | The requested table location is outside the repository's (or dataset source's) storage namespace, for example a foreign/external table location. No credentials are vended for such locations. |
| Vending fails with status code `406` | The storage backend does not support vending (only S3 is supported today), or S3 vending is disabled. Configure `credentials_vending.role_arn` on the relevant S3 blockstore. |

## Table Maintenance

### Compact Data Files

In the lakeFS catalog, data integrity is maintained after data file compaction operations (such as RewriteDataFiles), since data files are not deleted by such operations (only new snapshot and manifest files are created).

However, to avoid unnecessary merge conflicts, we recommend marking compaction operations using `snapshotProperty()`, so that lakeFS can automatically resolve conflicts when merging branches with compaction commits.

> [!NOTE]
>
> **Info**
>
> Expired or deleted snapshots will very likely lead to merge conflicts, as lakeFS cannot determine which snapshots to keep. This includes snapshots expired by [Tables Cleanup](<#tables-cleanup>) - merge compacted branches before cleanup expires the snapshots involved.

#### Requirements

- Use the Spark Java API (not SQL procedures) with Iceberg v1.5 or newer
- Mark compaction operations with the following property and value using `snapshotProperty()`:

```scala
SparkActions.get(spark)
    .rewriteDataFiles(table)
    .snapshotProperty("lakefs.compaction.operation-id", "rewrite-data-files")
    .execute();
```

#### Conflict Resolution

When merging branches, lakeFS automatically resolves conflicts if both branches have compaction commits for the same table and at most one branch has non-compaction data changes. This allows safe merging of compacted branches without losing work.

> [!NOTE]
>
> **Info**
>
> Expired or deleted snapshots will very likely lead to merge conflicts, as lakeFS cannot determine which snapshots to keep.

> [!TIP]
>
> Frequently merge compacted branches to minimize merge conflicts.

> [!TIP]
>
> Data changes are ignored in non-"main" *Iceberg* branches ("Refs"), so it's advised to avoid branching in Iceberg when branching in lakeFS.

For disabling the automatic conflict resolution, set the `iceberg.ignore_compaction_commits` configuration flag to `false` (it defaults to `true`).

### Tables Cleanup

Iceberg's built-in maintenance procedures (expire snapshots, delete orphan files) are not aware of lakeFS versioning and must remain disabled (see [Unsupported Operations](<#unsupported-operations>)). To reclaim the storage they would normally free, lakeFS provides **Iceberg Cleanup**: a Spark job, included in the lakeFS Enterprise Spark metadata client, that reduces the storage footprint of catalog-managed tables without deleting anything a lakeFS branch, tag, retained commit, or staged change still references.

A cleanup run works in two parts:

1. **Expire snapshots**: on every branch, table snapshots older than the retention policy are removed from the table metadata, and the trimmed metadata is staged on the branch (commit it like any other catalog change).
2. **Sweep storage**: files in the catalog's managed storage that are no longer referenced by any retained table or view - on any branch head, tag, commit kept by the repository's [garbage collection rules](<https://docs.lakefs.io/admin/garbage-collection/index.md>), or staged change - are marked as deletion candidates and then deleted. Files newer than the safety age are never deleted, protecting in-flight writes.

#### Requirements

- The repository must have garbage collection rules [configured](<https://docs.lakefs.io/admin/garbage-collection/index.md#how-to-configure-garbage-collection-rules>): the commits they retain define which historical table versions cleanup keeps.
- The Spark cluster needs read, write, and delete access to the repository's storage namespace (see [this](<https://docs.lakefs.io/admin/garbage-collection/index.md#how-to-run-the-garbage-collection-job>) for more details).
- The lakeFS user running the cleanup must have the permissions listed below (the standard GC set, plus relevant catalog permissions).

**Example cleanup policy**

```json
{
  "statement": [
    {
      "effect": "allow",
      "action": [
        "retention:GetGarbageCollectionRules",
        "retention:PrepareGarbageCollectionCommits",
        "retention:PrepareGarbageCollectionUncommitted",
        "fs:ReadRepository",
        "fs:ListBranches",
        "fs:ListTags",
        "fs:ListObjects"
      ],
      "resource": "arn:lakefs:fs:::repository/my-repo"
    },
    {
      "effect": "allow",
      "action": ["fs:ReadObject", "fs:WriteObject"],
      "resource": "arn:lakefs:fs:::repository/my-repo/object/*"
    },
    {
      "effect": "allow",
      "action": ["fs:ReadConfig"],
      "resource": "*"
    },
    {
      "effect": "allow",
      "action": ["catalog:ReadTable", "catalog:UpdateTable"],
      "resource": "arn:lakefs:catalog:::table/my-repo/*/*"
    }
  ]
}
```

#### Running cleanup

```bash
CLIENT_VERSION=0.26.0
SCALA_VERSION=2.12  # 2.13 for Spark 4.x
spark-submit --class io.treeverse.gc.IcebergCleanup \
  --conf spark.hadoop.lakefs.api.url=https://lakefs.example.com/api/v1 \
  --conf spark.hadoop.lakefs.api.access_key=<LAKEFS_ACCESS_KEY> \
  --conf spark.hadoop.lakefs.api.secret_key=<LAKEFS_SECRET_KEY> \
  --conf spark.hadoop.lakefs.iceberg.catalog.uri=https://lakefs.example.com/iceberg/api \
  --conf spark.hadoop.fs.s3a.access.key=<S3_ACCESS_KEY> \
  --conf spark.hadoop.fs.s3a.secret.key=<S3_SECRET_KEY> \
  https://treeverse-clients-us-east.s3.amazonaws.com/lakefs-spark-client-enterprise/${CLIENT_VERSION}/lakefs-spark-client-enterprise_${SCALA_VERSION}-assembly-${CLIENT_VERSION}.jar \
  <repository-name> [region]
```

The job arguments are the repository name and, on S3, an optional region. `spark.speculation` must remain disabled (a duplicated speculative task could double-apply metadata commits); the job refuses to run when it is enabled.

#### Configuration

Pass the following properties as Hadoop configuration, i.e. with the `spark.hadoop.` prefix:

| Property | Default | Description |
| --- | :---: | --- |
| `lakefs.iceberg.catalog.uri` | (required) | URI of the lakeFS Iceberg REST catalog, e.g. `https://lakefs.example.com/iceberg/api`. |
| `lakefs.iceberg.cleanup.max_snapshot_age_days` | `5` | Snapshots older than this are expired. `0` expires every unprotected snapshot down to the keep floor. |
| `lakefs.iceberg.cleanup.min_snapshots_to_keep` | `2` | Minimum number of snapshots kept per table metadata file. Must be greater than `1`. |
| `lakefs.iceberg.cleanup.safety_age_seconds` | `259200` (3 days) | Files younger than this are never deleted. Minimum: `43200` (12 hours). |
| `lakefs.iceberg.cleanup.dry_run` | `false` | Report what the run would expire and delete, changing nothing. |
| `lakefs.iceberg.cleanup.do_stage` | `true` | When `false`, expirations are only previewed in the report - no table metadata is trimmed or staged. |
| `lakefs.iceberg.cleanup.do_mark` | `true` | Expire snapshots and mark deletion candidates. Set to `false` for a sweep-only run. |
| `lakefs.iceberg.cleanup.do_sweep` | `true` | Delete the marked candidates. Set to `false` for a mark-only run. |
| `lakefs.iceberg.cleanup.mark_id` |  | ID of the mark to enact in a sweep-only run. Must not be set when marking. |
| `lakefs.iceberg.cleanup.sweep_parallelism` | `3` | Parallelism of the deletion phase. |

`do_stage` only applies to marking runs: a sweep-only run (`do_mark=false`) skips snapshot expiration entirely and just enacts the named mark. Setting `dry_run=true` forces both `do_stage` and `do_sweep` off, so a dry run reports deletion candidates without modifying the repository's tables or storage.

#### Run modes

- **Full run** (the default): expire snapshots, mark unreferenced files, and delete them, in a single run.
- **Dry run** (`dry_run=true`): only writes the run reports (under `<storage-namespace>/_lakefs/retention/iceberg/`); table metadata is untouched and nothing is deleted. A dry run's mark can never be swept by a later run.
- **Mark-only** (`do_sweep=false`): expires snapshots and records the deletion candidates for review; the run's logs and report name the resulting mark ID.
- **Sweep-only** (`do_mark=false` plus `mark_id`): deletes the candidates of an earlier mark. The mark must still be younger than the safety age; a failed or interrupted sweep can be resumed the same way, skipping what was already deleted.

#### Per-table controls

The current snapshot and every snapshot referenced by an Iceberg branch or tag ref are never expired. In addition, table owners can override the job's retention policy through standard Iceberg table properties:

- `lakefs-gc.enabled=false` excludes the table from snapshot expiration.
- `history.expire.min-snapshots-to-keep` and `history.expire.max-snapshot-age-ms` (on the table or per Iceberg ref) raise the protection when they retain more than the job policy does.

#### Run reports

Every run writes its artifacts under the repository's storage namespace, at `_lakefs/retention/iceberg/expire/<run-id>/` and `_lakefs/retention/iceberg/sweep/<run-id>/`: Parquet datasets of the planned expirations, their per-table outcomes, the deletion candidates, and the deletion outcomes, alongside a `summary.json` recording the run's configuration, status, and counts. A sweep run's ID is the mark ID that a sweep-only run enacts.

#### Limitations

- **Format-v3 tables**: snapshot expiration skips v3 tables, so their old snapshots, and the files only those snapshots reference, are not reclaimed. Each skipped table is logged and, when staging is enabled, reported with outcome `skipped-unreadable`. The storage sweep cleans v3 tables, except tables with encryption keys, which are not supported and may abort the run.
- **External tables**: a table whose pointer references metadata outside the lakeFS-managed location (e.g. registered with an external `metadataLocation`) is skipped - neither expired nor swept - and counted as skipped in the run report. Files it references inside other, managed tables' directories are not protected by the skip.
- **Format-v1 tables with embedded manifests**: v1 table metadata in which a snapshot embeds its manifest list directly (a `manifests` array instead of a `manifest-list` file pointer) is not supported, and aborts the run. This layout predates Iceberg 0.8; rewrite such tables before running the cleanup.
- **Compaction conflict resolution**: the [automatic conflict resolution for compaction commits](<#compact-data-files>) cannot yet handle expired snapshots. Merge compacted branches before the cleanup expires the snapshots involved, or such merges may conflict.

### Unsupported Operations

Iceberg's built-in table maintenance operations - the Spark procedures and `SparkActions` provided by Iceberg core - are not supported against the lakeFS catalog:

- [Drop table with purge](<https://iceberg.apache.org/docs/latest/spark-ddl/#drop-table-purge>)
- [Rewrite manifests](<https://iceberg.apache.org/docs/latest/maintenance/#rewrite-manifests>)
- [Expire snapshots](<https://iceberg.apache.org/docs/latest/maintenance/#expire-snapshots>)
- [Remove old metadata files](<https://iceberg.apache.org/docs/latest/maintenance/#remove-old-metadata-files>)
- [Delete orphan files](<https://iceberg.apache.org/docs/latest/maintenance/#delete-orphan-files>)

Instead, run the [lakeFS Iceberg Cleanup](<#tables-cleanup>), the lakeFS-provided maintenance job: it safely expires old snapshots and deletes unreferenced files - including old metadata files and the storage of dropped tables - once no retained lakeFS commit references them.

> [!CAUTION]
>
> **Danger**
>
> **To prevent data loss, clients must keep any other cleanup operation disabled:**
>
> - Disabling orphan file deletion.
> - Setting `remove-dangling-deletes` to false when rewriting.
> - Disabling snapshot expiration.

> [!NOTE]
>
> The `history.expire.min-snapshots-to-keep` and `history.expire.max-snapshot-age-ms` table properties also raise what [Tables Cleanup](<#tables-cleanup>) retains - avoid very high values on tables you expect cleanup to trim.

## Limitations

1. **Table Maintenance**:

   - See [Table Maintenance](<#table-maintenance>) section for details
2. **Advanced Features**:

   - Server-side query planning
   - Table renaming
   - Updating table's location (using Commit)
3. lakeFS Iceberg REST Catalog is currently tested to work with Amazon S3, S3-Compatible storage (such as MinIO), Google Cloud Storage and Azure Blob Storage.
4. Iceberg [table format](<https://iceberg.apache.org/spec/#format-versioning>) versions `v1`, `v2` and, from lakeFS Enterprise v1.110.0, `v3` are supported. New tables are `v2` unless the client requests `format-version` 3. [Tables Cleanup](<#tables-cleanup>) does not yet expire snapshots of `v3` tables.

## Roadmap

The following features are planned for future releases:

1. **Table Import**:

   - Support for importing existing Iceberg tables from other catalogs
   - Bulk import capabilities for large-scale migrations
2. **Azure Storage Support**
3. **Advanced Features**:

   - Views API support
   - Table transactions
4. **Advanced versioning capabilities**

   - merge non-conflicting table updates

## How It Works

Under the hood, the lakeFS Iceberg REST Catalog keeps track of each table's metadata file. This is typically referred to as the [table pointer](<https://iceberg.apache.org/spec/#overview>).

This pointer is stored inside the repository's [storage namespace](<https://docs.lakefs.io/resources/glossary/index.md#storage-namespace> "A storage namespace is a path on the underlying storage that defines where a lakeFS repository stores both metadata and data").

When a request is made, the catalog would examine the table's fully qualified namespace: `<repository>.<reference>.<namespace>.<table_name>` to read that special pointer file from the given reference specified, and returns the underlying object store location of the metadata file to the client. When a table is created or updated, lakeFS would make sure to generate a new metadata file inside the storage namespace, and register that metadata file as the current pointer for the requested branch. These changes are staged in lakeFS, and may be committed to the branch.

This approach builds on Iceberg's existing metadata and the immutability of its snapshots: a commit in lakeFS captures a metadata file, which in turn captures manifest lists, manifest files and all related data files.

Besides simply avoiding "double booking" where both Iceberg and lakeFS would need to keep track of which files belong to which version, it also greatly improves the scalability and compatibility of the catalog with the existing Iceberg tool ecosystem.

### Example: Reading an Iceberg Table

Here's a simplified example of what reading from an Iceberg table would look like:

```
sequenceDiagram
    Actor Iceberg Client
    participant lakeFS Catalog API
    participant lakeFS
    participant Object Store

    Iceberg Client->>lakeFS Catalog API: get table metadata("repo.branch.table")
    lakeFS Catalog API->>lakeFS: get('repo', 'branch', 'table')
    lakeFS->>lakeFS Catalog API: physical_address
    lakeFS Catalog API->>Iceberg Client: object location ("s3://.../metadata.json")
    Iceberg Client->>Object Store: GetObject
    Object Store->>Iceberg Client: table data
```

### Example: Writing an Iceberg Table

Here's a simplified example of what writing to an Iceberg table would look like:

```
sequenceDiagram
    Actor Iceberg Client
    participant lakeFS Catalog API
    participant lakeFS
    participant Object Store
    Iceberg Client->>Object Store: write table data
    Iceberg Client->>lakeFS Catalog API: Iceberg commit
    lakeFS Catalog API->>lakeFS: stage('new table pointer')
    lakeFS->>Object Store: PutObject("metdata.json")
    lakeFS Catalog API->>Iceberg Client: Iceberg commit done
    Iceberg Client->>lakeFS: lakeFS commit('repo','branch', message)
```

### Related Resources

> [!NOTE]
>
> **Further Reading**
>
> - [Iceberg REST Catalog API Specification](<https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/apache/iceberg/main/open-api/rest-catalog-open-api.yaml>)
> - [Iceberg Official Documentation](<https://iceberg.apache.org/docs/latest/>)
> - [lakeFS Enterprise Features](<https://docs.lakefs.io/editions/index.md>)

---

## Deprecated: Iceberg HadoopCatalog

> [!WARNING]
>
> `HadoopCatalog` and other filesystem-based catalogs are currently not recommended by the Apache Iceberg community and come with several limitations around concurrency and tooling.
>
> As such, the `HadoopCatalog` described in this section is now deprecated and will not receive further updates

### Setup

Use the following Maven dependency to install the lakeFS custom catalog:

```xml
<dependency>
<groupId>io.lakefs</groupId>
<artifactId>lakefs-iceberg</artifactId>
<version>0.1.4</version>
</dependency>
```

Include the `lakefs-iceberg` jar in your package list along with Iceberg. For example:

```python
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.3_2.12:1.3.0,io.lakefs:lakefs-iceberg:0.1.4")
```

### Configuration

Set up the Spark SQL catalog:

```python
.config("spark.sql.catalog.lakefs", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.lakefs.catalog-impl", "io.lakefs.iceberg.LakeFSCatalog") \
.config("spark.sql.catalog.lakefs.warehouse", f"lakefs://{repo_name}") \ 
.config("spark.sql.catalog.lakefs.cache-enabled", "false")
```

Configure the S3A Hadoop FileSystem with your lakeFS connection details. Note that these are your lakeFS endpoint and credentials, not your S3 ones.

```python
.config("spark.hadoop.fs.s3.impl", "org.apache.hadoop.fs.s3a.S3AFileSystem") \
.config("spark.hadoop.fs.s3a.endpoint", "https://example-org.us-east-1.lakefscloud.io") \
.config("spark.hadoop.fs.s3a.access.key", "AKIAIO5FODNN7EXAMPLE") \
.config("spark.hadoop.fs.s3a.secret.key", "wJalrXUtnFEMI/K3MDENG/bPxRfiCYEXAMPLEKEY") \
.config("spark.hadoop.fs.s3a.path.style.access", "true")
```

```shell
spark-shell --conf spark.sql.catalog.lakefs="org.apache.iceberg.spark.SparkCatalog" \
    --conf spark.sql.catalog.lakefs.catalog-impl="io.lakefs.iceberg.LakeFSCatalog" \
    --conf spark.sql.catalog.lakefs.warehouse="lakefs://example-repo" \
    --conf spark.sql.catalog.lakefs.cache-enabled="false" \
    --conf spark.hadoop.fs.s3.impl="org.apache.hadoop.fs.s3a.S3AFileSystem" \
    --conf spark.hadoop.fs.s3a.endpoint="https://example-org.us-east-1.lakefscloud.io" \
    --conf spark.hadoop.fs.s3a.access.key="AKIAIO5FODNN7EXAMPLE" \
    --conf spark.hadoop.fs.s3a.secret.key="wJalrXUtnFEMI/K3MDENG/bPxRfiCYEXAMPLEKEY" \
    --conf spark.hadoop.fs.s3a.path.style.access="true"
```

### Using Iceberg tables with HadoopCatalog

#### Create a table

To create a table on your main branch, use the following syntax:

```sql
CREATE TABLE lakefs.main.db1.table1 (id int, data string);
```

#### Insert data into the table

```sql
INSERT INTO lakefs.main.db1.table1 VALUES (1, 'data1');
INSERT INTO lakefs.main.db1.table1 VALUES (2, 'data2');
```

#### Create a branch

We can now commit the creation of the table to the main branch:

```shell
lakectl commit lakefs://example-repo/main -m "my first iceberg commit"
```

Then, create a branch:

```shell
lakectl branch create lakefs://example-repo/dev -s lakefs://example-repo/main
```

#### Make changes on the branch

We can now make changes on the branch:

```sql
INSERT INTO lakefs.dev.db1.table1 VALUES (3, 'data3');
```

#### Query the table

If we query the table on the branch, we will see the data we inserted:

```sql
SELECT * FROM lakefs.dev.db1.table1;
```

Results in:

```text
+----+------+
| id | data |
+----+------+
| 1  | data1|
| 2  | data2|
| 3  | data3|
+----+------+
```

However, if we query the table on the main branch, we will not see the new changes:

```sql
SELECT * FROM lakefs.main.db1.table1;
```

Results in:

```text
+----+------+
| id | data |
+----+------+
| 1  | data1|
| 2  | data2|
+----+------+
```

### Migrating an existing Iceberg table to the Hadoop Catalog

This is done through an incremental copy from the original table into lakeFS.

1. Create a new lakeFS repository `lakectl repo create lakefs://example-repo <base storage path>`
2. Initiate a spark session that can interact with the source iceberg table and the target lakeFS catalog. Here's an example of Hadoop and S3 session and lakeFS catalog with [per-bucket config](<https://docs.cloudera.com/HDPDocuments/HDP3/HDP-3.1.4/bk_cloud-data-access/content/s3-per-bucket-configs.html>):

   ```java
   SparkConf conf = new SparkConf();
   conf.set("spark.hadoop.fs.s3a.path.style.access", "true");

   // set hadoop on S3 config (source tables we want to copy) for spark
   conf.set("spark.sql.catalog.hadoop_prod", "org.apache.iceberg.spark.SparkCatalog");
   conf.set("spark.sql.catalog.hadoop_prod.type", "hadoop");
   conf.set("spark.sql.catalog.hadoop_prod.warehouse", "s3a://my-bucket/warehouse/hadoop/");
   conf.set("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions");
   conf.set("spark.hadoop.fs.s3a.bucket.my-bucket.access.key", "<AWS_ACCESS_KEY>");
   conf.set("spark.hadoop.fs.s3a.bucket.my-bucket.secret.key", "<AWS_SECRET_KEY>");

   // set lakeFS config (target catalog and repository)
   conf.set("spark.sql.catalog.lakefs", "org.apache.iceberg.spark.SparkCatalog");
   conf.set("spark.sql.catalog.lakefs.catalog-impl", "io.lakefs.iceberg.LakeFSCatalog");
   conf.set("spark.sql.catalog.lakefs.warehouse", "lakefs://example-repo");
   conf.set("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions");
   conf.set("spark.hadoop.fs.s3a.bucket.example-repo.access.key", "<LAKEFS_ACCESS_KEY>");
   conf.set("spark.hadoop.fs.s3a.bucket.example-repo.secret.key", "<LAKEFS_SECRET_KEY>");
   conf.set("spark.hadoop.fs.s3a.bucket.example-repo.endpoint"  , "<LAKEFS_ENDPOINT>");
   ```

   3\. Create Schema in lakeFS and copy the data

   Example of copy with spark-sql:

   ```sql
   -- Create Iceberg Schema in lakeFS
   CREATE SCHEMA IF NOT EXISTS <lakefs-catalog>.<branch>.<db>
   -- Create new iceberg table in lakeFS from the source table (pre-lakeFS)
   CREATE TABLE IF NOT EXISTS <lakefs-catalog>.<branch>.<db> USING iceberg AS SELECT * FROM <iceberg-original-table>
   ```
