# Iceberg table permissions

:::callout{theme="neutral"}
The default roles listed on this page are the out-of-the-box defaults from Palantir. Your administrator may have configured custom settings for your environment via [custom role sets](../../platform-security-management/manage-roles/index.md#role-sets).
:::

This page describes the operations that govern what you can do with Foundry [Iceberg tables](../../data-integration/iceberg-tables/index.md). Operations are the individual permissions Foundry checks before allowing an action, and [roles](../../security/projects-and-roles/index.md#roles) are collections of operations that you can grant to users. For more information about how operations and roles relate, see [Understanding roles and operations](../../platform-security-management/manage-roles/index.md#understanding-roles-and-operations).

## Reading and writing Iceberg tables

The broader `table:read` and `table:write` operations govern reading and writing Iceberg tables. These operations apply to both Iceberg tables and virtual tables.

## Main branch protection

:::callout{theme="neutral"}
Main branch protection support for Iceberg tables is in Beta and may not yet be available on your environment.
:::

Main branch protection refers specifically to **resource** branch protection on the table, and not to **code** branch protection on the backing code.

If you have [main branch protection](../../global-branching/resource-protection-and-approval-policies/index.md#resource-protection) enabled on your Iceberg table resource, you must have the following operation to make changes outside of the owning [Foundry job spec](../../data-integration/builds/index.md#jobs-and-jobspecs).

Foundry generates the job spec automatically from the pipeline that authored the table, such as the Pipeline Builder or Python transforms logic that created the resource. To make changes outside of this owning resource, you must have an additional elevated permission that bypasses the table's main branch protection.

| Operation | Display name | Default role |
|---|---|---|
| **`iceberg:bypass-branch-protection`** | Bypass branch protection | `Owner` |

You commonly need this operation to make changes to a branch-protected table from either a [maintenance task](../maintenance-page/index.md) or an [external client](../authentication/index.md).

## Maintenance task operations

These operations control who can read and write [maintenance tasks](../maintenance-page/index.md) on an Iceberg table.

| Operation | Display name | Default role |
|---|---|---|
| **`iceberg:read-maintenance-tasks`** | Read table maintenance tasks | `Viewer` |
| **`iceberg:write-maintenance-tasks`** | Write table maintenance tasks | `Editor` |
| **`iceberg:write-sql-maintenance-tasks`** | Write custom SQL maintenance tasks | `Editor` |
| **`iceberg:write-data-altering-maintenance-tasks`** | Write data-altering maintenance tasks | `Editor` |
| **`iceberg:schedule-maintenance-tasks`** | Create a new schedule on maintenance tasks (of any type) | `Editor` |

The three `write` operations are cumulative. Writing or editing any maintenance task always requires `iceberg:write-maintenance-tasks`. Depending on the task category, Foundry also checks the more specific `iceberg:write-sql-maintenance-tasks` and `iceberg:write-data-altering-maintenance-tasks` operations. As a result, removing `iceberg:write-maintenance-tasks` from a role removes the ability to author maintenance tasks entirely, even if the role still includes the other two operations.

Creating or editing a task also requires permission to read and write the underlying table data. On a branch-protected table, [main branch protection](#main-branch-protection) applies as well.

### Maintenance operations in practice

The following table shows the operations you need to write each kind of task:

| Task type | Required operations |
|---|---|
| **Form-based procedures:**<br>For example, `Rewrite data files` or `Expire snapshots` | `iceberg:write-maintenance-tasks` |
| **`Custom SQL` that does not logically alter the current snapshot:**<br>For example, `CALL system.rewrite_data_files(...)` | `iceberg:write-maintenance-tasks`<br>+ `iceberg:write-sql-maintenance-tasks` |
| **`Custom SQL` that logically alters the current snapshot:**<br>For example, `INSERT`, `UPDATE`, `DELETE` | `iceberg:write-maintenance-tasks`<br>+ `iceberg:write-sql-maintenance-tasks`<br>+ `iceberg:write-data-altering-maintenance-tasks` |

### Combining branch protection with maintenance operations

Foundry checks the operation to bypass [main branch protection](#main-branch-protection) and the operations to [edit maintenance tasks](#maintenance-operations-in-practice) independently. This lets you separate who can author a kind of change from the tables they can apply it to.

For example:

* To write a Custom SQL maintenance task against a table that is **not branch protected**, a user needs `iceberg:write-sql-maintenance-tasks` and `iceberg:write-maintenance-tasks`.
* To write the same task against a table that **is branch protected**, a user needs those same two operations and additionally `iceberg:bypass-branch-protection`.