Table kit command
table.fields.create
Create a field
Adds a field (column) to a table: its title, its type (text, number, single_select, date, link_to_record, formula, ai, ...) and the options that type reads; answers the field with its id and name.
- Kit
- Table 0.4.0 (.ktable)
- Changes the document
- yes
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
ai_prompt | string | no | |
asOrigin | string | no | system:<name> writes as a host feature, outside the undo history. Agents leave it out. |
formula | string | no | |
is_primary | boolean | no | |
meta | any | no | |
name | string | no | 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. |
options | object | no | Settings of the field's type: only the keys its type reads matter, and other keys are kept as they are. |
order | integer | no | |
readonly | boolean | no | |
required | boolean | no | |
tableId | integer | string | yes | The table's id. |
title | string | no | |
type | "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" | no | The field's type (default text). There is no email or phone type: use text, or url for a link to open. text: One line of text (a string). long_text: Text of several lines (a string); options.showAs shows it as text or rendered markdown. number: A number. date: A calendar date written as YYYY-MM-DD; options.date_format is how the editor shows it. datetime: A date and time as an ISO 8601 string; options.date_format is how the editor shows it. single_select: One of options.choices (a string). multi_select: Some of options.choices (a list of strings). checkbox: true or false. url: A web address (a string). attachment: Files kept in the document: a list of the values table.attachments.put answers. document_link: A reference to another document (a string). formula: Computed from the field's `formula` expression, which names fields in braces ({price} * 2); read-only. ai: Written by the host's model as options.ai_config says (table.ai.prepare, then table.ai.apply); read-only. rating: A whole number from 0 to options.max (default 5). user: A person, {id, name, avatar?}, or a list of them. link_to_record: Links to records of the table options.target_table_id names; set with table.links.replace, read as [{row_key, display}]. lookup: Computed: the values of options.target_field_id in the records linked through options.link_field_id. rollup: Computed: options.aggregation over the records linked through options.link_field_id (their options.target_field_id values). button: A button labelled options.label that runs options.action; it holds no value. created_time: Reserved for when the record was created; this engine leaves it empty. last_modified_time: Reserved for when the record last changed; this engine leaves it empty. created_by: Reserved for who created the record; this engine leaves it empty. last_modified_by: Reserved for who last changed the record; this engine leaves it empty. auto_number: Reserved for a running number; this engine leaves it empty. |
Call through table_run
text
table_run {
"path": "<file>.ktable",
"steps": [{ "command": "table.fields.create", "params": { "tableId": <integer | string> } }]
}The required parameters, with placeholders for their types: not a tested example. Optional: ai_prompt, asOrigin, formula, is_primary, meta, name, options, order, readonly, required, title, type. 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 | A field (column). |
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 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": "object"
}Parameter schema
json
{
"additionalProperties": false,
"properties": {
"ai_prompt": {
"type": "string"
},
"asOrigin": {
"description": "system:<name> writes as a host feature, outside the undo history. Agents leave it out.",
"type": "string"
},
"formula": {
"type": "string"
},
"is_primary": {
"type": "boolean"
},
"meta": {},
"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"
},
"order": {
"type": "integer"
},
"readonly": {
"type": "boolean"
},
"required": {
"type": "boolean"
},
"tableId": {
"description": "The table's id.",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"Table"
]
},
"title": {
"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"
}
},
"required": [
"tableId"
],
"type": "object"
}Generated from kition-sdk packages/script/kits/table.ts and the kit itself (kition-table@ee73209). As data: commands.jsonl.