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

# Add or replace data

> Append new rows to a Mammoth dataset or replace it, using a file upload or another dataset. Covers update methods, column mapping, validation, and results.

The **Add or Replace Data** workflow lets you update an existing dataset without starting from scratch. You can append new rows on top of your existing data, or overwrite it entirely, using either a file upload or another dataset in your project as the source. This guide is for anyone who maintains datasets. Start with [Select a workflow](#select-a-workflow).

Use this when you need to:

- Load the latest period of data into a running dataset (append)
- Swap a dataset with a completely refreshed export (replace)
- Merge two datasets that share the same schema

> **Note:** The operation runs in the background. You do not need to wait on the modal. Track progress in the **Batches** section of the dataset preview panel or in the **Activity Log**.

## Select a workflow

| Scenario | Source | Go to |
| --- | --- | --- |
| You have a new file (CSV, Excel, etc.) to load | **Upload file** | [Path A: upload a file](#path-a-upload-a-file) |
| You want to pull data from another dataset in your project | **Select existing** | [Path B: select an existing dataset](#path-b-select-an-existing-dataset) |

Both paths use the same **Add or Replace Data** modal. To open it:

- **From the preview panel:** Click any dataset row, scroll to **Batches**, and click **Add new data**
- **From the context menu:** Hover any dataset row, click **⋯**, and choose **Add or Replace data**

Both entry points are available only for file-based datasets that have views. **Add new data** is not shown on the standalone Dataset Settings page.

The dialog is titled with the dataset name followed by **Add or Replace data**. It has an **Input File** row (**Upload file** or **Select existing**) and an **Update Method** row. Choosing **Update Method** saves it to the dataset immediately, even if you then select **Cancel**. The same setting applies to both paths.

![Add or Replace data dialog with Upload file selected, Update Method set to Combine with older data, the PDF callout, and a disabled Submit button](https://docs.mammoth.io/api/v1/images/20261009_013939_Add-or-Replace-data-dialog.jpg)

## Path A: upload a file

**Prerequisite**: You have Edit-level access to the dataset and a file in a supported format.


### Step 1: Choose an update method

| Method | What it does | Best for |
| --- | --- | --- |
| **Combine with older data** *(default)* | Appends new rows to the existing dataset. Previous data is kept. | Incremental loads such as daily sales, event logs, transaction feeds |
| **Replace the older data** | Deletes all existing rows and inserts the new data. | Full snapshots such as weekly inventory exports or complete dimension tables |

![Update Method dropdown open, listing Combine with older data (highlighted) and Replace the older data](https://docs.mammoth.io/api/v1/images/20260430_065748_update_method_dropdown1.jpg)

### Step 2: Upload your file

| Detail | Value |
| --- | --- |
| Maximum file size | 50 MB ([limits](https://docs.mammoth.io/learn/limits-and-quotas)) |
| Accepted formats | CSV, TSV, PSV, TXT, XLS, XLSX, XML, ZIP, BZ2, GZ, TAR, 7Z, PDF, TIFF, JPEG, JPG, PNG, HEIC, WEBP |

1. Drag a file onto the drop zone, or click **Upload file** to browse your computer.
2. Choose your **Update Method** (Combine or Replace).
3. Optionally configure **Batch & Column Mapping settings** (see below). This row is not shown for PDF files.
4. If the Update Method is Replace and the file is not a PDF, select **Replace and use the new file's columns** when the file has new or renamed columns. The dataset's columns then become the file's columns.
5. Click **Submit**. The button stays disabled until a file is selected.

A callout in the dialog explains that uploading a PDF replays the dataset's saved recipe automatically, while uploading a CSV or Excel file appends it directly by matching columns.

**Expected result**: The dialog closes and Mammoth processes the file in the background. A new row appears in the **Batches** list. It reads **Applying recipe** while Mammoth structures the file, or **Pending** if the batch needs your input, such as a column mapping, a sheet selection, or a file password. Select a pending row to resolve it.

---

### Batch and column mapping settings

The **Batch & Column Mapping settings** line appears below the file drop zone. It shows whether the dataset's incoming-data rules are set to **Default** or **Custom**.

![Batch & Column Mapping settings row showing Default, with a pencil icon at the right to edit](https://docs.mammoth.io/api/v1/images/20260505_060023_batch_col_mapping_area1.jpg)

- **Default**: Mammoth maps columns by matching names and converts mismatched column types to text.
- **Custom**: The dataset has saved, non-default mapping rules.

Selecting the row (a pencil icon appears when you hover) opens the **Combine / Replace Settings** sub-dialog.

![Combine / Replace Settings dialog with If column type doesn't match set to Convert destination column to text and Column Mapping set to Map with existing columns](https://docs.mammoth.io/api/v1/images/20260505_060336_combine_replace_setting_modal1.jpg)

#### If column type doesn't match

| Option | Behavior |
| --- | --- |
| **Convert destination column to text** *(default)* | Changes the destination column's type to Text so all incoming values fit. Broadest compatibility, with no data lost. |
| **Convert incompatible values to null** | Keeps the destination column's original type. Incoming values that can't be cast to that type are stored as `null`. |
| **Do not update the dataset** | Aborts the operation if any column type mismatch is detected. Use this when strict type integrity is required. |

#### Column mapping

| Option | Behavior |
| --- | --- |
| **Map with existing columns** *(default)* | Mammoth auto-matches incoming columns to destination columns by exact display name. No manual mapping required. |
| **Create new column mapping** | You define one or more **name aliases** per destination column. Mammoth uses these aliases to recognize the correct incoming column even if the name differs between files. |

**When to use aliases:** If the same column appears under different headers in different source files (for example, `Cust_ID`, `CustomerID`, or `Customer id`), define aliases so Mammoth always maps them to the right destination column.

When **Create new column mapping** is selected, a mapping table appears showing every destination column alongside its configured aliases:

| Element | Description |
| --- | --- |
| **Alias pills** (for example, `Customer id ×`) | The name(s) Mammoth will look for in incoming data. Click a pill to edit its name; click **×** to remove it. Multiple aliases are joined with "or", so any match will work. |
| **+ button** | Adds a new alias for this column. |
| **Toggle** | Enables or disables mapping for this destination column. |
| **Type icon + column name** (right side) | The destination column's data type and name. |

The **All destination columns must be mapped** checkbox: when checked, new data is added only if its number of columns matches the existing dataset.

Click **Save changes** to persist the configuration. The **Batch & Column Mapping settings** line updates to show **Custom**.

**Expected result**: Future loads use your saved mapping rules.

## Path B: select an existing dataset

**Prerequisite**: You have Edit-level access to the destination dataset and can see the source dataset in the same project.

Use **Select existing** when you want to combine or replace using data from another dataset already in your project.

### Step 1: Select the source dataset

![Select existing source list showing store_transaction and cust1-extra-col.xls_test02, a data preview, and a Review Column Mapping button](https://docs.mammoth.io/api/v1/images/20260430_065845_select-existing-list-dataset-to-combine1.jpg)

Open the **Dataset** picker and choose the source. It lists the other datasets in the current project, plus the project's unprocessed PDF files (marked **Unprocessed PDF**).

Datasets that hold unstructured data are marked with a warning icon and **Needs structuring**. They appear only when the destination dataset has a saved recipe, and they must be structured to match the destination before they can combine.

Once a dataset is selected, a data preview appears showing the source columns and the first rows of data.

Two picks behave differently:

- **Unprocessed PDF**: Mammoth replays the destination's saved recipe against the PDF. There is no column mapping, and the button is **Submit**.
- **Needs structuring**: The button is **Apply Recipe**. It previews the destination's recipe applied to the source dataset, and nothing is written until you select **Submit**. Submitting confirms the recipe on the source and deletes the source dataset.

---

### Step 2: Check the update method

The **Update Method** at the top of the dialog also applies here. **Combine with older data** (default) appends the source rows and keeps previous data. **Replace the older data** deletes all existing rows and inserts the source rows. The table under [Step 1 of Path A](#step-1-choose-an-update-method) describes both.

![Animation of the Add or Replace data dialog with Select existing chosen and an empty Select dataset dropdown](https://docs.mammoth.io/api/v1/images/20260508_050328_map-replace.gif)

---

### The Delete dataset after combining checkbox

The **Delete dataset after combining** checkbox is checked by default. It is hidden when you pick a PDF or a dataset that needs structuring. If left checked, Mammoth permanently deletes the source dataset after the operation completes. Uncheck it to keep the source dataset intact. Leave it checked only when the source is a temporary staging dataset that is no longer needed after the merge.

![Add or Replace data dialog with Select existing chosen, orders.csv in the source field, and Delete dataset after combining checked](https://docs.mammoth.io/api/v1/images/20260505_060220_Screenshot2026-04-281612071.jpg)

---

### Step 3: Check schema validation

After selecting a source dataset, Mammoth automatically checks whether its column structure matches the destination's schema.

| Outcome | Indicator | What to do |
| --- | --- | --- |
| Schemas match | Green check: "New data matches the settings" | Click **Validate** or **Submit**, or **Review Column Mapping** to adjust |
| Schemas differ | Red message: "This new data does not matches the settings" | Click **Review Column Mapping**, then complete Step 4 |

---

### Step 4: Review column mapping (only if schemas differ)

![Column mapping view with Customer id unmapped, Customer name and Item matched, Save results into options, and Previous and Validate buttons](https://docs.mammoth.io/api/v1/images/20260430_071019_review-column-mapping1.jpg)

The sub-header confirms what is happening:

```plaintext
[Destination dataset] is combining data with [Source dataset]   ☑ Delete dataset after combining
```

The mapping table lists every destination column on the left (with its data type icon) and a **Select column** dropdown on the right for choosing the matching source column.

**Column type icons:**

| Icon | Type |
| --- | --- |
| `T` | Text |
| `#` | Number |
| `⏱` | Date / Time |

Use the **Filter columns by** dropdown to show **All**, **Matched**, or **Unmatched** columns. A column search appears when the dataset has many columns or when you start typing a query. When a mapped source column has a different type from the destination column, a selector lets you choose which column type to keep.

The **Validate** button is enabled once at least one column is mapped (and, for a new dataset, once it has a name). Unmapped columns are allowed. After a successful validation, the button becomes **Submit**. When **Save results into** is **New Dataset**, **Submit** is available without validating.

#### Save results into a new dataset

By default, the combined result overwrites the destination dataset. Toggle **Save results into** to **New Dataset** to preserve both the source and destination and write the output to a new dataset instead. You can name the new dataset (up to 300 characters).

## Validation before submit

When you click **Validate**, Mammoth runs a pre-flight check to detect any views, pipelines, or tasks that depend on the destination dataset and would be affected by the operation.

If issues are found, a **Review** modal appears listing the affected items. You must confirm you understand the impact before the final submit becomes available.

## What happens after submit

The dialog closes right away and the operation runs in the background, so you don't need to wait on it. For **Select existing**, a message confirms when the source dataset will be deleted. Mammoth:

1. Appends or replaces the data rows in the destination dataset
2. If **Replace** was selected, deletes the previous batch records
3. If **Delete dataset after combining** was checked, removes the source dataset
4. Updates the **batch count** shown in the dataset preview panel
5. Reruns dependent views and pipelines. A view whose incoming link has Auto-sync off is not rerun: the new batch stays pending, and Monitor shows "new batch received, auto-sync off" with **Preview** and **Process** buttons
6. Creates an Activity Log entry recording what happened, who triggered it, and when

You can monitor progress in the **Batches** section of the dataset preview panel or in the **Activity Log**.

**Batch count after the operation:** With **Combine**, the batch count increments by one for each operation. With **Replace**, the previous batch records are removed and a single new batch appears (created suspended if all the previous batches were suspended).

## Related articles

- [Data Consolidation](https://docs.mammoth.io/learn/automations/data-consolidation/): automate combine/replace for scheduled file uploads across an automation
- [Dataset Refresh](https://docs.mammoth.io/learn/automations/dataset-refresh/): refresh a cloud-connected dataset on a schedule using the same Combine / Replace logic
- [Activity Log reference](https://docs.mammoth.io/learn/monitor/activity-log): track every batch operation with timestamps and full audit context

---
Source: https://docs.mammoth.io/learn/data-library/add-or-replace-data.md · Updated: 2026-10-13