Split a dataset into parts

TypeScript SDK

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);

import requests

url = "https://platform.toloka.ai/api/v2-beta/datasets/{datasetId}/split"

payload = {}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "id": "<string>",
  "internal": true,
  "jsonSchema": {
    "additionalProperties": true,
    "allOf": [
      "<unknown>"
    ],
    "anyOf": [
      "<unknown>"
    ],
    "const": "<string>",
    "default": "<string>",
    "description": "<string>",
    "enum": [
      "<string>"
    ],
    "examples": [
      "<string>"
    ],
    "exclusiveMaximum": 123,
    "exclusiveMinimum": 123,
    "format": "<string>",
    "items": "<unknown>",
    "maxItems": 4503599627370495,
    "maxLength": 4503599627370495,
    "maximum": 123,
    "minItems": 4503599627370495,
    "minLength": 4503599627370495,
    "minimum": 123,
    "oneOf": [
      "<unknown>"
    ],
    "pattern": "<string>",
    "properties": {},
    "required": [
      "<string>"
    ],
    "title": "<string>",
    "type": "string",
    "uniqueItems": true
  },
  "name": "<string>",
  "operations": [
    {
      "blocking": true,
      "sourceFieldId": "<string>",
      "type": "copy"
    }
  ],
  "split": {
    "error": {
      "code": "too_many_labels",
      "message": "<string>"
    },
    "lastFill": {
      "kept": 4503599627370495,
      "parts": {},
      "placed": 4503599627370495
    },
    "parts": [
      {
        "name": "<string>",
        "roles": [
          "train"
        ]
      }
    ],
    "progress": {
      "placed": 4503599627370495,
      "total": 4503599627370495
    },
    "recipe": {
      "balanceByFieldId": "<string>",
      "seed": 1073741823,
      "shares": [
        {
          "name": "<string>",
          "share": 123
        }
      ]
    },
    "status": "filling"
  }
}

POST

datasets

{datasetId}

split

TypeScript SDK

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);

import requests

url = "https://platform.toloka.ai/api/v2-beta/datasets/{datasetId}/split"

payload = {}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "id": "<string>",
  "internal": true,
  "jsonSchema": {
    "additionalProperties": true,
    "allOf": [
      "<unknown>"
    ],
    "anyOf": [
      "<unknown>"
    ],
    "const": "<string>",
    "default": "<string>",
    "description": "<string>",
    "enum": [
      "<string>"
    ],
    "examples": [
      "<string>"
    ],
    "exclusiveMaximum": 123,
    "exclusiveMinimum": 123,
    "format": "<string>",
    "items": "<unknown>",
    "maxItems": 4503599627370495,
    "maxLength": 4503599627370495,
    "maximum": 123,
    "minItems": 4503599627370495,
    "minLength": 4503599627370495,
    "minimum": 123,
    "oneOf": [
      "<unknown>"
    ],
    "pattern": "<string>",
    "properties": {},
    "required": [
      "<string>"
    ],
    "title": "<string>",
    "type": "string",
    "uniqueItems": true
  },
  "name": "<string>",
  "operations": [
    {
      "blocking": true,
      "sourceFieldId": "<string>",
      "type": "copy"
    }
  ],
  "split": {
    "error": {
      "code": "too_many_labels",
      "message": "<string>"
    },
    "lastFill": {
      "kept": 4503599627370495,
      "parts": {},
      "placed": 4503599627370495
    },
    "parts": [
      {
        "name": "<string>",
        "roles": [
          "train"
        ]
      }
    ],
    "progress": {
      "placed": 4503599627370495,
      "total": 4503599627370495
    },
    "recipe": {
      "balanceByFieldId": "<string>",
      "seed": 1073741823,
      "shares": [
        {
          "name": "<string>",
          "share": 123
        }
      ]
    },
    "status": "filling"
  }
}

Authorizations

Authorization

string

header

required

Enter ApiKey <your-api-key> in Authorization, including the ApiKey prefix. In cURL and Python samples, <api-key> means this full value. The TypeScript SDK adds the prefix for you.

Path Parameters

datasetId

string

required

Dataset ID with prefix ds..

Pattern: ^ds\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Body

application/json

Assign unassigned rows to split parts using their shares. Existing assignments are retained and count toward the target proportions.

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.

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.

Required string length: 1 - 128

Pattern: ^[a-z]([a-z0-9_]*[a-z0-9])?$

itemFilter

object

Assign only unassigned rows matching this filter when processing starts.

Show child attributes

parts

object[]

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.

Required array length: 1 - 10 elements

Show child attributes

seed

integer

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.

Required range: 0 <= x <= 2147483647

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.

Pattern: ^dsl\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response

The split field, filling or ready

A field of a dataset.

createdAt

string<date-time>

required

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

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

description

string | null

required

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

string

required

Dataset field ID with prefix df..

Pattern: ^df\.[0-9a-f]{8}-[0-9a-f]{4}-[7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

internal

boolean

required

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

jsonSchema

object

required

JSON Schema that values in this field must satisfy.

Show child attributes

name

string

required

Name of the dataset field.

operations

object[]

required

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

A background operation writing into a dataset field.

Option 1
Option 2
Option 3

Show child attributes

split

object | null

required

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

Show child attributes

Reference

TypeScript SDK

CLI

HTTP API

Authorizations

Path Parameters

Body

Response