> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/v1/interfaces/command-line-interface/lakehouse.md).

# Lakehouse commands

The `lakehouse` command group manages Iceberg tables inside a DataOS® Lakehouse: namespaces, tables, branches, schema, partitioning, properties, snapshots, and maintenance operations. A Data Engineer uses these commands to inspect and evolve Lakehouse tables directly from the terminal, without writing SQL DDL.

## Quick reference

| Command                                          | Description                                                    |
| ------------------------------------------------ | -------------------------------------------------------------- |
| `dataos-ctl lakehouse namespace list`            | List namespaces in a DataOS® Lakehouse                         |
| `dataos-ctl lakehouse operation apply`           | Apply a DataOS® Lakehouse operation                            |
| `dataos-ctl lakehouse operation delete`          | Delete a DataOS® Lakehouse operation                           |
| `dataos-ctl lakehouse operation get`             | Get a DataOS® Lakehouse operation                              |
| `dataos-ctl lakehouse table create`              | Create a table in a DataOS® Lakehouse                          |
| `dataos-ctl lakehouse table get`                 | Get details of a DataOS® Lakehouse table                       |
| `dataos-ctl lakehouse table list`                | List tables in a DataOS® Lakehouse namespace                   |
| `dataos-ctl lakehouse table branch create`       | Create a branch on a DataOS® Lakehouse table                   |
| `dataos-ctl lakehouse table branch delete`       | Delete a branch from a DataOS® Lakehouse table                 |
| `dataos-ctl lakehouse table branch fastforward`  | Fast-forward a target branch to match a source branch          |
| `dataos-ctl lakehouse table branch list`         | List branches of a DataOS® Lakehouse table                     |
| `dataos-ctl lakehouse table branch rename`       | Rename a branch on a DataOS® Lakehouse table                   |
| `dataos-ctl lakehouse table branch replace`      | Replace a branch on a DataOS® Lakehouse table                  |
| `dataos-ctl lakehouse table metadata get`        | Get metadata versions of a DataOS® Lakehouse table             |
| `dataos-ctl lakehouse table metadata set`        | Set the metadata version of a DataOS® Lakehouse table          |
| `dataos-ctl lakehouse table partition get`       | Get partition spec of a DataOS® Lakehouse table                |
| `dataos-ctl lakehouse table partition update`    | Update partition spec of a DataOS® Lakehouse table             |
| `dataos-ctl lakehouse table properties add`      | Add properties to a DataOS® Lakehouse table                    |
| `dataos-ctl lakehouse table properties get`      | Get properties of a DataOS® Lakehouse table                    |
| `dataos-ctl lakehouse table properties remove`   | Remove properties from a DataOS® Lakehouse table               |
| `dataos-ctl lakehouse table schema add-field`    | Add a field to a DataOS® Lakehouse table schema                |
| `dataos-ctl lakehouse table schema drop-field`   | Drop a field from a DataOS® Lakehouse table schema             |
| `dataos-ctl lakehouse table schema get`          | Get schema of a DataOS® Lakehouse table                        |
| `dataos-ctl lakehouse table schema rename-field` | Rename a field in a DataOS® Lakehouse table schema             |
| `dataos-ctl lakehouse table schema set-nullable` | Set field nullability in a DataOS® Lakehouse table schema      |
| `dataos-ctl lakehouse table schema update-field` | Update the type of a field in a DataOS® Lakehouse table schema |
| `dataos-ctl lakehouse table snapshot cherrypick` | Cherry-pick a snapshot into a DataOS® Lakehouse table          |
| `dataos-ctl lakehouse table snapshot list`       | List snapshots of a DataOS® Lakehouse table                    |
| `dataos-ctl lakehouse table snapshot rollback`   | Rollback a DataOS® Lakehouse table to a snapshot               |
| `dataos-ctl lakehouse table snapshot set`        | Set the current snapshot of a DataOS® Lakehouse table          |

{% hint style="info" %}
`lakehouse` accepts the aliases `lh`, `lakehouses`, and `lake-house`.
{% endhint %}

## Identifying a lakehouse and a table

Every command in this group needs `-n`/`--name`, the name of the **Lakehouse Resource** (for example `sales-lakehouse`), not the Depot that backs it. Passing a Depot name here returns `lakehouse '<name>' does not exist`.

Commands that operate on a specific table accept the target either as one identifier, or as three discrete flags:

| Flag                                       | Description                                                                               |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `-i`, `--identifier`                       | A single string: `lakehouse:namespace:table` or `lakehouse\|namespace\|table`.            |
| `-n`, `--name` + `--namespace` + `--table` | The Lakehouse Resource name, the Iceberg namespace, and the table name as separate flags. |

## dataos-ctl lakehouse namespace list

List the Iceberg namespaces available in a Lakehouse.

### Syntax

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse namespace list --name ${{lakehouse-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse namespace list --name sales-lakehouse
```

{% endtab %}
{% endtabs %}

### Flags

| Flag           | Description                     | Type    | Required |
| -------------- | ------------------------------- | ------- | -------- |
| `-n`, `--name` | Name of the Lakehouse Resource. | string  | Yes      |
| `-h`, `--help` | Display help for this command.  | boolean | No       |

{% hint style="info" %}
`namespace` accepts the aliases `ns` and `namespaces`.
{% endhint %}

## Lakehouse maintenance operations

The `operation` subcommand group submits and tracks maintenance jobs against a Lakehouse, such as compaction and snapshot expiry.

{% hint style="info" %}
`operation` accepts the aliases `op` and `operations`.
{% endhint %}

### dataos-ctl lakehouse operation apply

Submit a maintenance operation from a manifest file.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse operation apply --name ${{lakehouse-name}} -f ${{manifest-file-path}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse operation apply --name sales-lakehouse -f ./compact-operation.yaml
```

{% endtab %}
{% endtabs %}

| Flag                   | Description                             | Type    | Required |
| ---------------------- | --------------------------------------- | ------- | -------- |
| `-n`, `--name`         | Name of the Lakehouse Resource.         | string  | Yes      |
| `-f`, `--manifestFile` | Manifest file describing the operation. | string  | Yes      |
| `-h`, `--help`         | Display help for this command.          | boolean | No       |

The manifest's operation type determines the action: `COMPACT`, `COMPACT_DELETE_FILES`, `EXPIRE_SNAPSHOTS`, `REWRITE_MANIFESTS`, `DROP_TABLE`, `REMOVE_ORPHAN_FILES`, or `DELETE_FROM_DATASET`.

### dataos-ctl lakehouse operation get

Get maintenance operations, with optional filters and pagination.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse operation get \
  --name ${{lakehouse-name}} \
  [--namespace ${{namespace}}] [--table ${{table}}] \
  [--status ${{status}}] [--operation ${{operation-type}}] \
  [--page ${{page}}] [--size ${{page-size}}] [--all]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse operation get --name sales-lakehouse --status RUNNING
```

{% endtab %}
{% endtabs %}

| Flag           | Description                                                   | Type    | Required         |
| -------------- | ------------------------------------------------------------- | ------- | ---------------- |
| `-n`, `--name` | Name of the Lakehouse Resource.                               | string  | Yes              |
| `--id`         | ID of a specific operation.                                   | string  | No               |
| `--namespace`  | Filter by namespace.                                          | string  | No               |
| `--table`      | Filter by table.                                              | string  | No               |
| `--status`     | Filter by status: `QUEUED`, `RUNNING`, `COMPLETED`, `FAILED`. | string  | No               |
| `--operation`  | Filter by operation type.                                     | string  | No               |
| `-a`, `--all`  | Get operations from every user, not just the caller.          | boolean | No               |
| `--page`       | Page number.                                                  | int     | No, default `1`  |
| `--size`       | Page size.                                                    | int     | No, default `10` |
| `-h`, `--help` | Display help for this command.                                | boolean | No               |

### dataos-ctl lakehouse operation delete

Delete a maintenance operation record.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse operation delete --name ${{lakehouse-name}} --id ${{operation-id}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse operation delete --name sales-lakehouse --id op-4821
```

{% endtab %}
{% endtabs %}

| Flag           | Description                     | Type    | Required |
| -------------- | ------------------------------- | ------- | -------- |
| `-n`, `--name` | Name of the Lakehouse Resource. | string  | Yes      |
| `--id`         | ID of the operation to delete.  | string  | Yes      |
| `-h`, `--help` | Display help for this command.  | boolean | No       |

## Table commands

### dataos-ctl lakehouse table list

List tables in a namespace.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table list --name ${{lakehouse-name}} --namespace ${{namespace}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table list --name sales-lakehouse --namespace sales
```

{% endtab %}
{% endtabs %}

| Flag           | Description                            | Type    | Required |
| -------------- | -------------------------------------- | ------- | -------- |
| `-n`, `--name` | Name of the Lakehouse Resource.        | string  | Yes      |
| `--namespace`  | Iceberg namespace to list tables from. | string  | Yes      |
| `-h`, `--help` | Display help for this command.         | boolean | No       |

{% hint style="info" %}
`table` accepts the aliases `tb` and `tables`. `table list` operates at namespace scope, so it has no `--identifier` alternative.
{% endhint %}

### dataos-ctl lakehouse table create

Create a table from a manifest file describing its schema.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table create \
  --name ${{lakehouse-name}} --namespace ${{namespace}} --table ${{table}} \
  -f ${{manifest-file-path}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table create \
  --name sales-lakehouse --namespace sales --table orders \
  -f ./orders-schema.yaml
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                                                                    | Type    | Required |
| --------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table. See [Identifying a lakehouse and a table](#identifying-a-lakehouse-and-a-table). | string  | Yes      |
| `-f`, `--manifestFile`                              | Manifest file with the table schema.                                                           | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command.                                                                 | boolean | No       |

### dataos-ctl lakehouse table get

Get a table's details.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table get --name ${{lakehouse-name}} --namespace ${{namespace}} --table ${{table}} [--details]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table get --name sales-lakehouse --namespace sales --table orders --details
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-d`, `--details`                                   | Include detailed output.       | boolean | No       |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

## Table branch commands

Iceberg branches let you write to a table in isolation before merging changes into the main history.

### dataos-ctl lakehouse table branch list

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch list -i ${{lakehouse}}:${{namespace}}:${{table}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch list -i sales-lakehouse:sales:orders
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table branch create

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch create \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --branch ${{branch-name}} [--sid ${{snapshot-id}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch create -i sales-lakehouse:sales:orders --branch audit-2026-07
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                                  | Type    | Required |
| --------------------------------------------------- | ------------------------------------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                                | string  | Yes      |
| `--branch`                                          | Name of the branch to create.                                | string  | Yes      |
| `--sid`                                             | Snapshot ID to branch from. Defaults to the latest snapshot. | string  | No       |
| `-h`, `--help`                                      | Display help for this command.                               | boolean | No       |

### dataos-ctl lakehouse table branch rename

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch rename \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --branch ${{current-name}} --new-name ${{new-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch rename -i sales-lakehouse:sales:orders --branch audit-2026-07 --new-name audit-final
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--branch`                                          | Current branch name.           | string  | Yes      |
| `--new-name`                                        | New branch name.               | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table branch fastforward

Fast-forward a target branch to match a source branch that is ahead of it.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch fastforward \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --source ${{ahead-branch}} --target ${{behind-branch}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch fastforward -i sales-lakehouse:sales:orders --source audit-final --target main
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                        | Type    | Required |
| --------------------------------------------------- | -------------------------------------------------- | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                      | string  | Yes      |
| `--source`                                          | Branch that is ahead, which provides the changes.  | string  | Yes      |
| `--target`                                          | Branch that is behind, which receives the changes. | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command.                     | boolean | No       |

### dataos-ctl lakehouse table branch replace

Replace a branch with another branch or a specific snapshot.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch replace \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --branch ${{branch-to-replace}} \
  [--source ${{source-branch}}] [--sid ${{snapshot-id}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch replace -i sales-lakehouse:sales:orders --branch main --source audit-final
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required                   |
| --------------------------------------------------- | ------------------------------ | ------- | -------------------------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes                        |
| `--branch`                                          | Branch to replace.             | string  | Yes                        |
| `--source`                                          | Source branch to replace with. | string  | One of `--source`, `--sid` |
| `--sid`                                             | Snapshot ID to replace with.   | string  | One of `--source`, `--sid` |
| `-h`, `--help`                                      | Display help for this command. | boolean | No                         |

### dataos-ctl lakehouse table branch delete

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table branch delete -i ${{lakehouse}}:${{namespace}}:${{table}} --branch ${{branch-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table branch delete -i sales-lakehouse:sales:orders --branch audit-2026-07
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--branch`                                          | Branch to delete.              | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

{% hint style="warning" %}
Deleting a branch removes access to any snapshots reachable only from that branch, unless they are also referenced by another branch or tag.
{% endhint %}

## Table metadata commands

Metadata versions track Iceberg's `metadata.json` pointer history, a lower-level rollback mechanism than snapshots.

### dataos-ctl lakehouse table metadata get

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table metadata get -i ${{lakehouse}}:${{namespace}}:${{table}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table metadata get -i sales-lakehouse:sales:orders
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table metadata set

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table metadata set -i ${{lakehouse}}:${{namespace}}:${{table}} --version ${{metadata-version}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table metadata set -i sales-lakehouse:sales:orders --version 00012-a1b2c3d4.metadata.json
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                          | Type    | Required |
| --------------------------------------------------- | ---------------------------------------------------- | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                        | string  | Yes      |
| `--version`                                         | Metadata version to set, as shown by `metadata get`. | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command.                       | boolean | No       |

## Table partition commands

### dataos-ctl lakehouse table partition get

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table partition get -i ${{lakehouse}}:${{namespace}}:${{table}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table partition get -i sales-lakehouse:sales:orders
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table partition update

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table partition update -i ${{lakehouse}}:${{namespace}}:${{table}} -f ${{manifest-file-path}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table partition update -i sales-lakehouse:sales:orders -f ./partition-spec.yaml
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                | Type    | Required |
| --------------------------------------------------- | ------------------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                              | string  | Yes      |
| `-f`, `--manifestFile`                              | Manifest file with the new partition spec. | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command.             | boolean | No       |

{% hint style="info" %}
Updating a partition spec evolves it going forward. Existing data files keep their original partition layout; Iceberg does not rewrite historical data.
{% endhint %}

## Table properties commands

Table properties are arbitrary key-value configuration, such as `write.format.default`.

### dataos-ctl lakehouse table properties get

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table properties get -i ${{lakehouse}}:${{namespace}}:${{table}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table properties get -i sales-lakehouse:sales:orders
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table properties add

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table properties add -i ${{lakehouse}}:${{namespace}}:${{table}} --kv ${{key}}=${{value}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table properties add -i sales-lakehouse:sales:orders \
  --kv write.format.default=parquet --kv commit.retry.num-retries=5
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                                    | Type        | Required |
| --------------------------------------------------- | -------------------------------------------------------------- | ----------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                                  | string      | Yes      |
| `--kv`                                              | A `key=value` pair to add. Repeat the flag for multiple pairs. | stringArray | Yes      |
| `-h`, `--help`                                      | Display help for this command.                                 | boolean     | No       |

### dataos-ctl lakehouse table properties remove

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table properties remove -i ${{lakehouse}}:${{namespace}}:${{table}} --key ${{key}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table properties remove -i sales-lakehouse:sales:orders --key commit.retry.num-retries
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                                  | Type        | Required |
| --------------------------------------------------- | ------------------------------------------------------------ | ----------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                                | string      | Yes      |
| `--key`                                             | A property key to remove. Repeat the flag for multiple keys. | stringArray | Yes      |
| `-h`, `--help`                                      | Display help for this command.                               | boolean     | No       |

## Table schema commands

Schema commands evolve a table's columns one field at a time.

### dataos-ctl lakehouse table schema get

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema get -i ${{lakehouse}}:${{namespace}}:${{table}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema get -i sales-lakehouse:sales:orders
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table schema add-field

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema add-field \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --field-name ${{field-name}} --type ${{field-type}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema add-field -i sales-lakehouse:sales:orders \
  --field-name discount_amount --type decimal --precision 10 --scale 2
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                                                                                | Type    | Required          |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------- | ----------------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                                                                              | string  | Yes               |
| `--field-name`                                      | Name of the new field.                                                                     | string  | Yes               |
| `--type`                                            | Field type: a primitive such as `string`, `int`, `long`, `double`, or `decimal`, or `map`. | string  | Yes               |
| `-p`, `--precision`                                 | Precision, for `decimal` fields.                                                           | int     | No, default `10`  |
| `-s`, `--scale`                                     | Scale, for `decimal` fields.                                                               | int     | No, default `2`   |
| `-k`, `--keyType`                                   | Key datatype, for `map` fields.                                                            | string  | With `--type map` |
| `-v`, `--valueType`                                 | Value datatype, for `map` fields.                                                          | string  | With `--type map` |
| `-h`, `--help`                                      | Display help for this command.                                                             | boolean | No                |

New fields are added as nullable by default.

### dataos-ctl lakehouse table schema update-field

Change the type of an existing field. Iceberg only allows type promotions that preserve compatibility, such as `int` to `long` or widening a `decimal`'s precision.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema update-field \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --field-name ${{field-name}} --type ${{new-type}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema update-field -i sales-lakehouse:sales:orders --field-name quantity --type long
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                      | Type    | Required         |
| --------------------------------------------------- | -------------------------------- | ------- | ---------------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                    | string  | Yes              |
| `--field-name`                                      | Name of the field to update.     | string  | Yes              |
| `--type`                                            | New field type.                  | string  | Yes              |
| `-p`, `--precision`                                 | Precision, for `decimal` fields. | int     | No, default `10` |
| `-s`, `--scale`                                     | Scale, for `decimal` fields.     | int     | No, default `2`  |
| `-h`, `--help`                                      | Display help for this command.   | boolean | No               |

### dataos-ctl lakehouse table schema rename-field

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema rename-field \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --field-name ${{current-name}} --new-name ${{new-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema rename-field -i sales-lakehouse:sales:orders --field-name qty --new-name quantity
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--field-name`                                      | Current field name.            | string  | Yes      |
| `--new-name`                                        | New field name.                | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table schema set-nullable

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema set-nullable \
  -i ${{lakehouse}}:${{namespace}}:${{table}} \
  --field-name ${{field-name}} --nullable=${{true-or-false}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema set-nullable -i sales-lakehouse:sales:orders --field-name customer_id --nullable=false
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                     | Type    | Required           |
| --------------------------------------------------- | ------------------------------- | ------- | ------------------ |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                   | string  | Yes                |
| `--field-name`                                      | Field to update.                | string  | Yes                |
| `--nullable`                                        | Whether the field allows nulls. | boolean | No, default `true` |
| `-h`, `--help`                                      | Display help for this command.  | boolean | No                 |

{% hint style="warning" %}
`--nullable` defaults to `true`. Pass `--nullable=false` explicitly to make a field required; Iceberg rejects this if the table already contains null values in that field.
{% endhint %}

### dataos-ctl lakehouse table schema drop-field

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table schema drop-field -i ${{lakehouse}}:${{namespace}}:${{table}} --field-name ${{field-name}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table schema drop-field -i sales-lakehouse:sales:orders --field-name legacy_notes
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--field-name`                                      | Field to drop.                 | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

## Table snapshot commands

Snapshots are Iceberg's data commits; each write to a table produces one.

### dataos-ctl lakehouse table snapshot list

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table snapshot list -i ${{lakehouse}}:${{namespace}}:${{table}} [--branch ${{branch-name}}]
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table snapshot list -i sales-lakehouse:sales:orders --branch main
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                      | Type    | Required |
| --------------------------------------------------- | -------------------------------- | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                    | string  | Yes      |
| `--branch`                                          | Filter snapshots by branch name. | string  | No       |
| `-h`, `--help`                                      | Display help for this command.   | boolean | No       |

### dataos-ctl lakehouse table snapshot set

Set the current snapshot pointer to any snapshot ID, including one outside the current branch's ancestry.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table snapshot set -i ${{lakehouse}}:${{namespace}}:${{table}} --sid ${{snapshot-id}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table snapshot set -i sales-lakehouse:sales:orders --sid 5813723014234567890
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--sid`                                             | Snapshot ID to set as current. | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table snapshot rollback

Roll a table back to a snapshot that is an ancestor of the current one.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table snapshot rollback -i ${{lakehouse}}:${{namespace}}:${{table}} --sid ${{snapshot-id}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table snapshot rollback -i sales-lakehouse:sales:orders --sid 5813723014234567890
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--sid`                                             | Snapshot ID to roll back to.   | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

### dataos-ctl lakehouse table snapshot cherrypick

Cherry-pick a snapshot's changes into the current branch's lineage, without a full branch merge.

{% tabs %}
{% tab title="Syntax" %}

```bash
dataos-ctl lakehouse table snapshot cherrypick -i ${{lakehouse}}:${{namespace}}:${{table}} --sid ${{snapshot-id}}
```

{% endtab %}

{% tab title="Example" %}

```bash
dataos-ctl lakehouse table snapshot cherrypick -i sales-lakehouse:sales:orders --sid 5813723014234567891
```

{% endtab %}
{% endtabs %}

| Flag                                                | Description                    | Type    | Required |
| --------------------------------------------------- | ------------------------------ | ------- | -------- |
| `-i`, `--identifier` / `-n`+`--namespace`+`--table` | Target table.                  | string  | Yes      |
| `--sid`                                             | Snapshot ID to cherry-pick.    | string  | Yes      |
| `-h`, `--help`                                      | Display help for this command. | boolean | No       |

## Validation rules

* `-n`/`--name` must be a Lakehouse Resource name, not the Depot name that backs it; using the Depot name returns `lakehouse '<name>' does not exist`.
* Reading namespaces, operations, or tables requires an explicit read grant on that Lakehouse Resource. A missing grant returns a `Forbidden` error naming the required permission object, not an empty result.
* `--kv` (properties add) and `--key` (properties remove) are repeatable flags; pass the flag once per entry rather than a comma-separated list.
* `schema set-nullable --nullable=false` fails if the table already contains null values in that field.

## Related commands

* [Resource commands](/references/v1/interfaces/command-line-interface/resource.md): apply and inspect the Lakehouse Resource itself.
* Depot commands: inspect the `lakehouse` Depot type schema that backs a Lakehouse Resource.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/references/v1/interfaces/command-line-interface/lakehouse.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.