Table kit command

table.import.run

Import a file into a table

Imports a file given as base64 into a new or existing table, with write mode, schema mode, unique key and field overrides.

Kit
Table 0.4.0 (.ktable)
Changes the document
yes

Parameters

Parameters of table.import.run
NameTypeRequiredDescription
asOriginstringnosystem:<name> writes as a host feature, outside the undo history. Agents leave it out.
contentstringno
field_overridesobject[]no
fileNamestringno
idempotency_keystringno
import_tokenstringno
schema_modestringno
sheetstringno
sourceobjectnoA preview request's `source`: `{ kind: "workspace", workspace_path }` names the workspace file the host read the bytes from; anything else is an upload named by `fileName`.
targetobjectnoThe execute request's `target`. `document_id` is not checked: the kit has one document.
unique_bystring[]no
write_modestringno

Call through table_run

text
table_run {
  "path": "<file>.ktable",
  "steps": [{ "command": "table.import.run" }]
}

The required parameters, with placeholders for their types: not a tested example. Optional: asOrigin, content, field_overrides, fileName, idempotency_key, import_token, schema_mode, sheet, source, target, unique_by, write_mode. table_run answers the step’s result in completed[i].result.

Result

Result of table.import.run
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoWhat the import did.
Result JSON Schema
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 import did.",
      "properties": {
        "document_id": {
          "description": "The document's id.",
          "type": "integer"
        },
        "fields_created": {
          "description": "Fields created.",
          "type": "integer"
        },
        "fields_updated": {
          "description": "Fields changed.",
          "type": "integer"
        },
        "path": {
          "description": "The document's path.",
          "type": "string"
        },
        "rows_created": {
          "description": "Records created.",
          "type": "integer"
        },
        "rows_skipped": {
          "description": "Rows left out.",
          "type": "integer"
        },
        "rows_total": {
          "description": "Rows read.",
          "type": "integer"
        },
        "rows_updated": {
          "description": "Records updated (upsert).",
          "type": "integer"
        },
        "table_id": {
          "description": "The table written.",
          "type": "integer"
        },
        "warnings": {
          "items": {
            "additionalProperties": true,
            "description": "Something the import noticed.",
            "properties": {
              "code": {
                "description": "A stable code.",
                "type": "string"
              },
              "column": {
                "description": "The column, from 1, when it is about one.",
                "type": "integer"
              },
              "message": {
                "description": "What happened.",
                "type": "string"
              },
              "row": {
                "description": "The row, from 1, when it is about one.",
                "type": "integer"
              },
              "severity": {
                "description": "info, warning or error.",
                "type": "string"
              }
            },
            "type": "object"
          },
          "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"
    },
    "content": {
      "default": "",
      "type": "string"
    },
    "field_overrides": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "index": {
            "default": 0,
            "type": "integer"
          },
          "options": {
            "additionalProperties": true,
            "type": "object"
          },
          "title": {
            "default": "",
            "type": "string"
          },
          "type": {
            "default": "",
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "fileName": {
      "default": "",
      "type": "string"
    },
    "idempotency_key": {
      "default": "",
      "type": "string"
    },
    "import_token": {
      "default": "",
      "type": "string"
    },
    "schema_mode": {
      "default": "",
      "type": "string"
    },
    "sheet": {
      "default": "",
      "type": "string"
    },
    "source": {
      "additionalProperties": false,
      "description": "A preview request's `source`: `{ kind: \"workspace\", workspace_path }` names the workspace file\nthe host read the bytes from; anything else is an upload named by `fileName`.",
      "properties": {
        "kind": {
          "default": "",
          "type": "string"
        },
        "workspace_path": {
          "default": "",
          "type": "string"
        }
      },
      "type": "object"
    },
    "target": {
      "additionalProperties": false,
      "description": "The execute request's `target`. `document_id` is not checked: the kit has one document.",
      "properties": {
        "document_id": {
          "default": 0,
          "type": "integer"
        },
        "kind": {
          "default": "",
          "type": "string"
        },
        "path": {
          "default": "",
          "type": "string"
        },
        "table_id": {
          "default": 0,
          "oneOf": [
            {
              "type": "integer"
            },
            {
              "type": "string"
            }
          ],
          "x-khp-role": "object",
          "x-khp-types": [
            "Table"
          ]
        },
        "table_title": {
          "default": "",
          "type": "string",
          "x-khp-role": "place"
        }
      },
      "type": "object"
    },
    "unique_by": {
      "default": [],
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "write_mode": {
      "default": "",
      "type": "string"
    }
  },
  "type": "object"
}

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