@toloka-platform/sdk 0.11.4 → 0.12.1

package/src/cli/data.ts

@@ -92,6 +92,7 @@ export type LoadDatasetOptions = {
   readonly datasetName: string;
   readonly outPath: string;
   readonly projectId?: string;
+  readonly fields?: readonly string[];
   readonly limit?: number;
   readonly timeoutMs?: number;
   readonly fetch?: typeof globalThis.fetch;
@@ -106,7 +107,7 @@ type DatasetRef = {
 const isJsonObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === "object" && value !== null && !Array.isArray(value);
 
-const summarizeJsonSchema = (schema: unknown): string => {
+export const summarizeJsonSchema = (schema: unknown): string => {
   if (!isJsonObject(schema)) return "unknown";
   if (Array.isArray(schema.anyOf)) {
     const variants = [...new Set(schema.anyOf.map(summarizeJsonSchema))];
@@ -156,6 +157,13 @@ const declaredDatasetFields = async (options: {
 
 const formatDatasetChoice = (dataset: Dataset): string => `${dataset.name} (${dataset.id})`;
 
+const MAX_LISTED_NAMES = 10;
+
+export const listedNames = (names: readonly string[]): string =>
+  names.length <= MAX_LISTED_NAMES
+    ? names.join(", ")
+    : `${names.slice(0, MAX_LISTED_NAMES).join(", ")} and ${names.length - MAX_LISTED_NAMES} more`;
+
 const collectLiveDatasets = async (client: PotatoClient, projectId: string): Promise<Dataset[]> => {
   const datasets: Dataset[] = [];
   for await (const dataset of client.datasets.listAll({ projectId })) datasets.push(dataset);
@@ -165,7 +173,7 @@ const collectLiveDatasets = async (client: PotatoClient, projectId: string): Pro
   });
 };
 
-const resolveLiveDataset = async (
+export const resolveLiveDataset = async (
   client: PotatoClient,
   options: GenerateDatasetFieldDeclarationsOptions & { readonly source?: ProjectSource },
   createWhenMissing: boolean,
@@ -210,8 +218,10 @@ const resolveLiveDataset = async (
     createWhenMissing && datasetId === undefined,
     live.length === 0
       ? `Dataset "${token}" does not exist in project ${projectId}. Run toloka dataset create ${JSON.stringify(token)} first, or toloka apply for a dataset a pipeline declares.`
-      : `Dataset "${token}" does not exist in project ${projectId}. This project has: ${live.map(formatDatasetChoice).join(", ")}.`,
-    { hint: { disabled: true } },
+      : `Dataset "${token}" does not exist in project ${projectId}. This project has: ${listedNames(live.map(formatDatasetChoice))}.`,
+    live.length <= MAX_LISTED_NAMES
+      ? { hint: { disabled: true } }
+      : { hint: { description: "Run toloka dataset list to see every dataset of the project." } },
   );
 
   assertCli(
@@ -440,22 +450,35 @@ export async function uploadDataset(
   const uploadedOutput = `Uploaded ${completed.result.itemsIngested} rows to dataset ${resolved.name}.`;
   let inferredFields: ReadonlyArray<InferredField> = [];
   let inferenceReport: string | undefined;
-  let warning: string | undefined;
+  const warnings: string[] = [];
   try {
     const inferred = await client.datasets.getInferredFields({ datasetId });
     inferredFields = inferred.fields;
     inferenceReport = formatInferredFields(inferredFields);
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
-    warning = `Upload succeeded, but inferred fields could not be fetched: ${reason}`;
+    warnings.push(`Upload succeeded, but inferred fields could not be fetched: ${reason}`);
+  }
+  if (fields.length > 0) {
+    try {
+      await client.waitFor({ type: "datasetFields", datasetId }, options.waitFor);
+    } catch (error) {
+      if (!(error instanceof PotatoApiError && error.code === "wait_timeout")) throw error;
+      warnings.push(
+        `Upload succeeded, but its rows are still being copied into the dataset fields; check them with toloka dataset columns ${fieldsHint} --json.`,
+      );
+    }
   }
+  const addFieldsHint =
+    fields.length === 0 && inferredFields.some((field) => field.depth === 1)
+      ? `To filter, balance or split by these fields, add them as dataset fields: toloka dataset fields add ${fieldsHint} <field>… (or --all).`
+      : undefined;
   return {
     datasetId,
     rowsUploaded: completed.result.itemsIngested,
     inferredFields,
-    output:
-      inferenceReport === undefined ? uploadedOutput : `${uploadedOutput}\n${inferenceReport}`,
-    ...(warning === undefined ? {} : { warning }),
+    output: [uploadedOutput, inferenceReport, addFieldsHint].filter((line) => line !== undefined).join("\n"),
+    ...(warnings.length === 0 ? {} : { warning: warnings.join("\n") }),
   };
 }
 
@@ -539,16 +562,19 @@ export async function loadDataset(
   options: LoadDatasetOptions,
 ): Promise<DatasetCommandResult> {
   const resolved = await resolveLiveDataset(client, options, false);
-  const fieldNames: string[] = [];
+  const datasetRef = resolved.nameIsUnique ? resolved.name : resolved.datasetId;
+  const visibleFields: string[] = [];
   for await (const field of client.datasets.listAllFields({ datasetId: resolved.datasetId })) {
-    if (field.internal || field.name === RAW_UPLOAD_FIELD_NAME) continue;
-    fieldNames.push(field.name);
+    if (!field.internal) visibleFields.push(field.name);
   }
-  assertCli(
-    fieldNames.length > 0,
-    `Dataset ${resolved.name} has no fields to export.`,
-    { hint: { description: "Upload rows first with toloka dataset upload <name> <file>." } },
-  );
+  assertCli(visibleFields.length > 0, `Dataset ${resolved.name} has no rows yet.`, {
+    hint: { description: `Upload rows with toloka dataset upload ${datasetRef} <file>.` },
+  });
+  const unknown = (options.fields ?? []).filter((name) => !visibleFields.includes(name));
+  assertCli(unknown.length === 0, `Dataset ${resolved.name} has no field ${unknown.join(", ")}.`, {
+    hint: { description: `Its fields are ${listedNames(visibleFields)}.` },
+  });
+  const fieldNames = options.fields === undefined ? visibleFields : [...options.fields];
 
   const started = await client.datasets.startExport({
     datasetId: resolved.datasetId,
@@ -587,7 +613,9 @@ export async function loadDataset(
     options.outPath,
     limited.length === 0 ? "" : `${limited.map((row) => JSON.stringify(row)).join("\n")}\n`,
   );
-  return { output: `Wrote ${limited.length} rows to ${options.outPath}.` };
+  return {
+    output: `Wrote ${limited.length} rows with the fields ${listedNames(fieldNames)} to ${options.outPath}.`,
+  };
 }
 
 export async function setProjectSecret(

package/src/cli/fields.ts

@@ -0,0 +1,80 @@
+import type { DatasetField, PotatoClient } from "../client";
+import type { WaitForOptions } from "../wait-for";
+import { assertCli } from "./cli-error";
+import { listedNames, resolveLiveDataset, summarizeJsonSchema } from "./data";
+import { waitForFilledFields } from "./slices";
+import { formatTable } from "./table";
+import { uploadedRowFieldNames } from "./uploaded-fields";
+
+export type AddDatasetFieldsOptions = {
+  readonly sourceRoot: string;
+  readonly datasetName: string;
+  readonly projectId?: string;
+  readonly fields: readonly string[];
+  readonly all: boolean;
+  readonly wait: boolean;
+  readonly waitFor?: WaitForOptions;
+  readonly json: boolean;
+};
+
+const FIELDS_HINT = {
+  description: "Name fields of the uploaded rows, for example label split, or pass --all; toloka dataset upload prints them.",
+};
+
+const FIELD_NAME = /^[a-z]([a-z0-9_]{0,126}[a-z0-9])?$/u;
+
+const FIELD_NAME_RULE =
+  "a dataset field name takes lowercase letters, numbers and underscores, starts with a letter, ends with a letter or number, and has at most 128 characters";
+
+export async function addDatasetFields(
+  client: PotatoClient,
+  options: AddDatasetFieldsOptions,
+): Promise<{ readonly output: string }> {
+  assertCli(!(options.all && options.fields.length > 0), "Name the fields or pass --all, not both.", { hint: FIELDS_HINT });
+  assertCli(options.all || options.fields.length > 0, "Name the fields of the uploaded rows to add, or pass --all.", {
+    hint: FIELDS_HINT,
+  });
+  const dataset = await resolveLiveDataset(client, options, false);
+  const datasetRef = dataset.nameIsUnique ? dataset.name : dataset.datasetId;
+  const existing = new Set<string>();
+  for await (const field of client.datasets.listAllFields({ datasetId: dataset.datasetId })) existing.add(field.name);
+  const candidates = options.all
+    ? (await uploadedRowFieldNames(client, dataset.datasetId)).filter((name) => !existing.has(name))
+    : [...options.fields];
+  const unnamable = candidates.filter((name) => !FIELD_NAME.test(name));
+  assertCli(options.all || unnamable.length === 0, `${unnamable.join(", ")} cannot be a dataset field name: ${FIELD_NAME_RULE}.`, {
+    hint: { description: "Rename the field in the file before uploading it, or pick fields with names a dataset field can take." },
+  });
+  const names = candidates.filter((name) => FIELD_NAME.test(name));
+  const skipped = unnamable.length === 0 ? [] : [`Skipped ${listedNames(unnamable)}: ${FIELD_NAME_RULE}.`];
+
+  if (names.length === 0) {
+    return {
+      output: [`Every field of the rows uploaded to ${dataset.name} that can be a dataset field is one already.`, ...skipped].join(
+        "\n",
+      ),
+    };
+  }
+
+  const created = await client.datasets.createFieldsFromUploadedRows({ datasetId: dataset.datasetId, names });
+  const fields: DatasetField[] = options.wait
+    ? (await waitForFilledFields(client, { datasetId: dataset.datasetId, names, waitFor: options.waitFor })).filter(
+        (field) => names.includes(field.name),
+      )
+    : created;
+
+  if (options.json) return { output: JSON.stringify(fields, null, 2) };
+
+  return {
+    output: [
+      formatTable([
+        ["FIELD", "ID", "TYPE"],
+        ...fields.map((field) => [field.name, field.id, summarizeJsonSchema(field.jsonSchema)]),
+      ]),
+      options.wait
+        ? `Copied the values of ${listedNames(names)} from the uploaded rows; later uploads fill them too.`
+        : `Copying the values of ${listedNames(names)} from the uploaded rows; check with toloka dataset columns ${datasetRef} --json.`,
+      ...skipped,
+    ].join("\n"),
+  };
+}

package/src/cli/filters.ts

@@ -0,0 +1,73 @@
+import type { PotatoClient } from "../client";
+import { assertCli, REPORT_HINT } from "./cli-error";
+import { uploadedFieldHint } from "./uploaded-fields";
+
+export type FieldValueFilter = {
+  fieldValues: {
+    fieldId: string;
+    jsonPath: string;
+    operator: "text_eq";
+    value: string | number | boolean | null;
+    latestOnly: boolean;
+    sources: never[];
+  }[];
+  fieldSources: never[];
+  missingRevisionFields: never[];
+};
+
+const parseFilterValue = (raw: string): string | number | boolean | null => {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null") return null;
+  const numeric = Number(raw);
+  return raw.trim() !== "" && Number.isFinite(numeric) ? numeric : raw;
+};
+
+const splitFilter = (filter: string): { fieldName: string; rawValue: string } => {
+  const separator = filter.indexOf("=");
+  assertCli(separator > 0 && separator < filter.length - 1, "Dataset filters must use FIELD=VALUE syntax.", {
+    hint: { description: "Write the filter as field=value, for example split=train." },
+  });
+  return { fieldName: filter.slice(0, separator), rawValue: filter.slice(separator + 1) };
+};
+
+export const resolveFieldValueFilters = async (
+  client: Pick<PotatoClient, "datasets">,
+  dataset: { readonly datasetId: string; readonly name: string; readonly nameIsUnique: boolean },
+  filters: readonly string[],
+): Promise<FieldValueFilter> => {
+  const { datasetId } = dataset;
+  const datasetRef = dataset.nameIsUnique ? dataset.name : datasetId;
+  const parsed = filters.map(splitFilter);
+  const fieldIdsByName = new Map<string, string[]>();
+  for await (const field of client.datasets.listAllFields({ datasetId })) {
+    fieldIdsByName.set(field.name, [...(fieldIdsByName.get(field.name) ?? []), field.id]);
+  }
+  const unresolved = parsed.find(({ fieldName }) => fieldIdsByName.get(fieldName)?.length !== 1)?.fieldName;
+  const uploadedHint =
+    unresolved === undefined || fieldIdsByName.has(unresolved)
+      ? undefined
+      : await uploadedFieldHint(client, { datasetId, datasetRef, name: unresolved });
+  assertCli(unresolved === undefined, `Dataset field ${unresolved} was not found or is ambiguous.`, {
+    hint: uploadedHint ?? { description: `Run toloka dataset columns ${datasetRef} to see the column names.` },
+  });
+  const fieldValues = parsed.map(({ fieldName, rawValue }) => {
+    const [fieldId] = fieldIdsByName.get(fieldName) ?? [];
+    assertCli(fieldId, `Dataset field ${fieldName} has no resolved ID.`, { hint: REPORT_HINT });
+    const filter: FieldValueFilter["fieldValues"][number] = {
+      fieldId,
+      jsonPath: "$",
+      operator: "text_eq",
+      value: parseFilterValue(rawValue),
+      latestOnly: true,
+      sources: [],
+    };
+    return filter;
+  });
+  assertCli(
+    new Set(fieldValues.map((filter) => filter.fieldId)).size === fieldValues.length,
+    "Each field can be filtered once.",
+    { hint: { description: "Pass one --filter per field." } },
+  );
+  return { fieldValues, fieldSources: [], missingRevisionFields: [] };
+};

package/src/cli/slices.ts

@@ -0,0 +1,161 @@
+import type { DatasetField, DatasetSlice, PotatoClient } from "../client";
+import { PotatoApiError } from "../errors";
+import type { WaitForOptions } from "../wait-for";
+import { assertCli } from "./cli-error";
+import { resolveLiveDataset } from "./data";
+import { resolveFieldValueFilters } from "./filters";
+import { formatTable } from "./table";
+
+type SliceApi = Pick<PotatoClient, "datasets" | "waitFor">;
+
+export type DatasetSliceCommandResult = { readonly output: string };
+
+export type CreateDatasetSliceOptions = {
+  readonly sourceRoot: string;
+  readonly datasetName: string;
+  readonly projectId?: string;
+  readonly name?: string;
+  readonly filters?: readonly string[];
+  readonly from?: string;
+  readonly freeze?: readonly string[];
+  readonly wait: boolean;
+  readonly waitFor?: WaitForOptions;
+  readonly json: boolean;
+};
+
+export const formatCount = (value: number): string => value.toLocaleString("en-US");
+
+export const fieldNamesOf = async (
+  client: Pick<PotatoClient, "datasets">,
+  datasetId: string,
+): Promise<ReadonlyMap<string, string>> => {
+  const names = new Map<string, string>();
+  for await (const field of client.datasets.listAllFields({ datasetId })) names.set(field.id, field.name);
+  return names;
+};
+
+const describeFilter = (slice: DatasetSlice, fieldNames: ReadonlyMap<string, string>): string => {
+  if (slice.itemFilter === null) return "every row";
+  const { fieldValues = [], fieldSources = [], missingRevisionFields = [] } = slice.itemFilter;
+  return [
+    ...fieldValues.map((filter) => `${fieldNames.get(filter.fieldId) ?? filter.fieldId} = ${JSON.stringify(filter.value)}`),
+    ...fieldSources.map((filter) => `${fieldNames.get(filter.fieldId) ?? filter.fieldId} written by given sources`),
+    ...missingRevisionFields.map((fieldId) => `${fieldNames.get(fieldId) ?? fieldId} is empty`),
+  ].join(", ");
+};
+
+export const formatSlice = (slice: DatasetSlice, fieldNames: ReadonlyMap<string, string>): string => {
+  const rows: string[][] = [
+    ["Slice", slice.id],
+    ["Name", slice.name],
+    ["Dataset", slice.datasetId],
+    ["Status", slice.status],
+    ["Rows", formatCount(slice.rows)],
+    ["Rows matching", describeFilter(slice, fieldNames)],
+    ["Frozen", slice.frozenFieldIds.map((fieldId) => fieldNames.get(fieldId) ?? fieldId).join(", ") || "-"],
+  ];
+  if (slice.fromSliceId !== null) rows.push(["Taken from", slice.fromSliceId]);
+  if (slice.error !== null) rows.push(["Error", `${slice.error.code}: ${slice.error.message}`]);
+  rows.push(["Frozen at", slice.cutoff], ["Created", slice.createdAt]);
+  return formatTable(rows);
+};
+
+export const waitUntilDone = async <Resource>(
+  wait: () => Promise<Resource>,
+  { what, checkCommand }: { readonly what: string; readonly checkCommand: string },
+): Promise<Resource> => {
+  try {
+    return await wait();
+  } catch (error) {
+    assertCli(
+      !(error instanceof PotatoApiError && error.code === "wait_timeout"),
+      `Stopped waiting for ${what}; it keeps running. Check it with toloka ${checkCommand}.`,
+      { hint: { disabled: true } },
+    );
+    throw error;
+  }
+};
+
+export const waitForFilledFields = (
+  client: Pick<PotatoClient, "waitFor">,
+  {
+    datasetId,
+    names,
+    waitFor,
+  }: { readonly datasetId: string; readonly names?: readonly string[]; readonly waitFor?: WaitForOptions },
+): Promise<DatasetField[]> =>
+  waitUntilDone(
+    () => client.waitFor({ type: "datasetFields", datasetId, ...(names === undefined ? {} : { names }) }, waitFor ?? {}),
+    { what: `the fields of dataset ${datasetId} to finish filling`, checkCommand: `dataset columns ${datasetId} --json` },
+  );
+
+const render = async (client: SliceApi, slice: DatasetSlice, json: boolean): Promise<DatasetSliceCommandResult> => ({
+  output: json ? JSON.stringify(slice, null, 2) : formatSlice(slice, await fieldNamesOf(client, slice.datasetId)),
+});
+
+export async function createDatasetSlice(
+  client: PotatoClient,
+  options: CreateDatasetSliceOptions,
+): Promise<DatasetSliceCommandResult> {
+  assertCli(
+    options.from === undefined || options.filters === undefined,
+    "--from takes the source slice again with its own filter, so it takes no --filter.",
+    { hint: { description: "Pass either --from <slice> or --filter field=value." } },
+  );
+  const dataset = await resolveLiveDataset(client, options, false);
+  const frozenColumns = options.freeze && [...options.freeze];
+  if (options.wait) await waitForFilledFields(client, { datasetId: dataset.datasetId, waitFor: options.waitFor });
+  const created = await client.datasets.createSlice(
+    options.from === undefined
+      ? {
+          datasetId: dataset.datasetId,
+          name: options.name,
+          ...(options.filters === undefined
+            ? {}
+            : { itemFilter: await resolveFieldValueFilters(client, dataset, options.filters) }),
+          frozenColumns,
+        }
+      : { datasetId: dataset.datasetId, name: options.name, fromSlice: options.from, frozenColumns },
+  );
+  const slice = options.wait
+    ? await waitUntilDone(
+        () => client.waitFor({ type: "datasetSlice", sliceId: created.id }, options.waitFor ?? {}),
+        { what: `slice ${created.id}`, checkCommand: `dataset slice show ${created.id}` },
+      )
+    : created;
+  assertCli(slice.status !== "failed", `Slice ${slice.id} failed: ${slice.error?.message ?? "no reason given"}`, {
+    hint: { description: `Check it with toloka dataset slice show ${slice.id}.` },
+  });
+  return render(client, slice, options.json);
+}
+
+export async function listDatasetSlices(
+  client: PotatoClient,
+  options: { readonly sourceRoot: string; readonly datasetName: string; readonly projectId?: string },
+): Promise<DatasetSliceCommandResult> {
+  const dataset = await resolveLiveDataset(client, options, false);
+  const page = await client.datasets.listSlicesPage({ datasetId: dataset.datasetId, limit: 100 });
+  if (page.slices.length === 0) {
+    return { output: `Dataset ${dataset.name} has no slices. Create one with toloka dataset slice create ${dataset.datasetId}.` };
+  }
+  return {
+    output: formatTable([
+      ["SLICE", "NAME", "STATUS", "ROWS", "TAKEN FROM", "CREATED"],
+      ...page.slices.map((slice) => [
+        slice.id,
+        slice.name,
+        slice.status,
+        formatCount(slice.rows),
+        slice.fromSliceId ?? "-",
+        slice.createdAt,
+      ]),
+    ]),
+  };
+}
+
+export async function showDatasetSlice(
+  client: PotatoClient,
+  options: { readonly sliceId: string; readonly json: boolean },
+): Promise<DatasetSliceCommandResult> {
+  return render(client, await client.datasets.getSlice({ sliceId: options.sliceId }), options.json);
+}

package/src/cli/splits.ts

@@ -0,0 +1,223 @@
+import type { DatasetField, PotatoClient } from "../client";
+import type { WaitForOptions } from "../wait-for";
+import { assertCli } from "./cli-error";
+import type { SplitPartSpec } from "./context";
+import { resolveLiveDataset } from "./data";
+import { resolveFieldValueFilters } from "./filters";
+import { fieldNamesOf, formatCount, waitForFilledFields, waitUntilDone } from "./slices";
+import { formatTable } from "./table";
+import { uploadedFieldHint } from "./uploaded-fields";
+
+type SplitApi = Pick<PotatoClient, "datasets" | "waitFor">;
+
+export type SplitRatios = { readonly train: number; readonly validate: number; readonly test: number };
+
+export type DatasetSplitCommandResult = { readonly output: string };
+
+export type SplitDatasetOptions = {
+  readonly sourceRoot: string;
+  readonly datasetName: string;
+  readonly projectId?: string;
+  readonly column?: string;
+  readonly ratios?: SplitRatios;
+  readonly parts?: readonly SplitPartSpec[];
+  readonly validateOnTest: boolean;
+  readonly balanceBy?: string;
+  readonly seed?: number;
+  readonly filters?: readonly string[];
+  readonly slice?: string;
+  readonly wait: boolean;
+  readonly waitFor?: WaitForOptions;
+  readonly json: boolean;
+};
+
+export const DEFAULT_SPLIT_COLUMN = "split";
+
+const formatPercent = (share: number): string => `${Math.round(share * 100)}%`;
+
+const presetParts = (ratios: SplitRatios, validateOnTest: boolean): SplitPartSpec[] => {
+  const parts: SplitPartSpec[] = [
+    { name: "train", roles: ["train"], share: ratios.train },
+    { name: "validate", roles: ["validate"], share: ratios.validate },
+    { name: "test", roles: validateOnTest ? ["validate", "test"] : ["test"], share: ratios.test },
+  ];
+  return parts.filter((part) => (part.share ?? 0) > 0);
+};
+
+const requestedParts = (options: SplitDatasetOptions): SplitPartSpec[] | undefined => {
+  assertCli(options.ratios === undefined || options.parts === undefined, "Pass --ratios or --parts, not both.", {
+    hint: { description: "--ratios 80/10/10 is the same as --parts train:80,validate:10,test:10." },
+  });
+  assertCli(
+    !options.validateOnTest || options.ratios?.validate === 0,
+    "--validate-on-test makes the test part the validation set too, so it needs a validate ratio of 0.",
+    {
+      hint: {
+        description: "Pass --ratios with validate 0, for example --ratios 80/0/20, or give a part both roles with --parts test=validate+test:20.",
+      },
+    },
+  );
+  return options.ratios === undefined
+    ? options.parts && [...options.parts]
+    : presetParts(options.ratios, options.validateOnTest);
+};
+
+const describeRoles = (roles: readonly string[]): string => roles.join("+") || "no role";
+
+type FieldSplit = NonNullable<DatasetField["split"]>;
+
+const describeParts = (split: FieldSplit): string => {
+  const shareOf = (name: string) => split.recipe?.shares.find((share) => share.name === name)?.share;
+  return split.parts
+    .map((part) => {
+      const share = shareOf(part.name);
+      return `${part.name} ${share === undefined ? "" : `${formatPercent(share)} `}(${describeRoles(part.roles)})`;
+    })
+    .join(", ");
+};
+
+export const describeSplitColumn = (field: DatasetField): string =>
+  field.split === null ? "-" : `${field.split.status} · ${describeParts(field.split)}`;
+
+export const formatSplitColumn = (field: DatasetField, fieldNames: ReadonlyMap<string, string>): string => {
+  const { split } = field;
+  assertCli(split !== null, `Column ${field.name} is not a split column.`, { hint: { disabled: true } });
+  const rows: string[][] = [
+    ["Column", `${field.name} (${field.id})`],
+    ["Status", split.status],
+    ["Parts", describeParts(split)],
+  ];
+  if (split.recipe !== null) {
+    const balanceBy = split.recipe.balanceByFieldId;
+    rows.push(["Balanced by", balanceBy === null ? "-" : (fieldNames.get(balanceBy) ?? balanceBy)]);
+    rows.push(["Seed", String(split.recipe.seed)]);
+  }
+  if (split.progress !== null) {
+    rows.push(["Placed", `${formatCount(split.progress.placed)} of ${formatCount(split.progress.total)}`]);
+  }
+  if (split.lastFill !== null) {
+    rows.push([
+      "Last fill",
+      `placed ${formatCount(split.lastFill.placed)}, ${formatCount(split.lastFill.kept)} already had a part`,
+    ]);
+    rows.push([
+      "Rows",
+      Object.entries(split.lastFill.parts)
+        .map(([name, count]) => `${name} ${formatCount(count)}`)
+        .join(" · "),
+    ]);
+  }
+  if (split.error !== null) rows.push(["Error", `${split.error.code}: ${split.error.message}`]);
+  return formatTable(rows);
+};
+
+export const waitForSplitColumn = async (
+  client: SplitApi,
+  { datasetId, field, waitFor }: { datasetId: string; field: DatasetField; waitFor?: WaitForOptions },
+): Promise<DatasetField> => {
+  const done =
+    field.split?.status === "filling"
+      ? await waitUntilDone(
+          () => client.waitFor({ type: "datasetSplit", datasetId, column: field.name }, waitFor ?? {}),
+          { what: `column ${field.name}`, checkCommand: `dataset columns ${datasetId}` },
+        )
+      : field;
+  assertCli(
+    done.split?.status !== "failed",
+    `Splitting column ${done.name} failed: ${done.split?.error?.message ?? "no reason given"}`,
+    { hint: { description: "Fix the cause, then run toloka dataset split again; rows that already have a part keep it." } },
+  );
+  return done;
+};
+
+const listFields = async (client: Pick<PotatoClient, "datasets">, datasetId: string): Promise<DatasetField[]> => {
+  const fields: DatasetField[] = [];
+  for await (const field of client.datasets.listAllFields({ datasetId })) fields.push(field);
+  return fields;
+};
+
+const assertFieldsToReadExist = async (
+  client: Pick<PotatoClient, "datasets">,
+  {
+    dataset,
+    fields,
+    column,
+    balanceBy,
+  }: {
+    dataset: { readonly datasetId: string; readonly name: string; readonly nameIsUnique: boolean };
+    fields: readonly DatasetField[];
+    column: string;
+    balanceBy: string | undefined;
+  },
+): Promise<void> => {
+  const datasetRef = dataset.nameIsUnique ? dataset.name : dataset.datasetId;
+  const isField = (name: string) => fields.some((field) => field.name === name || field.id === name);
+  if (!isField(column)) {
+    const uploaded = await uploadedFieldHint(client, { datasetId: dataset.datasetId, datasetRef, name: column });
+    assertCli(
+      uploaded === undefined,
+      `Dataset ${dataset.name} has no field ${column}, but its uploaded rows have one.`,
+      {
+        hint: {
+          description: `Add it as a dataset field with toloka dataset fields add ${datasetRef} ${column}, so the split takes its values as parts, or pass another --column for a new split column.`,
+        },
+      },
+    );
+  }
+  if (balanceBy !== undefined && !isField(balanceBy)) {
+    const uploaded = await uploadedFieldHint(client, { datasetId: dataset.datasetId, datasetRef, name: balanceBy });
+    assertCli(false, `Dataset ${dataset.name} has no field ${balanceBy} to balance by.`, {
+      hint: uploaded ?? { description: `List its fields with toloka dataset columns ${datasetRef}.` },
+    });
+  }
+};
+
+export async function splitDataset(client: PotatoClient, options: SplitDatasetOptions): Promise<DatasetSplitCommandResult> {
+  assertCli(options.slice === undefined || options.filters === undefined, "Pass --slice or --filter, not both.", {
+    hint: { description: "--slice fills the rows of a slice; --filter fills the rows that match now." },
+  });
+  const parts = requestedParts(options);
+  const dataset = await resolveLiveDataset(client, options, false);
+  const fields = options.wait
+    ? await waitForFilledFields(client, { datasetId: dataset.datasetId, waitFor: options.waitFor })
+    : await listFields(client, dataset.datasetId);
+  await assertFieldsToReadExist(client, {
+    dataset,
+    fields,
+    column: options.column ?? DEFAULT_SPLIT_COLUMN,
+    balanceBy: options.balanceBy,
+  });
+  const field = await client.datasets.split({
+    datasetId: dataset.datasetId,
+    column: options.column,
+    parts,
+    balanceBy: options.balanceBy,
+    seed: options.seed,
+    ...(options.slice === undefined ? {} : { slice: options.slice }),
+    ...(options.filters === undefined
+      ? {}
+      : { itemFilter: await resolveFieldValueFilters(client, dataset, options.filters) }),
+  });
+  const done = options.wait ? await waitForSplitColumn(client, { datasetId: dataset.datasetId, field, waitFor: options.waitFor }) : field;
+  return {
+    output: options.json
+      ? JSON.stringify(done, null, 2)
+      : formatSplitColumn(done, await fieldNamesOf(client, dataset.datasetId)),
+  };
+}
+
+export async function listDatasetColumns(
+  client: PotatoClient,
+  options: { readonly sourceRoot: string; readonly datasetName: string; readonly projectId?: string; readonly json: boolean },
+): Promise<DatasetSplitCommandResult> {
+  const dataset = await resolveLiveDataset(client, options, false);
+  const fields: DatasetField[] = [];
+  for await (const field of client.datasets.listAllFields({ datasetId: dataset.datasetId })) fields.push(field);
+  if (options.json) return { output: JSON.stringify(fields, null, 2) };
+  return {
+    output: formatTable([
+      ["COLUMN", "ID", "SPLIT"],
+      ...fields.filter((field) => !field.internal).map((field) => [field.name, field.id, describeSplitColumn(field)]),
+    ]),
+  };
+}