> ## Documentation Index
> Fetch the complete documentation index at: https://help.csvbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Split Large CSV

> Automatically split large CSV files into smaller parts for faster, more reliable imports with improved browser performance.

Uploading very large CSV files can cause browser slowdowns, high memory usage, or upload timeouts, especially when files contain thousands of rows. The **Split Large Files** feature solves this by automatically dividing large CSV files into smaller parts and processing them sequentially behind the scenes.

Each part:

* Preserves the original headers and column structure
* Reuses the same column mappings automatically
* Is processed independently for improved reliability
* Remains grouped under a single parent import for easier tracking

This makes large imports significantly more stable and easier to manage.

## When does file splitting activate?

File splitting activates only when **all** of the following conditions are met:

* The uploaded file is a **CSV** file (`.xlsx` Excel files are not currently supported).
* **Split Large Files** is enabled for the sheet.
* The uploaded file exceeds the configured **Rows per Import** limit.

## Admin configuration

Enable the feature per sheet from **Sheet Settings** → **Import Steps**.

### Split Large Files

| Setting | Options | Default |
| - | - | - |
| Split Large Files | Yes / No | No |

Enable this setting to automatically split large CSV uploads into smaller parts.

When disabled, the entire CSV file is processed as a single upload.

### Rows per Import

| Setting | Type | Default |
| - | - | - |
| Rows per Import | Number | 1000 |

Defines the maximum number of rows processed in each part.

#### Example

If a CSV contains **4,500 rows** and the limit is set to **1,000 rows**, CSVbox processes the file in:

* Part 1 → Rows 1–1000
* Part 2 → Rows 1001–2000
* Part 3 → Rows 2001–3000
* Part 4 → Rows 3001–4000
* Part 5 → Rows 4001–4500

#### Choosing the right value

| Smaller parts | Larger parts |
| - | - |
| Faster processing per upload | Fewer total parts |
| Lower browser memory usage | Higher memory usage |
| Better reliability for large datasets | Faster overall completion for moderate files |

<Tip>
  For most use cases, **1,000–5,000 rows per part** works well.
</Tip>

### User Confirmation between parts

| Setting | Options | Default |
| - | - | - |
| User Confirmation | No / Yes / No, only if there are no errors | No |

Controls whether users must manually continue between parts.

#### Available modes

| Mode | Behavior |
| - | - |
| No | All parts upload automatically |
| Yes | User must confirm before each next part uploads |
| No, only if there are no errors | Upload continues automatically unless a part contains validation errors |

For the smoothest experience, use **No**.

## End user experience

<Steps>
  <Step title="Upload a CSV file">
    The user uploads a CSV file normally through the importer.

    If the file exceeds the configured row limit, CSVbox automatically prepares the file for multipart processing.
  </Step>

  <Step title="Review the split notification">
    Before processing begins, the user sees a notification such as:

    > **Large file detected**
    >
    > We'll split this file into smaller parts (X rows each) for smoother processing. Each part will be uploaded automatically, and your column mappings will be reused.

    The user can then:

    * **Start Upload**: continue processing.
    * **Cancel**: cancel the upload.
  </Step>

  <Step title="Map columns (first part only)">
    The first part behaves exactly like a normal CSVbox import. The user:

    * Maps columns
    * Reviews data
    * Fixes validation issues if needed
    * Submits the import

    CSVbox automatically reuses the same mappings for all remaining parts. The user does **not** need to map columns again.
  </Step>

  <Step title="Let the remaining parts process automatically">
    After the first part is submitted, remaining parts are processed automatically. A progress indicator shows overall upload progress, for example:

    ```text theme={null}
    Processing (2/5)

    2,000 / 5,000 rows processed
    ```

    Depending on the confirmation mode, the user may or may not be prompted between parts.
  </Step>

  <Step title="Complete the import">
    Once all parts finish processing:

    * The multipart upload is marked as completed.
    * All parts remain grouped under a single parent import.
    * Users can review part-level details if needed.
  </Step>
</Steps>

## Viewing multipart imports

Multipart uploads appear as a single grouped import on the **All Imports** page.

CSVbox automatically tracks:

* Overall import status
* Number of processed parts
* Row counts
* Failed or partial parts

### Multipart import statuses

| Status | Meaning |
| - | - |
| Success | All parts processed successfully |
| Processing | Upload is still running |
| Partial Failure | Some parts failed |
| Failed | Entire upload failed |

### Viewing part details

Opening the import details shows information for each individual part.

| Column | Description |
| - | - |
| Part | Part sequence number |
| Status | Success / Failed / Processing |
| Rows | Rows processed in that part |
| Import ID | Individual import reference |
| Errors | Validation or processing errors |

## Import limits and billing

Multipart uploads count as **a single import** toward your plan limits. For example:

* A 10-part upload = **1 import**
* A 50-part upload = **1 import**

Individual parts are not counted separately.

## Reliability and error handling

Each part is processed independently for improved stability. This means:

* A failure in one part doesn't invalidate already completed parts.
* Failed parts can be retried individually.
* Successfully processed parts remain intact.

### If a part fails

If a part encounters validation errors or processing failures:

* The multipart upload is marked as **Partial Failure**.
* Error details are available for the failed part.
* Successfully processed parts remain unaffected.

### If the browser is closed mid-upload

If the browser closes before processing completes:

* Completed parts remain saved.
* Remaining parts stop processing.
* The upload status reflects the completed progress.

<Warning>
  Keep the browser open until the upload finishes.
</Warning>

## Limitations

### Excel files are not supported

Currently, multipart processing supports **CSV files only**. Excel (`.xlsx`) files are processed as a single upload regardless of size.

If needed, convert Excel files to CSV before uploading.

### Maximum parts per upload

To ensure reliable processing, a single upload can generate up to **100 parts**. If splitting the file at the configured row limit would produce more than 100 parts, the upload stops with an error message.

In this case, either:

* Increase the **Rows per Import** value, or
* Split the source CSV manually before uploading.

## Best practices

For optimal performance:

* Use CSV files instead of Excel for very large datasets.
* Keep row limits between **1,000–5,000**.
* Enable automatic uploads when possible.
* Use smaller part sizes for slower devices or lower-memory environments.

## FAQ

### Do all parts use the same column mapping?

Yes. Once the first part is mapped, CSVbox automatically reuses the same mapping for all remaining parts.

### Are parts sent separately to destinations?

Yes. Each part is processed independently and sent separately to the configured destination.

### Can users retry failed parts?

Yes. Failed parts can be retried individually without re-uploading the full file.

### Can I disable this feature for specific users?

No. The feature is configured per sheet, not per user.

If different users require different behavior, create separate sheets with different settings.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.