Table kit command

table.records.list

List records

Reads a table's records (rows) with their values keyed by field name, a page at a time (limit, offset), with the total.

Kit
Table 0.4.0 (.ktable)
Changes the document
no

Parameters

Parameters of table.records.list
NameTypeRequiredDescription
limitintegernoHow many items to answer at most.
offsetintegernoHow many items to skip, from 0.
tableIdinteger | stringyesThe table's id.

Call through table_run

text
table_run {
  "path": "<file>.ktable",
  "steps": [{ "command": "table.records.list", "params": { "tableId": <integer | string> } }]
}

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

Result

Result of table.records.list
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoA page of records.
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 records.",
      "properties": {
        "items": {
          "items": {
            "additionalProperties": true,
            "description": "A record (row).",
            "properties": {
              "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 record's local projection address (recordId).",
                "type": "integer"
              },
              "order": {
                "description": "Its position in the table, from 1.",
                "type": "integer"
              },
              "row_key": {
                "description": "The record's stable key, used by links, bulk commands and transact.",
                "type": "string"
              },
              "table_id": {
                "description": "The table's id.",
                "type": "integer"
              },
              "tool_id": {
                "description": "The stable UUID accepted by recordId 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"
              },
              "values": {
                "additionalProperties": true,
                "description": "Its values, keyed by field name; a missing key is an empty value.",
                "type": "object"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "limit": {
          "description": "The page size.",
          "type": "integer"
        },
        "offset": {
          "description": "How many were skipped.",
          "type": "integer"
        },
        "total": {
          "description": "How many records the table has.",
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "type": "object"
}

Parameter schema

json
{
  "additionalProperties": false,
  "properties": {
    "limit": {
      "description": "How many items to answer at most.",
      "type": "integer"
    },
    "offset": {
      "description": "How many items to skip, from 0.",
      "type": "integer"
    },
    "tableId": {
      "description": "The table's id.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-types": [
        "Table"
      ]
    }
  },
  "required": [
    "tableId"
  ],
  "type": "object"
}

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