Table kit command
table.read
Read a table's or a view's records
Reads the records of one table, or of one view (only those its filter keeps, in its order), with their ids and values under the field names, a page at a time; changes nothing.
- Kit
- Table 0.4.0 (.ktable)
- Changes the document
- no
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
cursor | string | no | Where to go on: the cursor in a previous answer's next (the number of records before the page, counted from 0, as a string); default the first record. |
limit | integer | no | How many records to list, 1 to 200; default 50. |
tableId | integer | string | no | The table whose records to list, in order (a table's id, as inspect and table.tables.list answer it). |
viewId | integer | string | no | Instead of tableId: the view whose records to list, only those its filter keeps, in its order (a view's id, as inspect and table.views.list answer it). |
Call through table_run
text
table_run {
"path": "<file>.ktable",
"steps": [{ "command": "table.read" }]
}The required parameters, with placeholders for their types: not a tested example. Optional: cursor, limit, tableId, viewId. 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 page of the records of a table or a view. |
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 page of the records of a table or a view.",
"properties": {
"columns": {
"items": {
"description": "A field's name: the key of its values in table.records.create and table.records.update.",
"type": "string"
},
"type": "array"
},
"from": {
"description": "The first listed record's position, counted from 1.",
"type": "integer"
},
"next": {
"additionalProperties": true,
"description": "The step that lists the records after these; absent after the last.",
"properties": {
"command": {
"description": "table.read.",
"type": "string"
},
"params": {
"additionalProperties": true,
"description": "Its params: the same tableId or viewId, and the cursor to go on from.",
"type": "object"
}
},
"type": "object"
},
"rows": {
"items": {
"additionalProperties": true,
"description": "A record.",
"properties": {
"cells": {
"items": {
"description": "Its value in the column at the same position; null when empty. A link's records are {id, display}, by record id; text longer than 200 characters is cut and ends in an ellipsis."
},
"type": "array"
},
"id": {
"description": "The record's local projection address (recordId).",
"type": "integer"
},
"tool_id": {
"description": "The stable UUID accepted by recordId and used by receipts and conflicts.",
"type": "string"
}
},
"type": "object"
},
"type": "array"
},
"tableId": {
"description": "The table's id.",
"type": "integer"
},
"to": {
"description": "The last listed record's position, counted from 1.",
"type": "integer"
},
"total": {
"description": "How many records the table has, or the view shows.",
"type": "integer"
},
"viewId": {
"description": "The view's id, when a view was read.",
"type": "integer"
}
},
"type": "object"
}
},
"type": "object"
}Parameter schema
json
{
"additionalProperties": false,
"properties": {
"cursor": {
"description": "Where to go on: the cursor in a previous answer's next (the number of records before the page, counted from 0, as a string); default the first record.",
"type": "string"
},
"limit": {
"description": "How many records to list, 1 to 200; default 50.",
"type": "integer"
},
"tableId": {
"description": "The table whose records to list, in order (a table's id, as inspect and table.tables.list answer it).",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"Table"
]
},
"viewId": {
"description": "Instead of tableId: the view whose records to list, only those its filter keeps, in its order (a view's id, as inspect and table.views.list answer it).",
"oneOf": [
{
"type": "integer"
},
{
"type": "string"
}
],
"x-khp-types": [
"View"
]
}
},
"type": "object"
}Generated from kition-sdk packages/script/kits/table.ts and the kit itself (kition-table@ee73209). As data: commands.jsonl.