@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.
- package/dist/src/agent-response.js +6 -1
- package/dist/src/cli.js +76 -25
- package/dist/src/index.d.ts +1 -1
- package/dist/src/sql.d.ts +7 -1
- package/dist/src/sql.js +88 -8
- package/dist/src/stateql.d.ts +3 -2
- package/dist/src/stateql.js +92 -6
- package/dist/src/types.d.ts +17 -1
- package/dist/src/util.d.ts +1 -0
- package/dist/src/util.js +1 -1
- package/docs/batch.md +2 -1
- package/docs/cli.md +15 -9
- package/docs/databases.md +2 -2
- package/docs/library.md +3 -1
- package/docs/results.md +12 -0
- package/docs/writes.md +6 -0
- package/package.json +1 -1
- package/skills/stateql/SKILL.md +14 -6
- package/skills/stateql/reference/writes.md +4 -1
|
@@ -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
|
-
|
|
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]
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
package/dist/src/index.d.ts
CHANGED
|
@@ -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
|
|
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
|
-
|
|
703
|
-
this.consumeWord("ONLY");
|
|
782
|
+
const only = allowOnlyAndStar && this.consumeWord("ONLY");
|
|
704
783
|
this.qualifiedIdentifier();
|
|
705
|
-
|
|
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();
|
package/dist/src/stateql.d.ts
CHANGED
|
@@ -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>>;
|
package/dist/src/stateql.js
CHANGED
|
@@ -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
|
|
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,
|
|
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();
|
package/dist/src/types.d.ts
CHANGED
|
@@ -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;
|
package/dist/src/util.d.ts
CHANGED
|
@@ -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.
|
|
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 `
|
|
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 *`
|
|
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
package/skills/stateql/SKILL.md
CHANGED
|
@@ -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:
|
|
104
|
-
|
|
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
|
|
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.
|