> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.toloka.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# client.datasets.split()

> Split a dataset into parts.

Send an optional split field name in `column`, parts, and row selection. Assigns unassigned rows to named parts while keeping existing assignments. Returns the split field; poll its split status until `ready` or `failed`. To train on the result, create a slice that freezes this field.

## Signature

Method signature on `client.datasets`:

```ts theme={null}
split(args: {
  datasetId: string;
  column?: string;
  parts?: { name: string; roles: ("train" | "validate" | "test")[]; share?: undefined | number }[];
  balanceBy?: string;
  seed?: number;
  slice?: string;
  itemFilter?: Parameters<PotatoClient["datasets"]["split"]>[0]["itemFilter"];
}): Promise<DatasetField>;
```

## Parameters

**datasetId** `string` *required*

Dataset ID with prefix `ds.`.

**column** `string` (default: split)

The name of the split field. Defaults to "split". A new name creates a field; an existing split field fills unassigned rows using its saved parts and shares. An ordinary field can be adopted if its values are part names.

**parts** `\{ name: string; roles: ("train" | "validate" | "test")[]; share?: undefined | number \}[]`

Parts with names, roles, and optional shares. Shares must total 1. New split fields default to train 0.8, validate 0.1, and test 0.1; existing split fields reuse their parts and shares. A train role cannot be combined with another role. A part may have both validate and test roles, or no roles. Omit all shares to adopt existing part values without assigning rows; adoption does not accept `seed`, `balanceBy`, `slice`, or `itemFilter`.

**Fields**

**name** `string` *required*

Name stored in the split field for rows assigned to this part.

**roles** `("train" | "validate" | "test")[]` *required*

Training uses `train` parts, evaluates on `validate` parts, and excludes `test` parts from training; an empty array assigns no role.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**share** `number`

Target fraction of rows in this part, greater than 0 and at most 1; omit all shares to adopt existing assignments.

**balanceBy** `string`

Field name or ID to balance by. Rows with each label value are distributed across parts to preserve the label mix. Rare labels may be absent from some parts.

**seed** `number`

Seed for repeatable assignments. The same seed and row order produce the same assignments, including across datasets. Generated when omitted and saved with the split field.

**slice** `string`

Assign only unassigned rows in this slice. Processing waits for a slice that is still being created. Omit both `slice` and `itemFilter` to include all unassigned rows.

**itemFilter** `object`

Assign only unassigned rows matching this filter when processing starts.

**Fields**

**fieldValues** `DatasetFieldValueConditions`

Field-value conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**fieldSources** `DatasetFieldSourceConditions`

Field-author conditions that selected rows must satisfy; defaults to no conditions.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**missingRevisionFields** `string[]`

Field IDs with prefix `df.` that must have no revision on a selected row; defaults to an empty array.

## Returns

`Promise<DatasetField>`

A field of a dataset.

**id** `DatasetFieldId` *required*

Dataset field ID with prefix `df.`.

**name** `string` *required*

Name of the dataset field.

**description** `string | null` *required*

Description of the field, or null when none is set.

**jsonSchema** `JsonSchema` *required*

JSON Schema that values in this field must satisfy.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the supported JSON Schema fields.

**internal** `boolean` *required*

True when this field is excluded from pipeline input bindings. The field is still included in dataset field responses.

**split** `object | null` *required*

Set when this is a split field: each row's value names its part.

**Fields**

**parts** `object[]` *required*

The parts, with their roles: trainings learn on train parts and validate on validate parts. Test parts are held out for evaluations: no training learns on them, and only a training on this field validates on a part that has both the validate and test roles.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**recipe** `object | null` *required*

How the next fill samples parts; null for an adopted field until a fill gives it shares.

**Fields**

**shares** `object[]` *required*

Target proportion of rows for each split part.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**balanceByFieldId** `string | null` *required*

Field ID with prefix `df.` used to balance labels, or null when balancing is disabled.

**seed** `number` *required*

Seed used to make the part assignments repeatable.

**status** `"filling" | "ready" | "failed"` *required*

A slice cannot be taken while the field is filling.

**progress** `object | null` *required*

Rows placed so far while the field is filling.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed so far.

**total** `number` *required*

Number of rows to place in this fill.

**lastFill** `object | null` *required*

The last fill: rows it placed, rows that already had a part, and the rows each part held after it.

**Fields**

**placed** `number` *required*

Number of previously unassigned rows placed by the last fill.

**kept** `number` *required*

Number of rows whose existing part assignments were kept.

**parts** `object` *required*

Row counts for each part after the last fill, keyed by part name.

**error** `object | null` *required*

Why the last fill failed.

**Fields**

**code** `"too_many_labels" | "slice_failed"` *required*

Machine-readable reason the split fill failed.

**message** `string` *required*

Explanation of the split fill failure.

**operations** `DatasetFieldOperation[]` *required*

Operations currently writing to this field. A split or slice that reads the field is rejected while a blocking operation runs.

**type: "copy"**

**type** `"copy"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**sourceFieldId** `DatasetFieldId` *required*

The field the values are copied from.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "split\_fill"**

**type** `"split_fill"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**type: "write"**

**type** `"write"` *required*

Operation kind: `copy` copies field values, `split_fill` assigns split parts, and `write` writes new field revisions.

**writer** `string` *required*

The source of the new field revisions. For a batch inference run, this is `batch-inference-run:<id>`.

**progress** `object | null` *required*

The number of rows written and the total number expected, when known.

See the [HTTP endpoint](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset.md) for the complete schema.

**blocking** `boolean` *required*

True when splits and slices that read this field must wait for the operation to finish.

**createdAt** `string` *required*

Time the field was created, as an ISO 8601 timestamp.

## Errors

HTTP errors throw [`PotatoApiError`](https://docs.platform.toloka.ai/docs/sdk/errors). The endpoint documents these error responses:

| Status | Description |
| - | - |
| 400 | Unknown balancing field, failed slice, or values that are not parts |
| 404 | Dataset or slice not found |
| 409 | The field is still being filled |
| 429 | Rate limit exceeded |

HTTP endpoint: [`POST /datasets/{datasetId}/split`](https://docs.platform.toloka.ai/docs/api-reference/datasets/split-dataset).

```ts split() theme={null}
import { createClient } from "@toloka-platform/sdk";

const client = createClient({
  baseUrl: "https://platform.toloka.ai",
  apiKey: process.env.TOLOKA_API_KEY!,
});

const field = await client.datasets.split({
  datasetId: "ds.019a0000-0000-7000-8000-000000000001",
  column: "split",
  parts: [
    {
      name: "train",
      roles: [
        "train"
      ],
      share: 0.8
    },
    {
      name: "validation",
      roles: [
        "validate"
      ],
      share: 0.1
    },
    {
      name: "test",
      roles: [
        "test"
      ],
      share: 0.1
    }
  ],
  seed: 42
});
console.log(field);
```

```json split() theme={null}
{
  "id": "df.019a0000-0000-7000-8000-000000000001",
  "name": "<string>",
  "description": null,
  "jsonSchema": {},
  "internal": false,
  "split": null,
  "operations": [
    {
      "type": "copy",
      "sourceFieldId": "df.019a0000-0000-7000-8000-000000000001",
      "blocking": false
    }
  ],
  "createdAt": "2026-01-01T00:00:00Z"
}
```


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