Table kit command

table.records.history

Read a record's history

Reads one record's change history, newest first: its creation and each field update, with the values before and after, who made it and when.

Kit
Table 0.4.0 (.ktable)
Changes the document
no
Acts on
recordId (one id), which a run step’s on fills

Parameters

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

Call through table_run

text
table_run {
  "path": "<file>.ktable",
  "steps": [{ "command": "table.records.history", "params": { "tableId": <integer | string>, "recordId": <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.history
NameTypeRequiredDescription
changeobject | nullnoWhat the call changed, or null.
errorobjectnoWhy the call failed (A18); the file is as it was.
resultobjectnoA page of the record's history, newest first.
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 record's history, newest first.",
      "properties": {
        "items": {
          "items": {
            "additionalProperties": true,
            "description": "One change.",
            "properties": {
              "action": {
                "description": "What happened.",
                "enum": [
                  "create",
                  "update",
                  "delete"
                ],
                "type": "string"
              },
              "actor": {
                "description": "Who made the change.",
                "type": "string"
              },
              "after": {
                "description": "The value after (the whole record's values for a create)."
              },
              "before": {
                "description": "The value before (the whole record's values for a delete)."
              },
              "created_at": {
                "description": "When, in Unix milliseconds.",
                "type": "integer"
              },
              "document_id": {
                "description": "The document's KDM id.",
                "type": "string"
              },
              "field_id": {
                "description": "The field changed; null for a create or delete.",
                "oneOf": [
                  {
                    "description": "The field changed; null for a create or delete.",
                    "type": "integer"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "id": {
                "description": "The entry's id.",
                "type": "integer"
              },
              "record_id": {
                "description": "The record's id.",
                "type": "integer"
              },
              "table_id": {
                "description": "The table's id.",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "type": "array"
        },
        "limit": {
          "description": "The page size.",
          "type": "integer"
        },
        "offset": {
          "description": "How many were skipped.",
          "type": "integer"
        },
        "total": {
          "description": "How many entries there are.",
          "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"
    },
    "recordId": {
      "description": "The record's id.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-index-numbers": true,
      "x-khp-types": [
        "Record"
      ]
    },
    "tableId": {
      "description": "The table's id.",
      "oneOf": [
        {
          "type": "integer"
        },
        {
          "type": "string"
        }
      ],
      "x-khp-types": [
        "Table"
      ]
    }
  },
  "required": [
    "tableId",
    "recordId"
  ],
  "type": "object"
}

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