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

Parameters of table.read
NameTypeRequiredDescription
cursorstringnoWhere 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.
limitintegernoHow many records to list, 1 to 200; default 50.
tableIdinteger | stringnoThe table whose records to list, in order (a table's id, as inspect and table.tables.list answer it).
viewIdinteger | stringnoInstead 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

Result of table.read
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoA 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.