@fadhilp/stateql 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@ const RESULT_COMMANDS = new Set(["query", "mongo.query", "redis.query", "filter"
3
3
  const FALSE_DEFAULT_KEYS = ["cached", "duplicate", "duplicate_override"];
4
4
  const SHARED_HISTORY_KEYS = ["session_id", "actor_id", "actor_name", "origin"];
5
5
  // The caller already holds the handle it passed to these commands.
6
- const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns"]);
6
+ const HANDLE_ECHO_COMMANDS = new Set(["rows", "count", "columns", "summarize"]);
7
7
  const WRITE_COMMANDS = new Set(["exec", "mongo.exec", "redis.exec", "apply"]);
8
8
  const COMMAND_ALIASES = {
9
9
  "objects.list": "objects",
@@ -55,6 +55,10 @@ export function agentResponse(result, commandName) {
55
55
  data.total = data.rows;
56
56
  delete data.rows;
57
57
  }
58
+ else if (currentCommand === "summarize" && Array.isArray(data.columns)) {
59
+ const table = columnarRows(data.columns, undefined);
60
+ Object.assign(data, { columns: table.columns, rows: table.rows });
61
+ }
58
62
  else if (WRITE_COMMANDS.has(currentCommand)) {
59
63
  delete data.actor_id;
60
64
  delete data.plan_id;
@@ -187,6 +191,7 @@ function primaryHandleKey(currentCommand) {
187
191
  rows: "result_id",
188
192
  count: "result_id",
189
193
  columns: "result_id",
194
+ summarize: "result_id",
190
195
  export: "result_id",
191
196
  alias: "result_id",
192
197
  "alias.set": "result_id",
package/dist/src/cli.js CHANGED
@@ -8,6 +8,41 @@ import { exitCodeFor } from "./errors.js";
8
8
  import { StateQL } from "./stateql.js";
9
9
  import { agentResponse } from "./agent-response.js";
10
10
  import { askPassword, cliCredentialResolver, deleteOsPassword, saveOsPassword } from "./os-credentials.js";
11
+ const USAGE = `stql connect <target> [--name NAME] [--read-only|--read-write]
12
+ stql connect --env ENV | --credential-ref REF | --profile NAME [--name NAME] [--read-only|--read-write]
13
+ stql disconnect|status
14
+ stql actor show | set-name <display-name>
15
+ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
16
+ [--read-only|--read-write]
17
+ stql profile list|show|remove NAME
18
+ stql session start|list|show|summary|close
19
+ stql query <sql> | --file FILE [--params JSON | --param VALUE... | --params-file FILE]
20
+ [--cache auto|bypass|require] [--preview-rows 0..200]
21
+ stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
22
+ stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY]
23
+ [--replay] [--allow-unbounded] [--allow-destructive]
24
+ stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded]
25
+ [--allow-destructive]
26
+ stql apply <plan-handle>
27
+ stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
28
+ [--replay] [--allow-unbounded] [--allow-destructive]
29
+ stql redis query|exec|plan '<JSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
30
+ [--replay]
31
+ stql show|count|columns|summarize <result-handle>
32
+ stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
33
+ stql alias set <name> <result-handle>
34
+ stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
35
+ stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
36
+ stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
37
+ stql object KIND NAME [IDENTITY] [--schema NAME]
38
+ stql transaction begin|status|commit|rollback [--isolation LEVEL]
39
+ stql history [--limit N] [--offset N] [--category statement|introspection|management]
40
+ [--internal|--external]
41
+ stql receipt <operation-handle>
42
+ stql doctor|capabilities
43
+ stql purge [expired|results|history|all]
44
+ stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
45
+ stql pipe [--continue-on-error]`;
11
46
  const parsed = parseArgs({
12
47
  allowPositionals: true,
13
48
  strict: true,
@@ -22,6 +57,8 @@ const parsed = parseArgs({
22
57
  params: { type: "string" },
23
58
  param: { type: "string", multiple: true },
24
59
  "params-file": { type: "string" },
60
+ file: { type: "string" },
61
+ columns: { type: "string" },
25
62
  cache: { type: "string" },
26
63
  "preview-rows": { type: "string" },
27
64
  "max-cell-characters": { type: "string" },
@@ -56,7 +93,13 @@ if (values.version) {
56
93
  process.exit(0);
57
94
  }
58
95
  if (values.help || !command || command === "help") {
59
- console.log(helpText());
96
+ const topic = command === "help" ? subcommand : command;
97
+ const usage = topic ? commandUsage(topic) : helpText();
98
+ if (usage === undefined) {
99
+ console.error(`Unknown command "${topic}". Run "stql help" to list commands.`);
100
+ process.exit(exitCodeFor("INVALID_COMMAND"));
101
+ }
102
+ console.log(usage);
60
103
  process.exit(0);
61
104
  }
62
105
  const abortController = new AbortController();
@@ -147,7 +190,7 @@ async function runBatch() {
147
190
  }
148
191
  async function dispatch() {
149
192
  const params = parseParameters(values.params, values.param, values["params-file"]);
150
- const sql = [subcommand, ...rest].filter(Boolean).join(" ");
193
+ const sql = () => statementText([subcommand, ...rest]);
151
194
  switch (command) {
152
195
  case "connect": {
153
196
  if (values["read-only"] && values["read-write"]) {
@@ -183,7 +226,7 @@ async function dispatch() {
183
226
  case "redis":
184
227
  return dispatchRedis(subcommand, rest);
185
228
  case "query":
186
- return stateql.query(sql, {
229
+ return stateql.query(sql(), {
187
230
  params,
188
231
  cache: cacheMode(values.cache),
189
232
  ...(values["preview-rows"] === undefined
@@ -193,7 +236,7 @@ async function dispatch() {
193
236
  case "filter":
194
237
  return stateql.filter(requireValue(subcommand, "result handle"), requireValue(rest.join(" ").trim(), "filter predicate"), { params });
195
238
  case "exec":
196
- return stateql.exec(sql, {
239
+ return stateql.exec(sql(), {
197
240
  params,
198
241
  replay: values.replay ?? false,
199
242
  ...(values["idempotency-key"]
@@ -208,13 +251,16 @@ async function dispatch() {
208
251
  return stateql.rows(requireValue(subcommand, "result handle"), {
209
252
  offset: numberOption(values.offset, 0),
210
253
  limit: numberOption(values.limit, 20),
254
+ ...(values.columns === undefined ? {} : { columns: columnList(values.columns) }),
211
255
  });
212
256
  case "count":
213
257
  return stateql.count(requireValue(subcommand, "result handle"));
214
258
  case "columns":
215
259
  return stateql.columns(requireValue(subcommand, "result handle"));
260
+ case "summarize":
261
+ return stateql.summarize(requireValue(subcommand, "result handle"));
216
262
  case "export":
217
- return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format));
263
+ return stateql.exportResult(requireValue(subcommand, "result handle"), requireValue(values.output, "--output"), exportFormat(values.format), values.columns === undefined ? undefined : columnList(values.columns));
218
264
  case "alias":
219
265
  if (subcommand !== "set")
220
266
  throw new Error("Expected: alias set NAME RESULT");
@@ -241,7 +287,7 @@ async function dispatch() {
241
287
  case "transaction":
242
288
  return dispatchTransaction(subcommand, rest[0]);
243
289
  case "plan":
244
- return stateql.plan(sql, {
290
+ return stateql.plan(sql(), {
245
291
  params,
246
292
  allowUnbounded: values["allow-unbounded"] ?? false,
247
293
  ...(values["allow-destructive"]
@@ -271,7 +317,7 @@ async function dispatch() {
271
317
  }
272
318
  }
273
319
  async function dispatchMongo(action, args) {
274
- const payload = requireValue(args.join(" ").trim(), "MongoDB EJSON command");
320
+ const payload = requireValue(statementText(args), "MongoDB EJSON command");
275
321
  switch (action) {
276
322
  case "query":
277
323
  return stateql.mongoQuery(parseMongoCommand(payload), {
@@ -298,7 +344,7 @@ async function dispatchMongo(action, args) {
298
344
  }
299
345
  }
300
346
  async function dispatchRedis(action, args) {
301
- const payload = parseRedisCommand(requireValue(args.join(" ").trim(), "Redis JSON command"));
347
+ const payload = parseRedisCommand(requireValue(statementText(args), "Redis JSON command"));
302
348
  switch (action) {
303
349
  case "query": return stateql.redisQuery(payload, { cache: cacheMode(values.cache) });
304
350
  case "exec": return stateql.redisExec(payload, { replay: values.replay ?? false, ...(values["idempotency-key"] ? { idempotencyKey: values["idempotency-key"] } : {}) });
@@ -453,6 +499,21 @@ function parseParameters(value, values, file) {
453
499
  }
454
500
  return parsedValue;
455
501
  }
502
+ function statementText(args) {
503
+ const inline = args.filter(Boolean).join(" ").trim();
504
+ const file = values.file;
505
+ if (file === undefined)
506
+ return inline;
507
+ if (inline)
508
+ throw new Error("Use either inline text or --file, not both.");
509
+ if (file === "-" && values["params-file"] === "-") {
510
+ throw new Error("--file and --params-file cannot both read standard input.");
511
+ }
512
+ return withoutBom(readFileSync(file === "-" ? 0 : resolve(file), "utf8")).trim();
513
+ }
514
+ function columnList(value) {
515
+ return value.split(",").map((name) => name.trim()).filter(Boolean);
516
+ }
456
517
  function parseParameter(value) {
457
518
  try {
458
519
  return JSON.parse(value);
@@ -606,30 +667,20 @@ function extractHandle(data) {
606
667
  }
607
668
  return undefined;
608
669
  }
670
+ function commandUsage(name) {
671
+ const entries = USAGE.split(/\n(?=stql )/).filter((entry) => entry.slice("stql ".length).split(" ")[0].split("|").includes(name));
672
+ return entries.length > 0 ? entries.join("\n") : undefined;
673
+ }
609
674
  function helpText() {
610
675
  return `StateQL ${packageVersion()}
611
676
 
612
677
  Usage: stql <command> [arguments] [options]
613
678
 
614
- Commands:
615
- connect TARGET | --env ENV | --credential-ref REF | --profile NAME
616
- disconnect, status
617
- actor show | set-name NAME
618
- profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential-ref REF]
619
- profile list|show|remove
620
- query, filter, exec, show, rows, count, columns, export
621
- mongo query|exec|plan '<EJSON command>'
622
- redis query|exec|plan '<JSON command>'
623
- alias set
624
- inspect schema|table|collection|collections|columns|indexes|constraints
625
- objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR]
626
- object KIND NAME [IDENTITY] [--schema NAME]
627
- transaction begin|status|commit|rollback
628
- plan, apply, history [--category CATEGORY] [--internal|--external], receipt, doctor, purge, capabilities
629
- batch [file.json|file.jsonl|-]
630
- pipe
679
+ Commands (stql help COMMAND shows one):
680
+ ${USAGE}
631
681
 
632
682
  SQL parameters: --params JSON, repeated --param VALUE, or --params-file FILE.
683
+ Long SQL or native commands: --file FILE (- reads standard input) instead of inline text.
633
684
  Query preview: --preview-rows N (default: 5, maximum: 200).
634
685
  Long cells: --max-cell-characters N (default: 200); use export for full values.
635
686
  Deadline: --timeout-ms N (default: 30000). Ctrl+C cancels database work.
@@ -3,4 +3,4 @@ export { agentResponse } from "./agent-response.js";
3
3
  export { CredentialResolutionError, StateQLError, exitCodeFor, } from "./errors.js";
4
4
  export type { CredentialResolutionFailure } from "./errors.js";
5
5
  export type { TableChange, TableIdentity, TableUpdate } from "./table-editor.js";
6
- export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
6
+ export type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, BatchCommandName, BatchOptions, CatalogObject, CatalogObjectKind, DescribeObjectData, ListObjectsData, ListObjectsFilter, CapabilitiesData, CommandExecutionContext, CommandOrigin, CloseSessionData, Column, ColumnsData, ColumnSummary, CommitTransactionData, ConnectOptions, ConnectionData, CountData, CredentialAccess, CredentialOperation, CredentialRequest, CredentialSource, CredentialResolver, DisconnectData, DoctorData, Driver, ExecData, ExecOptions, ExecutionOptions, ExportData, Failure, FilterOptions, HistoryData, HistoryEntry, HistoryCategory, HistoryOptions, MongoAggregateOptions, MongoDocument, MongoFindOptions, MongoMutationOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, MongoWriteOutcome, OperationData, PlanData, PlanOptions, ProfileData, ProfileOptions, ProfileUpdateOptions, ProfilesData, PurgeData, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, RedisWriteOutcome, QueryOptions, RecentOperationData, RecentResultData, RemovedProfileData, Response, ResultData, RollbackTransactionData, Row, RowsData, RowsOptions, SqlParameters, SqlDriver, StateQLActorOptions, StateQLOptions, StateConfidence, StateQLSnapshot, StateQLSnapshotOptions, StateQLWorkspaceOptions, StatusConnectionData, StatusData, SummaryData, Success, SessionData, SessionListItem, SessionsData, SessionSummaryData, TransactionData, TransactionReferenceData, Warning, } from "./types.js";
package/dist/src/sql.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import type { AST } from "node-sql-parser";
2
- import type { Driver, SqlDriver } from "./types.js";
2
+ import type { Driver, SqlDriver, SqlParameters } from "./types.js";
3
3
  export type StatementType = "select" | "insert" | "upsert" | "replace" | "update" | "delete" | "create" | "alter" | "drop" | "truncate" | "values" | "show" | "explain" | "vacuum" | "analyze" | "reindex" | "optimize" | "check" | "cluster";
4
4
  export interface SqlAnalysis {
5
5
  ast: AST;
@@ -18,3 +18,9 @@ export interface SqlAnalysis {
18
18
  export declare function analyzeSql(sql: string, driver: SqlDriver): SqlAnalysis;
19
19
  /** @internal Compatibility for existing connection records during Mongo rollout. */
20
20
  export declare function analyzeSql(sql: string, driver: Driver): SqlAnalysis;
21
+ export interface CountStatement {
22
+ sql: string;
23
+ params: unknown[];
24
+ }
25
+ /** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
26
+ export declare function matchedRowsCount(analysis: SqlAnalysis, params: SqlParameters, driver: SqlDriver): CountStatement | undefined;
package/dist/src/sql.js CHANGED
@@ -50,13 +50,93 @@ export function analyzeSql(sql, driver) {
50
50
  throw new StateQLError("INVALID_SQL", message);
51
51
  }
52
52
  }
53
+ function parserDatabase(driver) {
54
+ if (driver === "postgres")
55
+ return "Postgresql";
56
+ if (driver === "mysql")
57
+ return "MySQL";
58
+ return "Sqlite";
59
+ }
60
+ /** A COUNT(*) of the rows a single-table UPDATE or DELETE matches, or undefined when it cannot be derived safely. */
61
+ export function matchedRowsCount(analysis, params, driver) {
62
+ const ast = analysis.ast;
63
+ const isUpdate = analysis.statementType === "update";
64
+ const isDelete = analysis.statementType === "delete";
65
+ if (!isUpdate && !isDelete)
66
+ return undefined;
67
+ const tables = isUpdate ? ast.table : ast.from;
68
+ const singleTable = Array.isArray(tables) && tables.length === 1 && !record(tables[0])?.join;
69
+ const limit = record(ast.limit)?.value;
70
+ const hasLimit = Array.isArray(limit) && limit.length > 0;
71
+ if (!Array.isArray(params) || !singleTable)
72
+ return undefined;
73
+ if (ast.with || ast.orderby || hasLimit || (isUpdate && ast.from))
74
+ return undefined;
75
+ // The parser drops NULLS FIRST/LAST, which can change a subquery that also has a LIMIT.
76
+ if (/\bnulls\s+(?:first|last)\b/i.test(analysis.normalized))
77
+ return undefined;
78
+ const where = structuredClone(ast.where ?? null);
79
+ const setPlaceholders = placeholders(ast.set);
80
+ const wherePlaceholders = placeholders(where);
81
+ const placeholderCount = setPlaceholders.length + wherePlaceholders.length;
82
+ if (placeholders(ast).length !== placeholderCount)
83
+ return undefined;
84
+ let countParams;
85
+ if ([...setPlaceholders, ...wherePlaceholders].every(isQuestionMark)) {
86
+ if (params.length !== placeholderCount)
87
+ return undefined;
88
+ countParams = params.slice(setPlaceholders.length);
89
+ }
90
+ else if (driver === "postgres" && wherePlaceholders.every(isNumberedVar)) {
91
+ const renumbered = new Map();
92
+ for (const node of wherePlaceholders) {
93
+ const number = node.name;
94
+ if (!renumbered.has(number))
95
+ renumbered.set(number, renumbered.size + 1);
96
+ node.name = renumbered.get(number);
97
+ }
98
+ countParams = [...renumbered.keys()].map((number) => params[number - 1]);
99
+ }
100
+ else {
101
+ return undefined;
102
+ }
103
+ const select = {
104
+ type: "select",
105
+ columns: [{ expr: { type: "aggr_func", name: "COUNT", args: { expr: { type: "star", value: "*" } } }, as: null }],
106
+ from: tables,
107
+ where,
108
+ };
109
+ return {
110
+ sql: sqlParser().sqlify(select, { database: parserDatabase(driver) }),
111
+ params: countParams,
112
+ };
113
+ }
114
+ function placeholders(node, found = []) {
115
+ if (Array.isArray(node)) {
116
+ for (const item of node)
117
+ placeholders(item, found);
118
+ return found;
119
+ }
120
+ const value = record(node);
121
+ if (!value)
122
+ return found;
123
+ if (value.type === "var" || isQuestionMark(value)) {
124
+ found.push(value);
125
+ return found;
126
+ }
127
+ for (const child of Object.values(value))
128
+ placeholders(child, found);
129
+ return found;
130
+ }
131
+ function isQuestionMark(node) {
132
+ return node.type === "origin" && node.value === "?";
133
+ }
134
+ function isNumberedVar(node) {
135
+ return node.type === "var" && node.prefix === "$" && Number.isInteger(node.name);
136
+ }
53
137
  function parseSqlStatement(sql, driver) {
54
138
  const parser = sqlParser();
55
- const database = driver === "postgres"
56
- ? "Postgresql"
57
- : driver === "mysql"
58
- ? "MySQL"
59
- : "Sqlite";
139
+ const database = parserDatabase(driver);
60
140
  const parserSql = driver === "postgres" ? postgresParserSql(sql) : sql;
61
141
  let parsed;
62
142
  try {
@@ -699,10 +779,10 @@ class UtilityParser {
699
779
  if (this.done())
700
780
  return;
701
781
  while (true) {
702
- if (allowOnlyAndStar)
703
- this.consumeWord("ONLY");
782
+ const only = allowOnlyAndStar && this.consumeWord("ONLY");
704
783
  this.qualifiedIdentifier();
705
- if (allowOnlyAndStar)
784
+ // PostgreSQL accepts ONLY name or name *, never both.
785
+ if (allowOnlyAndStar && !only)
706
786
  this.consumePunctuation("*");
707
787
  if (this.consumePunctuation("(")) {
708
788
  this.identifier();
@@ -1,5 +1,5 @@
1
1
  import { type TableChange } from "./table-editor.js";
2
- import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
2
+ import type { ActorData, ActorLinkData, ActorResolutionData, ActorsData, ActorUnlinkData, AliasData, ApplyData, BatchCommand, CommandExecutionContext, CommandOrigin, BatchOptions, CapabilitiesData, CatalogObject, DescribeObjectData, ListObjectsData, ListObjectsFilter, CloseSessionData, ColumnsData, CommitTransactionData, ConnectOptions, ConnectionData, CountData, DisconnectData, DoctorData, ExecData, ExecOptions, ExecutionOptions, ExportData, FilterOptions, HistoryData, HistoryOptions, OperationData, PlanData, PlanOptions, ProfileData, ProfilesData, ProfileOptions, ProfileUpdateOptions, MongoExecOptions, MongoPlanOptions, MongoQueryOptions, MongoReadCommand, MongoWriteCommand, RedisCommand, RedisExecOptions, RedisPlanOptions, RedisQueryOptions, PurgeData, QueryOptions, RemovedProfileData, Response, ResultData, RollbackTransactionData, RowsData, RowsOptions, Column, SummaryData, StateQLActorOptions, StateQLOptions, StateQLWorkspaceOptions, StateQLSnapshot, StateQLSnapshotOptions, StatusData, SessionData, SessionsData, SessionSummaryData, TransactionData } from "./types.js";
3
3
  export declare class StateQL {
4
4
  /** Runtime contract marker for passwordRef/password_ref support. */
5
5
  static readonly passwordReferenceVersion: 1;
@@ -56,6 +56,7 @@ export declare class StateQL {
56
56
  rows(idOrAlias: string, options?: RowsOptions): Promise<Response<RowsData>>;
57
57
  count(idOrAlias: string): Promise<Response<CountData>>;
58
58
  columns(idOrAlias: string): Promise<Response<ColumnsData>>;
59
+ summarize(idOrAlias: string): Promise<Response<SummaryData>>;
59
60
  setAlias(name: string, id: string): Promise<Response<AliasData>>;
60
61
  /** Owned, full-value pages for host UIs. Reading a page does not add a command to history. */
61
62
  readMaterialized(id: string, options?: RowsOptions & {
@@ -97,7 +98,7 @@ export declare class StateQL {
97
98
  private editableMetadata;
98
99
  private panelResult;
99
100
  private fullResultRows;
100
- exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv"): Promise<Response<ExportData>>;
101
+ exportResult(idOrAlias: string, output: string, format?: "json" | "jsonl" | "csv", columns?: string[]): Promise<Response<ExportData>>;
101
102
  exec(sql: string, options?: ExecOptions): Promise<Response<ExecData>>;
102
103
  mongoExec(command: MongoWriteCommand, options?: MongoExecOptions): Promise<Response<ExecData>>;
103
104
  redisExec(command: RedisCommand, options?: RedisExecOptions): Promise<Response<ExecData>>;
@@ -11,9 +11,9 @@ import { analyzeMongoWriteSafety, deserializeMongoWriteCommand, serializeMongoCo
11
11
  import { deserializeRedisCommand, RedisAdapter, serializeRedisCommand, validateRedisReadCommand, validateRedisWriteCommand, } from "./redis.js";
12
12
  import { filterMaterializedRows, prepareFilterStatement, validateFilterParameters, } from "./filter.js";
13
13
  import { operationData, paginationWarnings, profileData, rowsToCsv, sessionData, transactionData, } from "./response-data.js";
14
- import { analyzeSql } from "./sql.js";
14
+ import { analyzeSql, matchedRowsCount } from "./sql.js";
15
15
  import { StateStore, } from "./store.js";
16
- import { compactRows, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
16
+ import { compactRows, compactValue, defaultHome, hash, isSqlParameters, parseJson, redact, } from "./util.js";
17
17
  const DEFAULT_SNAPSHOT_HISTORY_LIMIT = 50;
18
18
  const MAX_SNAPSHOT_HISTORY_LIMIT = 100;
19
19
  const DEFAULT_CREDENTIAL_RESOLUTION_TIMEOUT_MS = 120_000;
@@ -1019,7 +1019,7 @@ export class StateQL {
1019
1019
  throw new StateQLError("OUTPUT_LIMIT_EXCEEDED", "limit cannot exceed 1000 rows.", { suggestedAction: "Fetch another page or use export." });
1020
1020
  }
1021
1021
  const allRows = this.store.resultRows(result);
1022
- const rows = allRows.slice(offset, offset + limit);
1022
+ const rows = selectColumns(allRows.slice(offset, offset + limit), this.store.resultColumns(result), options.columns);
1023
1023
  return {
1024
1024
  data: {
1025
1025
  result_id: result.id,
@@ -1059,6 +1059,22 @@ export class StateQL {
1059
1059
  confidence: result.state_confidence,
1060
1060
  }));
1061
1061
  }
1062
+ async summarize(idOrAlias) {
1063
+ return this.withResult("summarize", idOrAlias, async (result) => {
1064
+ const rows = this.store.resultRows(result);
1065
+ return {
1066
+ data: {
1067
+ result_id: result.id,
1068
+ total: result.row_count,
1069
+ columns: this.store.resultColumns(result).map((column) => summarizeColumn(column.name, rows, this.maxCellCharacters)),
1070
+ },
1071
+ handle: result.id,
1072
+ cached: true,
1073
+ stateVersion: result.state_version,
1074
+ confidence: result.state_confidence,
1075
+ };
1076
+ });
1077
+ }
1062
1078
  async setAlias(name, id) {
1063
1079
  return this.run("alias.set", async (session) => {
1064
1080
  const result = this.requireResult(id, session);
@@ -1321,14 +1337,15 @@ export class StateQL {
1321
1337
  this.panelRows = { id: result.id, json: result.rows_json, rows: this.store.resultRows(result) };
1322
1338
  return this.panelRows.rows;
1323
1339
  }
1324
- async exportResult(idOrAlias, output, format = "csv") {
1340
+ async exportResult(idOrAlias, output, format = "csv", columns) {
1325
1341
  return this.withResult("export", idOrAlias, async (result) => {
1326
- const rows = this.store.resultRows(result);
1342
+ const resultColumns = this.store.resultColumns(result);
1343
+ const rows = selectColumns(this.store.resultRows(result), resultColumns, columns);
1327
1344
  const content = format === "json"
1328
1345
  ? `${JSON.stringify(rows, null, 2)}\n`
1329
1346
  : format === "jsonl"
1330
1347
  ? `${rows.map((row) => JSON.stringify(row)).join("\n")}\n`
1331
- : rowsToCsv(rows, this.store.resultColumns(result).map((column) => column.name));
1348
+ : rowsToCsv(rows, columns ?? resultColumns.map((column) => column.name));
1332
1349
  writeFileSync(resolve(output), content, "utf8");
1333
1350
  return {
1334
1351
  data: {
@@ -1648,6 +1665,7 @@ export class StateQL {
1648
1665
  const adapter = await this.openAdapter(connection, context, adapterSource);
1649
1666
  try {
1650
1667
  const stateSignature = await adapter.signature();
1668
+ const estimatedRows = await countMatchedRows(adapter, matchedRowsCount(analysis, options.params ?? [], connection.driver));
1651
1669
  const expiresAt = new Date(this.now().getTime() + 10 * 60_000).toISOString();
1652
1670
  const plan = this.store.savePlan({
1653
1671
  sessionId: session.id,
@@ -1681,6 +1699,7 @@ export class StateQL {
1681
1699
  state_version: plan.state_version,
1682
1700
  owner_actor_id: plan.owner_actor_id,
1683
1701
  expires_at: plan.expires_at,
1702
+ ...(estimatedRows === undefined ? {} : { estimated_rows: estimatedRows }),
1684
1703
  },
1685
1704
  handle: plan.id,
1686
1705
  executed: true,
@@ -1985,6 +2004,9 @@ export class StateQL {
1985
2004
  multi_row_table_plans: true,
1986
2005
  history_classification: true,
1987
2006
  actor_display_names: true,
2007
+ result_projection: true,
2008
+ result_summary: true,
2009
+ plan_row_estimates: true,
1988
2010
  },
1989
2011
  driver_features: {
1990
2012
  mongodb: {
@@ -2155,11 +2177,14 @@ export class StateQL {
2155
2177
  return this.rows(batchString(command.handle, "handle"), {
2156
2178
  offset: command.offset ?? 0,
2157
2179
  limit: command.limit ?? 20,
2180
+ ...(command.columns ? { columns: command.columns } : {}),
2158
2181
  });
2159
2182
  case "count":
2160
2183
  return this.count(batchString(command.handle, "handle"));
2161
2184
  case "columns":
2162
2185
  return this.columns(batchString(command.handle, "handle"));
2186
+ case "summarize":
2187
+ return this.summarize(batchString(command.handle, "handle"));
2163
2188
  case "alias.set":
2164
2189
  return this.setAlias(batchString(command.name, "name"), batchString(command.handle, "handle"));
2165
2190
  case "inspect":
@@ -3372,6 +3397,67 @@ function positiveInteger(value, name) {
3372
3397
  return value;
3373
3398
  throw new StateQLError("INVALID_COMMAND", `${name} must be a positive integer.`);
3374
3399
  }
3400
+ function selectColumns(rows, available, selected) {
3401
+ if (!selected)
3402
+ return rows;
3403
+ const names = available.map((column) => column.name);
3404
+ const unknown = selected.filter((name) => !names.includes(name));
3405
+ if (selected.length === 0 || unknown.length > 0) {
3406
+ throw new StateQLError("INVALID_COMMAND", unknown.length > 0 ? `Unknown column: ${unknown.join(", ")}.` : "columns cannot be empty.", { suggestedAction: `Use one or more of: ${names.join(", ")}.` });
3407
+ }
3408
+ // Keep missing keys missing, so MongoDB documents still distinguish missing from null.
3409
+ return rows.map((row) => Object.fromEntries(selected.filter((name) => name in row).map((name) => [name, row[name]])));
3410
+ }
3411
+ function summarizeColumn(name, rows, maxCellCharacters) {
3412
+ const values = rows
3413
+ .map((row) => row[name])
3414
+ .filter((value) => value !== null && value !== undefined);
3415
+ const [min, max] = valueRange(values);
3416
+ return {
3417
+ name,
3418
+ nulls: rows.length - values.length,
3419
+ distinct: new Set(values.map((value) => JSON.stringify(value))).size,
3420
+ min: compactValue(min, maxCellCharacters),
3421
+ max: compactValue(max, maxCellCharacters),
3422
+ };
3423
+ }
3424
+ const NUMERIC_TEXT = /^-?\d+(?:\.\d+)?$/;
3425
+ // Exact numerics (PostgreSQL numeric/bigint, MySQL DECIMAL) arrive as strings, so compare them as numbers.
3426
+ function valueRange(values) {
3427
+ const numeric = values.every((value) => typeof value === "number" || (typeof value === "string" && NUMERIC_TEXT.test(value)));
3428
+ const text = values.every((value) => typeof value === "string");
3429
+ if (values.length === 0)
3430
+ return [null, null];
3431
+ if (!numeric && !text)
3432
+ return [null, null];
3433
+ const compare = numeric
3434
+ ? (left, right) => Number(left) - Number(right)
3435
+ : (left, right) => (String(left) < String(right) ? -1 : String(left) > String(right) ? 1 : 0);
3436
+ let min = values[0];
3437
+ let max = values[0];
3438
+ for (const value of values) {
3439
+ if (compare(value, min) < 0)
3440
+ min = value;
3441
+ if (compare(value, max) > 0)
3442
+ max = value;
3443
+ }
3444
+ return [min, max];
3445
+ }
3446
+ async function countMatchedRows(adapter, count) {
3447
+ if (!count)
3448
+ return undefined;
3449
+ try {
3450
+ const { rows } = await adapter.read(count.sql, count.params);
3451
+ const value = Number(Object.values(rows[0] ?? {})[0]);
3452
+ return Number.isSafeInteger(value) ? value : undefined;
3453
+ }
3454
+ catch (error) {
3455
+ if (error instanceof AdapterExecutionError)
3456
+ throw error;
3457
+ // The estimate is advisory; a count the parser cannot express must not block the plan.
3458
+ return undefined;
3459
+ }
3460
+ }
3375
3461
  async function closeAdapterQuietly(adapter) {
3376
3462
  try {
3377
3463
  await adapter.close();
@@ -337,6 +337,7 @@ export interface RedisPlanOptions extends ExecutionOptions {
337
337
  export interface RowsOptions {
338
338
  offset?: number;
339
339
  limit?: number;
340
+ columns?: string[];
340
341
  }
341
342
  export interface PlanOptions extends ExecutionOptions {
342
343
  params?: SqlParameters;
@@ -347,7 +348,7 @@ export interface MongoPlanOptions extends ExecutionOptions {
347
348
  allowUnbounded?: boolean;
348
349
  allowDestructive?: boolean;
349
350
  }
350
- export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
351
+ export type BatchCommandName = "connect" | "disconnect" | "status" | "actor.show" | "actor.set-name" | "profile.add" | "profile.list" | "profile.show" | "profile.remove" | "profile.update" | "session.start" | "session.list" | "session.show" | "session.summary" | "session.close" | "query" | "filter" | "exec" | "show" | "rows" | "count" | "columns" | "summarize" | "alias.set" | "inspect" | "transaction.begin" | "transaction.status" | "transaction.commit" | "transaction.rollback" | "plan" | "mongo.query" | "mongo.exec" | "mongo.plan" | "redis.query" | "redis.exec" | "redis.plan" | "objects.list" | "object.describe" | "apply" | "history" | "receipt" | "doctor" | "purge" | "capabilities";
351
352
  export interface BatchCommand {
352
353
  command: BatchCommandName;
353
354
  target?: string;
@@ -364,6 +365,7 @@ export interface BatchCommand {
364
365
  object?: CatalogObject;
365
366
  cache?: "auto" | "bypass" | "require";
366
367
  preview_rows?: number;
368
+ columns?: string[];
367
369
  read_only?: boolean;
368
370
  secret_env?: string;
369
371
  credential_ref?: string;
@@ -542,6 +544,18 @@ export interface ColumnsData {
542
544
  result_id: string;
543
545
  columns: Column[];
544
546
  }
547
+ export interface ColumnSummary {
548
+ name: string;
549
+ nulls: number;
550
+ distinct: number;
551
+ min: unknown;
552
+ max: unknown;
553
+ }
554
+ export interface SummaryData {
555
+ result_id: string;
556
+ total: number;
557
+ columns: ColumnSummary[];
558
+ }
545
559
  export interface AliasData {
546
560
  alias: string;
547
561
  result_id: string;
@@ -603,6 +617,8 @@ export interface PlanData {
603
617
  state_version: string;
604
618
  owner_actor_id: string;
605
619
  expires_at: string;
620
+ /** Rows a single-table UPDATE or DELETE matched at plan time; absent when not derivable. */
621
+ estimated_rows?: number;
606
622
  }
607
623
  export interface ApplyData extends ExecData {
608
624
  plan_id: string;
@@ -9,4 +9,5 @@ export declare function isColumns(value: unknown): value is Column[];
9
9
  export declare function isRecord(value: unknown): value is Record<string, unknown>;
10
10
  export declare function redact(value: string): string;
11
11
  export declare function compactRows(rows: Row[], maxCellCharacters: number): Row[];
12
+ export declare function compactValue(value: unknown, max: number): unknown;
12
13
  export declare function toJsonSafe<T>(value: T): T;
package/dist/src/util.js CHANGED
@@ -78,7 +78,7 @@ export function compactRows(rows, maxCellCharacters) {
78
78
  compactValue(value, maxCellCharacters),
79
79
  ])));
80
80
  }
81
- function compactValue(value, max) {
81
+ export function compactValue(value, max) {
82
82
  if (typeof value === "bigint")
83
83
  return value.toString();
84
84
  if (Buffer.isBuffer(value)) {
package/docs/batch.md CHANGED
@@ -42,7 +42,8 @@ stql batch commands.json
42
42
  Batch fields use snake case. Supported command names match CLI paths, such as
43
43
  `actor.show`, `actor.set-name`, `filter`, `transaction.begin`, `session.summary`,
44
44
  `alias.set`, `plan`, and `apply`. `actor.set-name` takes the display name in the
45
- `name` field. Query commands may set `preview_rows` from 0 to 200. Native MongoDB
45
+ `name` field. Query commands may set `preview_rows` from 0 to 200. `rows` may
46
+ set `columns` to an array of column names; `summarize` takes `handle`. Native MongoDB
46
47
  batches use `mongo.query`, `mongo.exec`, or `mongo.plan` with the command object
47
48
  in `mongo`; the same cache, replay, idempotency, safety, and timeout fields
48
49
  apply. Database commands may set `timeout_ms`; otherwise they use the 30-second
package/docs/cli.md CHANGED
@@ -15,25 +15,25 @@ stql profile add|update NAME [TARGET [--ask-password] | --env ENV | --credential
15
15
  [--read-only|--read-write]
16
16
  stql profile list|show|remove
17
17
  stql session start|list|show|summary|close
18
- stql query <sql> [--params JSON | --param VALUE...] [--cache auto|bypass|require]
18
+ stql query <sql> | --file FILE [--params JSON | --param VALUE...] [--cache auto|bypass|require]
19
19
  [--preview-rows 0..200]
20
20
  stql filter <result-handle> <predicate> [--params JSON | --param VALUE...]
21
- stql exec <sql> [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
21
+ stql exec <sql> | --file FILE [--params JSON | --param VALUE...] [--idempotency-key KEY] [--replay]
22
22
  [--allow-unbounded] [--allow-destructive]
23
- stql mongo query|exec|plan '<EJSON command>' [--cache MODE] [--idempotency-key KEY]
23
+ stql mongo query|exec|plan '<EJSON command>' | --file FILE [--cache MODE] [--idempotency-key KEY]
24
24
  [--replay] [--allow-unbounded] [--allow-destructive]
25
25
  stql redis query '<JSON command>' [--cache auto|bypass|require]
26
26
  stql redis exec '<JSON command>' [--idempotency-key KEY] [--replay]
27
27
  stql redis plan '<JSON command>'
28
- stql show|count|columns <result-handle>
29
- stql rows <result-handle> [--offset N] [--limit N]
28
+ stql show|count|columns|summarize <result-handle>
29
+ stql rows <result-handle> [--offset N] [--limit N] [--columns a,b]
30
30
  stql alias set <name> <result-handle>
31
- stql export <result-handle> --output FILE [--format json|jsonl|csv]
31
+ stql export <result-handle> --output FILE [--format json|jsonl|csv] [--columns a,b]
32
32
  stql inspect schema|table|collection|collections|columns|indexes|constraints [name]
33
33
  stql objects [KIND] [--schema NAME] [--search TEXT] [--offset N|--cursor CURSOR] [--limit N]
34
34
  stql object KIND NAME [IDENTITY] [--schema NAME]
35
35
  stql transaction begin|status|commit|rollback [--isolation LEVEL]
36
- stql plan <sql> [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
36
+ stql plan <sql> | --file FILE [--params JSON | --param VALUE...] [--allow-unbounded] [--allow-destructive]
37
37
  stql apply <plan-handle>
38
38
  stql history [--limit N] [--offset N] [--category statement|introspection|management]
39
39
  [--internal|--external]
@@ -43,7 +43,7 @@ stql purge [expired|results|history|all]
43
43
  stql capabilities
44
44
  stql batch [commands.json|commands.jsonl|-] [--continue-on-error]
45
45
  stql pipe [--continue-on-error]
46
- stql help
46
+ stql help [command]
47
47
  ```
48
48
 
49
49
  Global options: `--output MODE`, `--timeout-ms N`, `--max-cell-characters N`,
@@ -63,6 +63,10 @@ Use `--params JSON` for a JSON array or named parameters. Use
63
63
  `--params-file FILE` when JSON is awkward to quote; `--params-file -` reads
64
64
  JSON from standard input.
65
65
 
66
+ Use `--file FILE` instead of inline text to read the SQL, or the MongoDB or
67
+ Redis command, from a file. `--file -` reads standard input, so it cannot be
68
+ combined with `--params-file -`. A leading UTF-8 BOM is ignored.
69
+
66
70
  ## Catalog inspection
67
71
 
68
72
  Use `objects` to list a bounded page and `object` to describe an entry:
@@ -98,6 +102,8 @@ their complete error object. Empty warnings and tracing metadata are omitted.
98
102
 
99
103
  Agent mode also removes data that costs tokens but adds no information:
100
104
 
105
+ - `summarize` returns `columns` (`name`, `nulls`, `distinct`, `min`, `max`) and
106
+ one row per result column.
101
107
  - `query`, `filter`, `show`, `mongo.query`, and `rows` return `columns` once and
102
108
  each row as an array in that order. When rows have different keys (for
103
109
  example, MongoDB documents), rows stay objects and `columns` is omitted.
@@ -110,7 +116,7 @@ Agent mode also removes data that costs tokens but adds no information:
110
116
  - `capabilities` lists enabled `features` as names.
111
117
  - `objects` returns `columns` once and each entry as an array. `identity` is
112
118
  omitted when it equals `schema.name` (or `name`) for every entry.
113
- - `rows`, `count`, and `columns` do not repeat the handle you passed.
119
+ - `rows`, `count`, `columns`, and `summarize` do not repeat the handle you passed.
114
120
  - Result `handle` is the generated alias, which cannot be reassigned. Full
115
121
  `q_...` IDs work too and appear in `--output json`, `silent`, and history.
116
122
  `alias` is present only when you chose a different name (batch `as`).
package/docs/databases.md CHANGED
@@ -95,8 +95,8 @@ stql plan "REINDEX TABLE public.jobs" --allow-destructive
95
95
 
96
96
  The PostgreSQL 14–18 grammar includes parenthesized `REINDEX CONCURRENTLY`,
97
97
  PostgreSQL 16 `BUFFER_USAGE_LIMIT` for `VACUUM`/`ANALYZE`, optional
98
- `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table *` maintenance
99
- targets. Memory sizes accept an integer number of kilobytes or a quoted
98
+ `DATABASE`/`SYSTEM` reindex names, and PostgreSQL 18 `ONLY table` and `table *`
99
+ maintenance targets (not both on one table). Memory sizes accept an integer number of kilobytes or a quoted
100
100
  `B|kB|MB|GB|TB` value. Older servers may reject newer forms after dispatch, so
101
101
  StateQL retains conservative unknown-outcome handling.
102
102
 
package/docs/library.md CHANGED
@@ -63,7 +63,9 @@ Library responses retain the full response envelope regardless of the CLI
63
63
  output mode. Check `response.ok` before reading `response.data`; failures expose
64
64
  `response.error`. Queries return typed `ResultData` with `result_id`, `preview`,
65
65
  and result metadata. Reuse `result_id` with methods such as `filter`, `rows`,
66
- `count`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
66
+ `count`, `summarize`, and `exportResult`; the CLI instead presents its primary ID as `handle`.
67
+ `rows(id, { columns })` and `exportResult(id, output, format, columns)` return
68
+ only the named columns.
67
69
  Queries preview five rows by default. Set `previewRows` from 0 to 200 on an
68
70
  individual query to control its response without changing or rerunning the
69
71
  materialized result. The constructor-level `previewRows` option changes the
package/docs/results.md CHANGED
@@ -67,6 +67,18 @@ use `results`, `history`, or `all` for explicit session cleanup. On POSIX
67
67
  systems, StateQL removes group and world access from its state directory,
68
68
  database, and SQLite sidecar files.
69
69
 
70
+ ## Column projection and summaries
71
+
72
+ `rows` and `export` accept `--columns a,b` (library: `columns: ["a", "b"]`) to
73
+ return only those columns, in that order. Unknown column names fail with
74
+ `INVALID_COMMAND` and a list of the available columns.
75
+
76
+ `summarize` returns, for each column of a stored result, the null count, the
77
+ distinct count, and the min and max. Min and max are computed only when all
78
+ non-null values are numbers or all are strings. Numeric strings, such as
79
+ PostgreSQL `numeric` values, compare as numbers. Neither command accesses the
80
+ original database.
81
+
70
82
  ## Local filtering
71
83
 
72
84
  `filter` evaluates one scalar SQLite predicate against a stored result. It
package/docs/writes.md CHANGED
@@ -10,6 +10,12 @@ The flags are independent.
10
10
  the flags explicitly supplied when it is created; `apply` never adds
11
11
  authorization.
12
12
 
13
+ For a single-table SQL `UPDATE` or `DELETE` without `ORDER BY` or `LIMIT`,
14
+ `plan` also returns `estimated_rows`: a `COUNT(*)` of the rows that the `WHERE`
15
+ clause matches at plan time. The field is absent for other statements, or when
16
+ the count cannot be derived. Data can change before `apply`, so treat it as an
17
+ estimate; `affected_rows` on `apply` is the real value.
18
+
13
19
  Use an idempotency key to protect retryable writes from duplicate execution:
14
20
 
15
21
  ```bash
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fadhilp/stateql",
3
- "version": "0.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Stateful, agent-oriented database CLI for safe result reuse",
5
5
  "repository": {
6
6
  "type": "git",
@@ -51,14 +51,18 @@ shows saved profiles.
51
51
  4. Read the response (see below). `total` is the full row count, so you do not
52
52
  need a separate `COUNT(*)`.
53
53
  5. More rows: `stql rows <handle> --offset <next_offset> --limit 50`
54
- (default 20, maximum 1000).
54
+ (default 20, maximum 1000). Add `--columns id,email` to return only some
55
+ columns of a wide result.
56
+ To understand the data, run `stql summarize <handle>`: for each column it
57
+ returns the null count, distinct count, min, and max.
55
58
  6. Narrow down: `stql filter <handle> 'CAST(total AS REAL) > ?' --param 100`.
56
59
  This runs locally on the stored rows in SQLite syntax, always with `?`, and
57
60
  returns a new handle. PostgreSQL `numeric`/`bigint` and MySQL `DECIMAL` values
58
61
  are stored as strings (`"7.50"`), and SQLite treats every string as greater
59
62
  than every number, so `total > ?` silently matches all rows. Wrap such
60
63
  columns in `CAST(... AS REAL)`, or filter in SQL with a new query.
61
- 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`).
64
+ 7. Save all rows: `stql export <handle> --output rows.csv` (`--format json|jsonl|csv`,
65
+ optional `--columns`).
62
66
 
63
67
  Use `--preview-rows N` (0 to 200) on `query` to change the preview size. Use
64
68
  `--cache bypass` when data may have changed outside this session; writes made
@@ -72,7 +76,7 @@ through `stql` invalidate the cache automatically.
72
76
 
73
77
  | Field | Meaning |
74
78
  | --- | --- |
75
- | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `show`, `export`. |
79
+ | `handle` | Stable result handle. Pass it to `rows`, `filter`, `count`, `columns`, `summarize`, `show`, `export`. |
76
80
  | `columns` + `rows` | Each row is an array in `columns` order. If rows have different keys (MongoDB documents), rows are objects and `columns` is absent. |
77
81
  | `total` | Rows in the stored result. |
78
82
  | `next_offset` | Present only when more rows exist. Absent means you have every row. |
@@ -96,12 +100,16 @@ through `stql` invalidate the cache automatically.
96
100
 
97
101
  - Put SQL in single quotes. In bash and PowerShell, `"$1"` expands to an empty
98
102
  string and breaks the query.
103
+ - For long SQL, or SQL with quotes, write it to a file and pass
104
+ `--file query.sql` instead of the inline SQL. `--file -` reads standard input.
105
+ This works for `query`, `exec`, `plan`, `stql mongo`, and `stql redis`.
99
106
  - Use parameters instead of string literals, so you do not need quotes inside
100
107
  quotes: `--param 'Ada Lovelace'`.
101
108
  - **Windows PowerShell 5.1** removes the double quotes inside JSON arguments, so
102
109
  `--params '[1]'` is fine but `stql redis query '{"command":"GET"}'` breaks.
103
- Send JSON on standard input instead: `'<one JSON command>' | stql pipe` (see
104
- below), or escape every inner quote as `\"`.
110
+ Send the JSON on standard input instead:
111
+ `'{"command":"GET","args":["a"]}' | stql redis query --file -`, or
112
+ `'<one JSON command>' | stql pipe` (see below).
105
113
 
106
114
  ## Several steps in one call
107
115
 
@@ -168,4 +176,4 @@ before you use `stql mongo` or `stql redis`.
168
176
  | `stql history --limit 10` | Recent commands in this session |
169
177
  | `stql receipt <operation-handle>` | Full record of a write |
170
178
  | `stql session summary` | Open results and recent writes |
171
- | `stql help` | Command syntax |
179
+ | `stql help <command>` | Syntax of one command (`stql help` lists all) |
@@ -43,10 +43,13 @@ Use a plan when the user should review a write before it runs.
43
43
 
44
44
  ```bash
45
45
  stql plan 'DELETE FROM sessions WHERE expires_at < $1' --param 2026-01-01 --allow-destructive
46
- # show the user statement_type, required_overrides, and expires_at
46
+ # show the user statement_type, estimated_rows, required_overrides, and expires_at
47
47
  stql apply <plan-handle>
48
48
  ```
49
49
 
50
+ - `estimated_rows` is the number of rows the `WHERE` clause matched when the
51
+ plan was made. It is present only for single-table `UPDATE` and `DELETE`
52
+ without `ORDER BY`/`LIMIT`. If it is absent, count the rows with a query.
50
53
  - A plan keeps only the approval flags given to `plan`; `apply` never adds any.
51
54
  - If data changed after `plan`, `apply` returns `STALE_PLAN`. Create a new plan.
52
55
  - Plans expire after 10 minutes.