Plans

Plans are the structured operation format executed by CSDB. All public query surfaces converge on the same executor:

• The fluent table API builds plans from chained method calls.
• SQL text is parsed into plans before execution.
• JSON sends plans directly inside a server command envelope.

Flow

TableQuery API ─┐
SQL text     ───┼─> QueryPlan ─> Executor ─> rows or mutation result
JSON command ───┘

Plan Kinds

type QueryPlan =
  | SelectPlan
  | InsertPlan
  | UpdatePlan
  | DeletePlan
  | CreateTablePlan
  | DropTablePlan;

Select Rows

Produced by fluent selection methods, SELECT, or a JSON select command.

TypeScript

{
  kind: "select",
  table: "workers",
  columns: ["id", "email"],
  joins: [],
  where: {
    type: "is-null",
    expr: { type: "identifier", name: "email" },
    not: true
  },
  orderBy: [{ column: "id", direction: "asc" }],
  limit: 10,
  output: "objects"
}

SQL

SELECT id, email
FROM workers
WHERE email IS NOT NULL
ORDER BY id ASC
LIMIT 10;

JSON

{
  "database": "payroll",
  "command": {
    "kind": "select",
    "table": "workers",
    "columns": ["id", "email"],
    "joins": [],
    "where": {
      "type": "is-null",
      "expr": { "type": "identifier", "name": "email" },
      "not": true
    },
    "orderBy": [{ "column": "id", "direction": "asc" }],
    "limit": 10,
    "output": "objects"
  }
}

Mutate Rows

Produced by fluent mutation methods, SQL, or JSON mutation commands.

TypeScript

{ kind: "insert", table: "workers", rows: [{ id: "w_001" }] }
{ kind: "update", table: "workers", set: { email: "ada@example.com" }, where: expression }
{ kind: "delete", table: "workers", where: expression }

SQL

INSERT INTO workers (id, name, email) VALUES (?, ?, ?);
UPDATE workers SET email = ? WHERE id = ?;
DELETE FROM workers WHERE id = ?;

JSON

Each object is the body of a separate POST /v1/commands request.

{
  "database": "payroll",
  "command": {
    "kind": "insert",
    "table": "workers",
    "rows": [{ "id": "w_001" }]
  }
}

{
  "database": "payroll",
  "command": {
    "kind": "update",
    "table": "workers",
    "set": { "email": "ada@example.com" },
    "where": {
      "type": "comparison",
      "op": "=",
      "left": { "type": "identifier", "name": "id" },
      "right": { "type": "literal", "value": "w_001" }
    }
  }
}

{
  "database": "payroll",
  "command": {
    "kind": "delete",
    "table": "workers",
    "where": {
      "type": "comparison",
      "op": "=",
      "left": { "type": "identifier", "name": "id" },
      "right": { "type": "literal", "value": "w_001" }
    }
  }
}

Change Tables

Produced by database table methods, compact DDL SQL, or JSON DDL commands.

TypeScript

{ kind: "create-table", schema }
{ kind: "drop-table", table: "tags" }

SQL

CREATE TABLE tags (label text primary key);
DROP TABLE tags;

JSON

{
  "database": "payroll",
  "command": {
    "kind": "create-table",
    "schema": {
      "name": "tags",
      "columns": { "label": "text" },
      "required": ["label"],
      "primary_key": { "columns": ["label"] }
    }
  }
}

{
  "database": "payroll",
  "command": { "kind": "drop-table", "table": "tags" }
}

Expressions

Expressions represent literals, identifiers, comparisons, IS NULL, AND, OR, and NOT. They are used in plan where fields and constraint evaluation. JSON uses the exact discriminated expression objects documented in Command Requests.