---
title: "table.transact: Run record and field operations as one step — Table kit command — Kition"
description: "Runs several record and field operations (set cells, create, delete or move records, move fields) as one atomic step that undoes together; a values key that names no field refuses the whole call."
canonical: "https://developer.kition.ai/docs/kits/table/commands/table.transact"
---

> Canonical HTML: [https://developer.kition.ai/docs/kits/table/commands/table.transact](https://developer.kition.ai/docs/kits/table/commands/table.transact)

# table.transact

**Run record and field operations as one step.** Runs several record and field operations (set cells, create, delete or move records, move fields) as one atomic step that undoes together; a values key that names no field refuses the whole call.

- Kit: Table 0.4.0 (.ktable); reference: [Table kit commands](https://developer.kition.ai/docs/kits/table.md)
- Changes the document: yes

## Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `asOrigin` | `string` | no | system:<name> writes as a host feature, outside the undo history. Agents leave it out. |
| `ops` | `(object \| object \| object \| object \| object)[]` | yes |  |

## Call through table_run

```text
table_run {
  "path": "<file>.ktable",
  "steps": [{ "command": "table.transact", "params": { "ops": <(object | object | object | object | object)[]> } }]
}
```

The required parameters, with placeholders for their types: not a tested example. Optional: `asOrigin`. table_run answers the step’s result in `completed[i].result`.

## Result

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `change` | `object \| null` | no | What the call changed, or null. |
| `error` | `object` | no | Why the call failed (A18); the file is as it was. |
| `result` | `object` | no | What the operations did. |

```json
{
  "additionalProperties": false,
  "description": "The request's own answer is in `result`, beside `change`: what the call changed in the document (null when nothing changed). A failed call answers `error` instead (A18).",
  "properties": {
    "change": {
      "description": "What the call changed, or null.",
      "oneOf": [
        {
          "additionalProperties": false,
          "description": "What one projection changed in the relational tables, by integer id. Every list is sorted and\nholds no repeats.",
          "properties": {
            "dashboards": {
              "description": "A dashboard, or the base's list of them, changed.",
              "type": "boolean"
            },
            "documentId": {
              "type": "string"
            },
            "origin": {
              "description": "Who wrote it: kind:principal, or a system origin's label.",
              "type": "string"
            },
            "recordsDeleted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "recordsReordered": {
              "description": "Tables whose records' positions changed.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "recordsUpserted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "schema": {
              "description": "Tables whose fields were added, removed, updated, or reordered.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "tables": {
              "description": "Tables whose own row changed: created, deleted, renamed, moved, or given a new primary\nfield.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "views": {
              "description": "Views created, deleted, updated, or reordered, or whose column widths or visibility\nchanged.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            }
          },
          "required": [
            "tables",
            "schema",
            "views",
            "recordsReordered",
            "dashboards"
          ],
          "type": "object"
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "additionalProperties": false,
      "description": "Why the call failed (A18); the file is as it was.",
      "properties": {
        "code": {
          "enum": [
            "invalid-params",
            "invalid-op",
            "invalid-value",
            "not-found",
            "read-only",
            "unknown-command",
            "command-failed",
            "not-open",
            "draft-required",
            "not-allowed",
            "unsupported",
            "unavailable",
            "failed"
          ],
          "type": "string"
        },
        "index": {
          "description": "The failing step or operation.",
          "type": "integer"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        }
      },
      "required": [
        "code",
        "message"
      ],
      "type": "object"
    },
    "result": {
      "additionalProperties": true,
      "description": "What the operations did.",
      "properties": {
        "change": {
          "additionalProperties": false,
          "description": "What one projection changed in the relational tables, by integer id. Every list is sorted and\nholds no repeats.",
          "properties": {
            "dashboards": {
              "description": "A dashboard, or the base's list of them, changed.",
              "type": "boolean"
            },
            "documentId": {
              "type": "string"
            },
            "origin": {
              "description": "Who wrote it: kind:principal, or a system origin's label.",
              "type": "string"
            },
            "recordsDeleted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "recordsReordered": {
              "description": "Tables whose records' positions changed.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "recordsUpserted": {
              "description": "[tableId, rowKey] pairs.",
              "items": {
                "items": {},
                "type": "array"
              },
              "type": "array"
            },
            "schema": {
              "description": "Tables whose fields were added, removed, updated, or reordered.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "tables": {
              "description": "Tables whose own row changed: created, deleted, renamed, moved, or given a new primary\nfield.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            },
            "views": {
              "description": "Views created, deleted, updated, or reordered, or whose column widths or visibility\nchanged.",
              "items": {
                "type": "integer"
              },
              "type": "array"
            }
          },
          "required": [
            "tables",
            "schema",
            "views",
            "recordsReordered",
            "dashboards"
          ],
          "type": "object"
        },
        "created": {
          "items": {
            "description": "The row key of a record the operations created.",
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}
```

## Parameter schema

```json
{
  "additionalProperties": false,
  "properties": {
    "asOrigin": {
      "description": "system:<name> writes as a host feature, outside the undo history. Agents leave it out.",
      "type": "string"
    },
    "ops": {
      "items": {
        "description": "One step of a transaction.",
        "oneOf": [
          {
            "additionalProperties": false,
            "description": "Sets cells of existing records; `null` clears. Computed fields are skipped; `transact`\nrefuses a key that names no field of the table.",
            "properties": {
              "op": {
                "enum": [
                  "cells.set"
                ],
                "type": "string"
              },
              "records": {
                "items": {
                  "additionalProperties": false,
                  "properties": {
                    "rowKey": {
                      "oneOf": [
                        {
                          "type": "integer"
                        },
                        {
                          "type": "string"
                        }
                      ]
                    },
                    "values": {
                      "additionalProperties": true,
                      "type": "object"
                    }
                  },
                  "required": [
                    "rowKey",
                    "values"
                  ],
                  "type": "object"
                },
                "type": "array"
              },
              "tableId": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              }
            },
            "required": [
              "tableId",
              "records",
              "op"
            ],
            "type": "object"
          },
          {
            "additionalProperties": false,
            "description": "Creates records (field name to initial value) at `at`; `null` appends. `transact` refuses\na key that names no field of the table.",
            "properties": {
              "at": {
                "description": "Where `records.create` inserts: `{\"before\": rowKey}` or `{\"after\": rowKey}`.",
                "oneOf": [
                  {
                    "additionalProperties": false,
                    "properties": {
                      "before": {
                        "oneOf": [
                          {
                            "type": "integer"
                          },
                          {
                            "type": "string"
                          }
                        ]
                      }
                    },
                    "required": [
                      "before"
                    ],
                    "type": "object"
                  },
                  {
                    "additionalProperties": false,
                    "properties": {
                      "after": {
                        "oneOf": [
                          {
                            "type": "integer"
                          },
                          {
                            "type": "string"
                          }
                        ]
                      }
                    },
                    "required": [
                      "after"
                    ],
                    "type": "object"
                  }
                ]
              },
              "op": {
                "enum": [
                  "records.create"
                ],
                "type": "string"
              },
              "records": {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              "tableId": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              }
            },
            "required": [
              "tableId",
              "records",
              "op"
            ],
            "type": "object"
          },
          {
            "additionalProperties": false,
            "description": "Deletes records and their links; unknown row keys are skipped.",
            "properties": {
              "op": {
                "enum": [
                  "records.delete"
                ],
                "type": "string"
              },
              "rowKeys": {
                "items": {
                  "oneOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "string"
                    }
                  ]
                },
                "type": "array"
              },
              "tableId": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              }
            },
            "required": [
              "tableId",
              "rowKeys",
              "op"
            ],
            "type": "object"
          },
          {
            "additionalProperties": false,
            "description": "Moves records, in the given order, to just before `before` (`null`: the end).",
            "properties": {
              "before": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              },
              "op": {
                "enum": [
                  "records.move"
                ],
                "type": "string"
              },
              "rowKeys": {
                "items": {
                  "oneOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "string"
                    }
                  ]
                },
                "type": "array"
              },
              "tableId": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              }
            },
            "required": [
              "tableId",
              "rowKeys",
              "op"
            ],
            "type": "object"
          },
          {
            "additionalProperties": false,
            "description": "Moves fields so the first becomes the `toIndex`-th of the table's other fields.",
            "properties": {
              "fieldIds": {
                "items": {
                  "oneOf": [
                    {
                      "type": "integer"
                    },
                    {
                      "type": "string"
                    }
                  ]
                },
                "type": "array"
              },
              "op": {
                "enum": [
                  "fields.move"
                ],
                "type": "string"
              },
              "tableId": {
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ]
              },
              "toIndex": {
                "type": "integer"
              }
            },
            "required": [
              "tableId",
              "fieldIds",
              "toIndex",
              "op"
            ],
            "type": "object"
          }
        ]
      },
      "type": "array"
    }
  },
  "required": [
    "ops"
  ],
  "type": "object"
}
```

Generated from kition-sdk packages/script/kits/table.ts and the kit itself (kition-table@ee73209).
