Table kit command

table.tables.create

Create a table

Creates a table from a title and optionally its fields (each with a type and options) and views; without fields it gets a primary text field Title, without views a grid view All. Answers the table with its ids.

Kit
Table 0.4.0 (.ktable)
Changes the document
yes

Parameters

Parameters of table.tables.create
NameTypeRequiredDescription
asOriginstringnosystem:<name> writes as a host feature, outside the undo history. Agents leave it out.
descriptionstringno
fieldsobject[]no
namestringnoThe table's internal name, the key of its values when a field: lowercase ASCII letters, digits and `_`, starting with a letter and not ending with `_` (`^[a-z](?:[a-z0-9_]*[a-z0-9])?$`), unique among the document's tables. An explicit name is kept as given; one not in that form, or already taken (also by an earlier field of the same call), is refused with invalid_params. Without one it is derived from the title: letters and digits kept and lowercased, every other run of characters made one `_`, `_` trimmed, `f_` put before a leading digit, `field` when nothing is left (a title in Chinese, say, for a table too), then `_2`, `_3`, ... when taken.
titlestringno
viewsobject[]no

Call through table_run

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

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

Result

Result of table.tables.create
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoA table with its fields and views.
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": "A table with its fields and views.",
      "properties": {
        "created_at": {
          "description": "When it was created, in Unix milliseconds.",
          "type": "integer"
        },
        "description": {
          "description": "The table's description.",
          "type": "string"
        },
        "document_id": {
          "description": "Always 1: the document's id.",
          "type": "integer"
        },
        "fields": {
          "items": {
            "additionalProperties": true,
            "description": "A field (column).",
            "properties": {
              "ai_prompt": {
                "description": "A legacy AI prompt.",
                "type": "string"
              },
              "created_at": {
                "description": "When it was created, in Unix milliseconds.",
                "type": "integer"
              },
              "document_id": {
                "description": "Always 1: the document's id.",
                "type": "integer"
              },
              "formula": {
                "description": "A formula field's expression.",
                "type": "string"
              },
              "id": {
                "description": "The field's local projection address (fieldId).",
                "type": "integer"
              },
              "is_primary": {
                "description": "It names the record.",
                "type": "boolean"
              },
              "meta": {
                "additionalProperties": true,
                "description": "Metadata the host keeps with the field.",
                "type": "object"
              },
              "name": {
                "description": "The key of its values in a record's `values`.",
                "type": "string"
              },
              "options": {
                "additionalProperties": true,
                "description": "The settings its type reads (choices, target_table_id, …).",
                "type": "object"
              },
              "order": {
                "description": "Its position among the table's fields, from 1.",
                "type": "integer"
              },
              "readonly": {
                "description": "Values are not written by hand (formula and AI fields).",
                "type": "boolean"
              },
              "required": {
                "description": "A record needs a value.",
                "type": "boolean"
              },
              "table_id": {
                "description": "The table's id.",
                "type": "integer"
              },
              "title": {
                "description": "The title people see.",
                "type": "string"
              },
              "tool_id": {
                "description": "The stable UUID accepted by fieldId and used by receipts and conflicts.",
                "type": "string"
              },
              "type": {
                "description": "The field type.",
                "enum": [
                  "text",
                  "long_text",
                  "number",
                  "date",
                  "datetime",
                  "single_select",
                  "multi_select",
                  "checkbox",
                  "url",
                  "attachment",
                  "document_link",
                  "formula",
                  "ai",
                  "rating",
                  "user",
                  "link_to_record",
                  "lookup",
                  "rollup",
                  "button",
                  "created_time",
                  "last_modified_time",
                  "created_by",
                  "last_modified_by",
                  "auto_number"
                ],
                "type": "string"
              },
              "unique": {
                "description": "Values must differ between records.",
                "type": "boolean"
              },
              "updated_at": {
                "description": "When it last changed, in Unix milliseconds.",
                "type": "integer"
              },
              "user_id": {
                "description": "Always 0: the document's own user.",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "id": {
          "description": "The table's local projection address (tableId).",
          "type": "integer"
        },
        "meta": {
          "additionalProperties": true,
          "description": "Metadata the host keeps with the table.",
          "type": "object"
        },
        "name": {
          "description": "The table's internal name.",
          "type": "string"
        },
        "order": {
          "description": "Its position among the tables, from 1.",
          "type": "integer"
        },
        "primary_field_id": {
          "description": "The id of the field that names a record.",
          "oneOf": [
            {
              "description": "The id of the field that names a record.",
              "type": "integer"
            },
            {
              "type": "null"
            }
          ]
        },
        "title": {
          "description": "The table's title.",
          "type": "string"
        },
        "tool_id": {
          "description": "The stable UUID accepted by tableId and used by receipts and conflicts.",
          "type": "string"
        },
        "updated_at": {
          "description": "When it last changed, in Unix milliseconds.",
          "type": "integer"
        },
        "user_id": {
          "description": "Always 0: the document's own user.",
          "type": "integer"
        },
        "views": {
          "items": {
            "additionalProperties": true,
            "description": "A view of a table.",
            "properties": {
              "config": {
                "additionalProperties": true,
                "description": "Its filters, sorts, groups and display settings.",
                "type": "object"
              },
              "created_at": {
                "description": "When it was created, in Unix milliseconds.",
                "type": "integer"
              },
              "document_id": {
                "description": "Always 1: the document's id.",
                "type": "integer"
              },
              "id": {
                "description": "The view's local projection address (viewId).",
                "type": "integer"
              },
              "locked": {
                "description": "The view is locked against changes in the editor.",
                "type": "boolean"
              },
              "order": {
                "description": "Its position among the table's views, from 1.",
                "type": "integer"
              },
              "table_id": {
                "description": "The table's id.",
                "type": "integer"
              },
              "title": {
                "description": "The view's title.",
                "type": "string"
              },
              "tool_id": {
                "description": "The stable UUID accepted by viewId and used by receipts and conflicts.",
                "type": "string"
              },
              "type": {
                "description": "The view type.",
                "enum": [
                  "grid",
                  "kanban",
                  "calendar",
                  "gallery"
                ],
                "type": "string"
              },
              "updated_at": {
                "description": "When it last changed, in Unix milliseconds.",
                "type": "integer"
              },
              "user_id": {
                "description": "Always 0: the document's own user.",
                "type": "integer"
              }
            },
            "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"
    },
    "description": {
      "default": "",
      "type": "string"
    },
    "fields": {
      "default": [],
      "items": {
        "additionalProperties": false,
        "properties": {
          "ai_prompt": {
            "default": "",
            "type": "string"
          },
          "formula": {
            "default": "",
            "type": "string"
          },
          "name": {
            "description": "The field's internal name, the key of its values when a field: lowercase ASCII letters, digits and `_`, starting with a letter and not ending with `_` (`^[a-z](?:[a-z0-9_]*[a-z0-9])?$`), unique among the table's fields. An explicit name is kept as given; one not in that form, or already taken (also by an earlier field of the same call), is refused with invalid_params. Without one it is derived from the title: letters and digits kept and lowercased, every other run of characters made one `_`, `_` trimmed, `f_` put before a leading digit, `field` when nothing is left (a title in Chinese, say, for a table too), then `_2`, `_3`, ... when taken.",
            "type": "string"
          },
          "options": {
            "additionalProperties": true,
            "description": "Settings of the field's type: only the keys its type reads matter, and other keys are kept as they are.",
            "properties": {
              "action": {
                "description": "button: what it does, {\"kind\": \"open_url\", \"url\"} or {\"kind\": \"run_workflow\", \"workflow_id\"}."
              },
              "aggregation": {
                "description": "rollup: how the linked values combine.",
                "enum": [
                  "count",
                  "sum",
                  "avg",
                  "max",
                  "min",
                  "and",
                  "or",
                  "concat"
                ],
                "type": "string"
              },
              "ai_config": {
                "additionalProperties": true,
                "description": "ai (and text, long_text or attachment fields the host's model fills): what the model does, checked when the field runs. Also summary_instruction, extract_instruction or schema, improve_instruction, max_words, enabled, and image settings.",
                "properties": {
                  "categories": {
                    "description": "classify: two or more categories.",
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "prompt": {
                    "description": "The instruction of customize, text_generation and image_customization.",
                    "type": "string"
                  },
                  "source_field_id": {
                    "description": "The field it reads; not needed by customize, text_generation and image_customization.",
                    "oneOf": [
                      {
                        "type": "integer"
                      },
                      {
                        "type": "string"
                      }
                    ],
                    "x-khp-role": "object",
                    "x-khp-types": [
                      "Field"
                    ]
                  },
                  "target_language": {
                    "description": "translate: the language to write.",
                    "type": "string"
                  },
                  "type": {
                    "description": "The action.",
                    "enum": [
                      "summarize",
                      "translate",
                      "extract",
                      "improve",
                      "customize",
                      "classify",
                      "text_generation",
                      "image_generation",
                      "image_customization"
                    ],
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "allow_multiple": {
                "description": "link_to_record: false allows one linked record per cell; default true.",
                "type": "boolean"
              },
              "choices": {
                "description": "single_select, multi_select: the values to choose from, in order, for example [\"Lead\", \"Customer\"].",
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "date_format": {
                "description": "date, datetime: how the editor shows the value; the stored value does not change.",
                "enum": [
                  "year_month_day_slash",
                  "year_month_day_time_slash",
                  "year_month_day_time_zone_slash",
                  "year_month_day_dash",
                  "year_month_day_time_dash",
                  "year_month_day_time_zone_dash",
                  "month_day_dash",
                  "month_day_year_slash",
                  "day_month_year_slash"
                ],
                "type": "string"
              },
              "icon": {
                "description": "rating: the symbol shown; default star.",
                "enum": [
                  "star",
                  "heart",
                  "thumbs"
                ],
                "type": "string"
              },
              "label": {
                "description": "button: the button's text; default the field's title.",
                "type": "string"
              },
              "link_field_id": {
                "description": "lookup, rollup: the link_to_record field of this table to follow.",
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ],
                "x-khp-role": "object",
                "x-khp-types": [
                  "Field"
                ]
              },
              "max": {
                "description": "rating: the highest rating, 1 to 10; default 5.",
                "type": "integer"
              },
              "multi_value_mode": {
                "description": "lookup: list answers the values as a list (default), concat as one string.",
                "enum": [
                  "list",
                  "concat"
                ],
                "type": "string"
              },
              "showAs": {
                "description": "long_text: show the value as plain text or as rendered markdown.",
                "enum": [
                  "text",
                  "markdown"
                ],
                "type": "string"
              },
              "symmetric_field_id": {
                "description": "link_to_record: the link field of the target table that links back, if any.",
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ],
                "x-khp-role": "object",
                "x-khp-types": [
                  "Field"
                ]
              },
              "target_field_id": {
                "description": "lookup, rollup: the field of the linked records to read; a rollup without it aggregates the linked records themselves (count).",
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ],
                "x-khp-role": "object",
                "x-khp-types": [
                  "Field"
                ]
              },
              "target_table_id": {
                "description": "link_to_record: the id of the table whose records it links to.",
                "oneOf": [
                  {
                    "type": "integer"
                  },
                  {
                    "type": "string"
                  }
                ],
                "x-khp-role": "object",
                "x-khp-types": [
                  "Table"
                ]
              }
            },
            "type": "object"
          },
          "primary": {
            "default": false,
            "type": "boolean"
          },
          "readonly": {
            "default": false,
            "type": "boolean"
          },
          "required": {
            "default": false,
            "type": "boolean"
          },
          "title": {
            "default": "",
            "type": "string"
          },
          "type": {
            "description": "The field's type (default text). There is no email or phone type: use text, or url for a link to open.\ntext: One line of text (a string).\nlong_text: Text of several lines (a string); options.showAs shows it as text or rendered markdown.\nnumber: A number.\ndate: A calendar date written as YYYY-MM-DD; options.date_format is how the editor shows it.\ndatetime: A date and time as an ISO 8601 string; options.date_format is how the editor shows it.\nsingle_select: One of options.choices (a string).\nmulti_select: Some of options.choices (a list of strings).\ncheckbox: true or false.\nurl: A web address (a string).\nattachment: Files kept in the document: a list of the values table.attachments.put answers.\ndocument_link: A reference to another document (a string).\nformula: Computed from the field's `formula` expression, which names fields in braces ({price} * 2); read-only.\nai: Written by the host's model as options.ai_config says (table.ai.prepare, then table.ai.apply); read-only.\nrating: A whole number from 0 to options.max (default 5).\nuser: A person, {id, name, avatar?}, or a list of them.\nlink_to_record: Links to records of the table options.target_table_id names; set with table.links.replace, read as [{row_key, display}].\nlookup: Computed: the values of options.target_field_id in the records linked through options.link_field_id.\nrollup: Computed: options.aggregation over the records linked through options.link_field_id (their options.target_field_id values).\nbutton: A button labelled options.label that runs options.action; it holds no value.\ncreated_time: Reserved for when the record was created; this engine leaves it empty.\nlast_modified_time: Reserved for when the record last changed; this engine leaves it empty.\ncreated_by: Reserved for who created the record; this engine leaves it empty.\nlast_modified_by: Reserved for who last changed the record; this engine leaves it empty.\nauto_number: Reserved for a running number; this engine leaves it empty.",
            "enum": [
              "text",
              "long_text",
              "number",
              "date",
              "datetime",
              "single_select",
              "multi_select",
              "checkbox",
              "url",
              "attachment",
              "document_link",
              "formula",
              "ai",
              "rating",
              "user",
              "link_to_record",
              "lookup",
              "rollup",
              "button",
              "created_time",
              "last_modified_time",
              "created_by",
              "last_modified_by",
              "auto_number"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    },
    "name": {
      "description": "The table's internal name, the key of its values when a field: lowercase ASCII letters, digits and `_`, starting with a letter and not ending with `_` (`^[a-z](?:[a-z0-9_]*[a-z0-9])?$`), unique among the document's tables. An explicit name is kept as given; one not in that form, or already taken (also by an earlier field of the same call), is refused with invalid_params. Without one it is derived from the title: letters and digits kept and lowercased, every other run of characters made one `_`, `_` trimmed, `f_` put before a leading digit, `field` when nothing is left (a title in Chinese, say, for a table too), then `_2`, `_3`, ... when taken.",
      "type": "string"
    },
    "title": {
      "default": "",
      "type": "string"
    },
    "views": {
      "default": [],
      "items": {
        "additionalProperties": false,
        "properties": {
          "config": {},
          "title": {
            "default": "",
            "type": "string"
          },
          "type": {
            "description": "The view's type (default grid).\ngrid: Rows and columns.\nkanban: Cards in columns, one per choice of a single_select field (config group_field_name, else the first single_select) or per checkbox value.\ncalendar: Records placed on the table's first date or datetime field.\ngallery: Cards with a cover picture (config cover_field_name, else the first attachment or url field).",
            "enum": [
              "grid",
              "kanban",
              "calendar",
              "gallery"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "type": "array"
    }
  },
  "type": "object"
}

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