Table kit command

table.import.preview

Preview a file import

Parses a CSV, TSV or spreadsheet file given as base64 and answers its sheets, detected columns and types and sample rows, without changing anything.

Kit
Table 0.4.0 (.ktable)
Changes the document
no

Parameters

Parameters of table.import.preview
NameTypeRequiredDescription
contentstringno
fileNamestringno
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`.

Call through table_run

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

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

Result

Result of table.import.preview
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoWhat the file holds and how it would be imported.
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 file holds and how it would be imported.",
      "properties": {
        "delimiter": {
          "description": "The delimiter of a CSV or TSV file.",
          "type": "string"
        },
        "encoding": {
          "description": "The text encoding of a CSV or TSV file.",
          "type": "string"
        },
        "expires_at": {
          "description": "When the preview expires; left out, since the kit keeps none.",
          "type": "integer"
        },
        "field_count": {
          "description": "How many columns.",
          "type": "integer"
        },
        "fields": {
          "items": {
            "additionalProperties": true,
            "description": "A column and the field it would become.",
            "properties": {
              "index": {
                "description": "The column, from 0.",
                "type": "integer"
              },
              "nullable": {
                "description": "Some rows leave it empty.",
                "type": "boolean"
              },
              "options": {
                "additionalProperties": true,
                "description": "The detected options (a select's choices).",
                "type": "object"
              },
              "sample_values": {
                "items": {
                  "description": "A value of the first rows."
                },
                "type": "array"
              },
              "title": {
                "description": "Its header.",
                "type": "string"
              },
              "type": {
                "description": "The field type detected.",
                "type": "string"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "filename": {
          "description": "The file's name.",
          "type": "string"
        },
        "format": {
          "description": "csv, tsv, xlsx, xls or ods.",
          "type": "string"
        },
        "import_token": {
          "description": "The preview's token (sha256 of the file).",
          "type": "string"
        },
        "row_count": {
          "description": "How many data rows.",
          "type": "integer"
        },
        "sample_rows": {
          "items": {
            "items": {
              "description": "A cell."
            },
            "type": "array"
          },
          "type": "array"
        },
        "selected_sheet": {
          "description": "The spreadsheet's sheet read.",
          "type": "string"
        },
        "sheets": {
          "items": {
            "additionalProperties": true,
            "description": "A sheet of a spreadsheet.",
            "properties": {
              "field_count": {
                "description": "How many columns.",
                "type": "integer"
              },
              "hidden": {
                "description": "Hidden in the spreadsheet.",
                "type": "boolean"
              },
              "index": {
                "description": "Its position, from 0.",
                "type": "integer"
              },
              "name": {
                "description": "Its name.",
                "type": "string"
              },
              "row_count": {
                "description": "How many data rows.",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "source": {
          "additionalProperties": true,
          "description": "Where the file came from.",
          "properties": {
            "kind": {
              "description": "upload.",
              "type": "string"
            },
            "upload_name": {
              "description": "The file's name.",
              "type": "string"
            },
            "workspace_path": {
              "description": "Unused by the kit.",
              "type": "string"
            }
          },
          "type": "object"
        },
        "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": {
    "content": {
      "default": "",
      "type": "string"
    },
    "fileName": {
      "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"
    }
  },
  "type": "object"
}

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