# Dataset Splitter: CSV, XLSX, JSON by rows or column (`ucchiii/dataset-splitter`) Actor

Split an Apify dataset or a CSV/JSON/NDJSON file into parts by row count, number of parts, column value or file size, or draw a random sample. Saves CSV/JSON/NDJSON/XLSX files and datasets. Empty input = free demo. $0.10 per 1,000 rows.

- **URL**: https://apify.com/ucchiii/dataset-splitter.md
- **Developed by:** [Actor Factory](https://apify.com/ucchiii) (community)
- **Categories:** Developer tools, Automation, Integrations
- **Security:** Limited permissions
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $70.00 / 1,000 1,000 rows splits

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

**Cut a big CSV or Apify dataset into parts, by rows, column or size**

**For anyone whose file is too big for the next tool: Google Sheets stops at 10 million cells, a CRM import accepts 10,000 rows at a time, a colleague needs one file per country.** Give this Actor an Apify dataset or a CSV / TSV / JSON / NDJSON file URL, choose how to cut it, and get **one file (or dataset) per part, each with a download link**.
**$0.10 per 1,000 rows processed** (rounded up per run). Failed runs and the demo are free. No scraping, no API keys.

Sample output (150 rows split into parts of 50):

| partIndex | key | rows | bytes | downloadUrl |
|---|---|---|---|---|
| 1 | iris-part-001.csv | 50 | 1,740 | https://api.apify.com/v2/key-value-stores/…/records/iris-part-001.csv?signature=… |
| 2 | iris-part-002.csv | 50 | 1,751 | … |
| 3 | iris-part-003.csv | 50 | 1,760 | … |

**Try it free: leave input empty and press Start.** The demo splits a built-in 25-row sample CSV into parts of 10 rows (not charged, rows carry `_demo: true`).

**Price example:** a 25,000-row file costs 25 units = **$2.50**, whether you make 3 parts or 300. A 150-row file costs 1 unit = $0.10.

### What it does

- **Fixed rows per part**: for example 10,000 rows per file for CRM imports or Google Sheets
- **Fixed number of parts**: split into N files of nearly equal size
- **One part per column value**: one file per country, status or customer, with a cap on the number of parts
- **Approximate size per part**: aim for files of about 5 MB (estimated from the output format, so allow some percent of difference)
- **Random sample** instead of splitting: n rows or a percentage, with a seed so the same sample can be drawn again (rows keep their original order)
- **Output**: CSV, JSON, NDJSON or XLSX files in the key-value store, and/or one new named dataset per part
- **Reads** an Apify dataset (pick it from your runs) or a public file URL; detects the format, the delimiter and the text encoding (UTF-8, Shift_JIS, Windows-1252)
- **Keeps your data as it is**: CSV values stay exactly as in the file (a ZIP code `00123` stays `00123`); turn on `detectNumbers` if you want real numbers in XLSX or JSON. Every part repeats the header row. Text starting with `=`, `+`, `-`, `@` is stored as plain text in XLSX, never as a formula

### Input example

```json
{
  "fileUrl": "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv",
  "splitMode": "column",
  "column": "species",
  "outputFormat": "xlsx"
}
```

To split an Apify dataset use `datasetId`. Modes and their fields: `rows` (`rowsPerPart`), `parts` (`partCount`), `column` (`column`, `maxParts`), `size` (`targetSizeMb`), `sample` (`sampleRows` or `samplePercent`, `seed`).

### Output

- **Dataset**: one summary row per part with `partIndex`, `key` (file name in the key-value store), `value` (the column value, for split by column), `rows`, `bytes`, `format`, `downloadUrl` and, when datasets are written, `datasetName` and `datasetId`. In sample mode the row also has the `seed` used. A failed run has one row with `status: failed` and a plain-language `error`.
- **Key-value store**: the part files, named `<source>-part-001.csv`, `<source>-<value>.csv` or `<source>-sample.csv` (change the start with `fileName`). `downloadUrl` is Apify's signed public link, so you can share a file without sharing your token.
- **New datasets** (option `saveToDatasets`): `prefix-001`, `prefix-002`, ... The default prefix is `split-` plus the run ID, so it is always new. Named datasets stay until you delete them; the run stops before writing if one of them already has items.
- **STATS** record: input rows, parts, bytes, 1,000-row units charged, notes and the sample seed.

```json
{
  "partIndex": 1, "status": "ok", "key": "iris-part-001.csv", "value": null,
  "rows": 50, "bytes": 1740, "format": "csv",
  "downloadUrl": "https://api.apify.com/v2/key-value-stores/…/records/iris-part-001.csv?signature=…"
}
```

### Limits (cannot be raised by input)

- 2,000,000 rows and 1,000 columns per run; 500 parts per run; 200 MB per source file
- A run that would break a limit **fails before anything is written and is not charged**; rows are never silently cut. Example: 1,000,000 rows at 1,000 rows per part would need 1,000 parts, so the run asks for at least 2,000 rows per part
- XLSX parts can have at most 1,048,575 rows (Excel's limit); use CSV or smaller parts. A warning is logged when a part is bigger than the Google Sheets limit of 10,000,000 cells
- Source URLs must be public `http` or `https` links. Addresses on internal networks (localhost, private ranges, cloud metadata) are blocked, also after redirects. XLSX and zip files are not read (convert them to CSV first)
- JSON input must be an array of objects (or an object with one such array); nested values are kept as JSON text in CSV and XLSX output and as nested JSON in JSON, NDJSON and datasets
- The whole source is held in memory. Rough guide per 1 GB of run memory: about 500,000 CSV rows or 350,000 JSON rows of a dozen short columns (fewer with wide rows). The default 2 GB covers about twice that; for more rows start the run with 4 GB or more memory

### Pricing

Pay per event: **$0.10 per 1,000 rows processed** (event `rows-1000`). All rows read from the source count once, rounded up per run: 2,500 rows cost 3 units ($0.30), regardless of mode, number of parts or output format (a random sample is charged for the rows read, not for the sample size). Nothing is charged for a failed run or the demo. The charge is made after all parts are saved. Set a maximum charge per run to cap spend: if it is too low for the whole source, the run stops before splitting anything.
On the Apify Free plan, the $5 of monthly platform credit covers about **50,000 rows** a month — enough to try it on real data.

### Use cases

- Cut a 600,000-row export into files of 10,000 rows for a CRM or e-mail tool import
- Keep a spreadsheet under Google Sheets' 10 million cell limit
- One Excel file per sales region, country or account manager
- Send a reproducible 5 percent test sample of a large dataset to a colleague or a model
- Break a large scraper dataset into 5 smaller datasets that can be processed in parallel

### FAQ

**Does the order of rows stay the same?** Yes, in every mode (also in the sample). In the rows, parts and size modes the parts are consecutive blocks of the source.
**What happens to rows with an empty value in the split column?** They go to a part named `empty`.
**How exact is the size mode?** It estimates each row's size in the chosen format and fills parts up to the target. CSV, JSON and NDJSON are usually within a few percent; XLSX is compressed, so it is only a rough guide.
**Can I run it twice with the same dataset prefix?** Not if the first run left items in those datasets. Pick a new prefix or delete the old datasets.
**Does it change my source?** No. It only reads the file or dataset and writes new files.
**Is the file link private?** Anyone holding the signed link can download that file; it gives no access to anything else in your account.

If this Actor saved you time, a rating on the Store helps others find it.

### More tools from the same developer

- [Dataset Transform](https://apify.com/ucchiii/dataset-transform) — flatten, filter, rename and convert any Apify dataset, export CSV / JSON / JSONL with a link
- [Remove Duplicates](https://apify.com/ucchiii/dataset-dedup-merge) — merge Apify datasets and remove duplicates by the fields you choose
- [CSV / XLSX Converter](https://apify.com/ucchiii/csv-xlsx-converter) — convert CSV, TSV, Excel XLSX, JSON and NDJSON files or Apify datasets into each other
- [Google Sheets Export](https://apify.com/ucchiii/google-sheets-export) — export an Apify dataset to Google Sheets
- [Fuzzy Dedupe](https://apify.com/ucchiii/dataset-fuzzy-dedupe) — find near-duplicate names, addresses, phones and URLs that exact dedup misses

# Actor input Schema

## `datasetId` (type: `string`):

Dataset to split (the 'defaultDatasetId' of a finished run). You can paste a dataset URL from Apify Console too. Up to 2,000,000 rows. Use this OR a file URL. Leave both empty to run a free demo.

## `fileUrl` (type: `string`):

Public http(s) link to a CSV, TSV, JSON or NDJSON file (up to 200 MB). Links to internal networks are blocked. Use this OR an Apify dataset. Leave both empty to run a free demo on a built-in sample (not charged).

## `splitMode` (type: `string`):

How to cut the data. rows: 'Rows per part'. parts: 'Number of parts'. column: 'Column'. size: 'Target size'. sample: 'Sample rows' or 'Sample percent'. Default: rows.

## `rowsPerPart` (type: `integer`):

Mode 'rows': maximum rows in each part (the last part may be smaller). Example 10000 for CRM imports. A run makes at most 500 parts. Default when empty: 10,000.

## `partCount` (type: `integer`):

Mode 'parts': how many parts of nearly equal size to make (up to 500). With fewer rows than parts you get one row per part. Default when empty: 2.

## `column` (type: `string`):

Mode 'column': name of the column whose values define the parts (matched case-insensitively if needed). Rows with an empty value go to a part named 'empty'. For dataset items only top-level fields are columns.

## `maxParts` (type: `integer`):

Mode 'column': if the column has more different values than this, the run fails before anything is written or charged. Hard limit 500. Default: 500.

## `targetSizeMb` (type: `number`):

Mode 'size': approximate size of each part in MB, estimated from the output format (XLSX is estimated at about 40% of the CSV size). Real files can differ by some percent. Default: 5.

## `sampleRows` (type: `integer`):

Mode 'sample': number of rows to draw at random. Takes precedence over 'Sample percent'. Rows keep their original order.

## `samplePercent` (type: `number`):

Mode 'sample': share of rows to draw, for example 10 for 10 percent (at least one row). Used when 'Sample rows' is empty.

## `seed` (type: `integer`):

Mode 'sample': the same seed and the same data always give the same sample. Empty = a random seed, which is reported in the output (field seed) so you can repeat the sample.

## `outputFormat` (type: `string`):

Format of the part files saved to the key-value store. Default: csv.

## `saveToKeyValueStore` (type: `boolean`):

Save every part as a file in the key-value store, with a public download link. Turn off to write only datasets. Default: on.

## `saveToDatasets` (type: `boolean`):

Write every part into its own new named dataset (prefix-001, prefix-002, ...). Named datasets stay until you delete them. The run fails before writing if one of them already has items. Default: off.

## `datasetNamePrefix` (type: `string`):

Prefix for the new datasets: lowercase letters, digits and dashes (max 40). Empty = 'split-' plus the run ID, which is always new.

## `inputFormat` (type: `string`):

Format of the source file. 'auto' uses the file extension, the content type and the content. Ignored for Apify datasets. Default: auto.

## `encoding` (type: `string`):

Character encoding of the source file. Output is always UTF-8. Default: auto (UTF-8, then Shift_JIS if kana are found, then Windows-1252).

## `detectNumbers` (type: `boolean`):

Turn plain numbers in a CSV into real numbers (useful for XLSX and JSON output). Values with leading zeros, more than 15 digits or exponents stay text. Default: off, values are kept exactly as in the file.

## `csvBom` (type: `boolean`):

Add a byte-order mark to CSV parts so Excel opens non-English text (for example Japanese) correctly. Leave off for databases and most code.

## `fileName` (type: `string`):

Start of every part file name, for example 'leads' gives leads-part-001.csv. Only letters, digits, dot, dash and underscore are kept. Empty = taken from the source.

## Actor input object example

```json
{
  "fileUrl": "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv",
  "splitMode": "rows",
  "rowsPerPart": 50,
  "maxParts": 500,
  "targetSizeMb": 5,
  "outputFormat": "csv",
  "saveToKeyValueStore": true,
  "saveToDatasets": false,
  "inputFormat": "auto",
  "encoding": "auto",
  "detectNumbers": false,
  "csvBom": false
}
```

# Actor output Schema

## `parts` (type: `string`):

One row per part: partIndex, key (file name) or value (for split by column), rows, bytes and the public downloadUrl. Download as CSV, JSON, Excel and more.

## `stats` (type: `string`):

Record STATS: input rows, parts, bytes, 1,000-row units charged, notes and the sample seed.

## `files` (type: `string`):

The key-value store that holds the part files.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "fileUrl": "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv",
    "rowsPerPart": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("ucchiii/dataset-splitter").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "fileUrl": "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv",
    "rowsPerPart": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("ucchiii/dataset-splitter").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "fileUrl": "https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv",
  "rowsPerPart": 50
}' |
apify call ucchiii/dataset-splitter --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ucchiii/dataset-splitter"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ebYyfw4gsapU8sSqo/builds/MJ5RCXDWUFEkf5oCr/openapi.json