> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://mammoth.io/docs/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# mammoth batch

> All 7 mammoth batch commands with examples, arguments and confirmation flags: Run and inspect batch operations.

> Generated from mammoth-cli 2.4.2, released 2026-11-02: `mammoth schema list`, `mammoth capability list` and the CLI's own `--help`. Do not edit by hand; run `npm run docs:capabilities`.

Run and inspect batch operations. 7 commands.

Every command also takes the [global flags](https://mammoth.io/docs/build/cli/global-flags/) (`--output`, `--yes`, `--confirm`, `--dry-run`, `--input`, `--profile`, ...), which are not repeated below. `--input` takes a JSON or YAML document of the input fields; `mammoth schema get COMMAND_ID` prints a command's full input schema.

**Confirmation.** Commands marked `--yes --confirm TARGET` or `--yes` always need those flags, even at a terminal: they never prompt. Commands marked "`--yes` or prompt" ask at an interactive terminal (table output, no `--no-input`) and otherwise need `--yes`. `--dry-run` skips confirmation and sends nothing.

## Summary

| Command | What it does | Effect | Confirmation |
|---|---|---|---|
| [`batch bulk-delete`](#mammoth-batch-bulk-delete) | Bulk-delete the named batches of a dataset. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`batch create`](#mammoth-batch-create) | Create a batch for a dataset. 'source_id' and 'mapping' are required. | Benign mutation | — |
| [`batch create-spec`](#mammoth-batch-create-spec) | Create a batch using the release 'BatchesPostRequest' envelope. | Benign mutation | — |
| [`batch delete`](#mammoth-batch-delete) | Delete one batch by id. Prompt or '--yes' required. | Destructive | `--yes` or prompt |
| [`batch get`](#mammoth-batch-get) | Get one batch by id for a dataset in the active project. | Read | — |
| [`batch list`](#mammoth-batch-list) | List batches for a dataset in the active project. | Read | — |
| [`batch update`](#mammoth-batch-update) | Apply patch operations to a dataset's batches. 'patch' is required. | Benign mutation | — |

## batch commands

### mammoth batch bulk-delete

Bulk-delete the named batches of a dataset. Prompt or '--yes' required.

```bash
mammoth batch bulk-delete 123 --input '{"ids": [11, 12]}' --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `ids` | `--input` field | no | — | `list[int] \| str \| None` |  |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal
- **Preconditions:** ids is required (the backend rejects a delete with no batch ids; it never deletes all batches). List ids with batch list.
- **Id:** `batch.bulk-delete` · **Result:** `BatchBulkDeleteResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.bulk_delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches` (DeleteBatches)

### mammoth batch create

Create a batch for a dataset. 'source_id' and 'mapping' are required.

```bash
mammoth batch create 123 456 --input '{"mapping": {"column_1": "column_1"}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `SOURCE_ID` | positional | yes | — | `int` | ID of the source. |
| `mapping` | `--input` field | yes | — | `dict[str, str] \| list[dict[str, Any]]` |  |
| `new_ds_params` | `--input` field | no | — | `dict[str, any]` |  |
| `is_validation_required` | `--input` field | no | — | `bool` |  |
| `change_map` | `--input` field | no | — | `dict[str, any]` |  |
| `delete_source_ds` | `--input` field | no | `false` | `bool` |  |
| `expected_destination_c_type` | `--input` field | no | `TEXT` | `str` |  |
| `blank_columns` | `--input` field | no | — | `list[str]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** returns a job id at once; follow it with `mammoth job wait`
- **Preconditions:** Every source column must be mapped to an existing destination column; the CLI reads both schemas and refuses (append_mapping_incomplete) an unmapped source column or a destination the dataset lacks, because the backend appends only mapped columns. A destination column no mapping item fills (add_column items count) would be NULL in every appended row, so it is refused (append_leaves_columns_blank) unless the input lists exactly those names in blank_columns; the confirmed blanks are named in mapping_check.warnings. The CLI sends each item's expected_destination_c_type as the destination's current type (never re-types it; an explicit different value is refused with append_type_mismatch) and warns in mapping_check.warnings when source and destination types differ. SOURCE_ID is a standalone dataset in the same project (4BATC010 INVALID_SOURCE_DATASET for a file id or an append child); to append a file use file upload with append_to_ds_id. delete_source_ds=true changes the mutation class to destructive and requires confirmation.
- **Id:** `batch.create` · **Result:** `BatchCreateResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.create`, API `POST /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches` (CreateBatch)

### mammoth batch create-spec

Create a batch using the release 'BatchesPostRequest' envelope.

```bash
mammoth batch create-spec 123 --input '{"file_id": 94}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `source_id` | `--input` field | no | — | `int` |  |
| `mapping` | `--input` field | no | — | `list[ColumnNameMapping] \| list[ColumnIdMapping] \| None` |  |
| `validate_only` | `--input` field | no | `false` | `bool` |  |
| `delete_source_ds` | `--input` field | no | `false` | `bool` |  |
| `new_ds_details` | `--input` field | no | — | `NewDsDetails` |  |
| `file_id` | `--input` field | no | — | `int` |  |
| `projected_source_schema` | `--input` field | no | — | `list[ProjectedSourceColumn]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** returns a job id at once; follow it with `mammoth job wait`
- **Preconditions:** Release BatchesPostRequest; file_id-only or source_id plus homogeneous mapping array. Dynamic confirmation applies only to delete_source_ds.
- **Id:** `batch.create-spec` · **Result:** `BatchCreateSpecResult`

### mammoth batch delete

Delete one batch by id. Prompt or '--yes' required.

```bash
mammoth batch delete 123 456 --yes
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `BATCH_ID` | positional | yes | — | `int` | ID of the batch. |

- **Effect:** Destructive, scope `project` · **Confirmation:** `--yes`, or answer the prompt at an interactive terminal · **Waits:** returns a job id at once; follow it with `mammoth job wait`
- **Preconditions:** Resolve the batch before confirmation.
- **Id:** `batch.delete` · **Result:** `BatchDeleteResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.delete`, API `DELETE /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches/{batch_id}` (DeleteBatch)

### mammoth batch get

Get one batch by id for a dataset in the active project.

```bash
mammoth batch get 123 456
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `BATCH_ID` | positional | yes | — | `int` | ID of the batch. |

- **Effect:** Read, scope `project` · **Confirmation:** none
- **Preconditions:** Required inputs: DATASET_ID, BATCH_ID.
- **Id:** `batch.get` · **Result:** `BatchGetResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.get`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches/{batch_id}` (GetBatch)

### mammoth batch list

List batches for a dataset in the active project.

```bash
mammoth batch list 123
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `limit` | `--input` field | no | `50` | `int` |  |
| `offset` | `--input` field | no | `0` | `int` |  |

- **Effect:** Read, scope `project` · **Confirmation:** none · **Pages:** `offset`
- **Preconditions:** Required inputs: DATASET_ID.
- **Id:** `batch.list` · **Result:** `BatchListResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.list`, API `GET /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches` (GetBatches)

### mammoth batch update

Apply patch operations to a dataset's batches. 'patch' is required.

```bash
mammoth batch update 123 --input '{"patch": {"name": "Status"}}'
```

| Name | Passed as | Required | Default | Type | Notes |
|---|---|---|---|---|---|
| `DATASET_ID` | positional | yes | — | `int` | ID of the dataset. |
| `patch` | `--input` field | yes | — | `dict[str, Any] \| list[dict[str, Any]]` |  |

- **Effect:** Benign mutation, scope `project` · **Confirmation:** none · **Waits:** returns a job id at once; follow it with `mammoth job wait`
- **Preconditions:** The server takes one patch operation per call: {"patch": {"op": "replace", "path": "batches", "value": {"suspend": \[BATCH_ID\], "restore": \[BATCH_ID\]}}} (a list holding that one operation is also accepted; "path" defaults to batches). Any remove operation in the patch changes the mutation class to destructive.
- **Id:** `batch.update` · **Result:** `BatchUpdateResult` · **Backed by:** SDK `mammoth.api.batches.BatchesAPI.update`, API `PATCH /workspaces/{workspace_id}/projects/{project_id}/datasets/{dataset_id}/batches` (UpdateBatches)

---
Source: https://mammoth.io/docs/build/cli/batch.md · Updated: 2026-11-02
