superdb-mcp 0.51231.0

package/docs/zq-to-super-upgrades.md

@@ -0,0 +1,408 @@
+---
+name: zq-to-super-upgrades
+description: "Migration guide from zq to SuperDB. Covers all breaking changes and syntax updates."
+superdb_version: "0.51231"
+last_updated: "2026-01-05"
+source: "https://github.com/chrismo/superkit/blob/main/doc/zq-to-super-upgrades.md"
+---
+
+# Upgrading zq to super
+
+This document is designed for AI assistants performing automated upgrades of zq
+scripts to SuperDB. It covers all breaking changes between zq and the current
+SuperDB release.
+
+## Quick Reference
+
+| Category   | zq               | super                       |
+|------------|------------------|-----------------------------|
+| Keyword    | `yield`          | `values`                    |
+| Function   | `parse_zson`     | `parse_sup`                 |
+| Function   | `func`           | `fn`                        |
+| Operator   | `over`           | `unnest`                    |
+| Switch     | `-z` / `-Z`      | `-s` / `-S`                 |
+| Switch     | `-f text`        | `-f line`                   |
+| Switch     | (implicit)       | `-c` required before query  |
+| Comments   | `//`             | `--` or `/* */`             |
+| Regexp     | `/pattern/`      | `'pattern'` (string)        |
+| Cast       | `type(value)`    | `value::type`               |
+| Agg filter | `count() where x`| `count() filter (x)`        |
+
+## CLI Changes
+
+### The `-c` switch is now required
+
+`super` requires a `-c` switch before any query string. `zq` accepted the query
+string as a positional argument.
+
+**OLD:**
+```bash
+echo '{"a":1}' | zq 'yield a' -
+```
+
+**NEW:**
+```bash
+echo '{"a":1}' | super -c 'values a' -
+```
+
+### The `-c` switch must immediately precede the query string
+
+The query must come directly after `-c`. Other flags go before `-c`.
+
+**CORRECT:**
+```bash
+echo '{"a":1}' | super -s -c 'values a' -
+```
+
+**INCORRECT:**
+```bash
+-- This is ILLEGAL - flags cannot go between -c and the query
+echo '{"a":1}' | super -c -s 'values a' -
+```
+
+### When there is no query, do NOT use `-c`
+
+If you're just reformatting data without a query, omit `-c` entirely.
+
+**OLD:**
+```bash
+zq -j input.json
+```
+
+**NEW:**
+```bash
+super -j input.json
+```
+
+**INCORRECT:**
+```bash
+-- This is ILLEGAL - -c requires a query string to follow it
+super -c -j input.json
+```
+
+### Output format switches
+
+- `-f text` → `-f line`
+- `-z` → `-s` (line-oriented Super JSON)
+- `-Z` → `-S` (formatted Super JSON)
+
+### Comments
+
+zq used `//` for single-line comments. SuperDB uses PostgreSQL-compatible syntax:
+- `--` for single-line comments
+- `/* ... */` for multi-line comments
+
+## Simple Renames
+
+### yield → values
+
+```bash
+-- OLD
+zq 'yield {a:1}'
+
+-- NEW
+super -c 'values {a:1}'
+```
+
+### parse_zson → parse_sup
+
+```bash
+-- OLD
+zq 'parse_zson(s)'
+
+-- NEW
+super -c 'parse_sup(s)'
+```
+
+### func → fn
+
+```bash
+-- OLD
+func double(x): ( x * 2 )
+
+-- NEW
+fn double(x): ( x * 2 )
+```
+
+### over → unnest (basic usage)
+
+Simple uses are a direct replacement:
+
+```bash
+-- OLD
+zq 'yield [1,2,3] | over this'
+
+-- NEW
+super -c 'values [1,2,3] | unnest this'
+```
+
+## Behavioral Changes
+
+### Indexing is 0-based (with pragma for 1-based)
+
+0-based indexing is the default. Use `pragma index_base = 1` for SQL-style
+1-based indexing when needed.
+
+```bash
+-- 0-based indexing (default)
+super -s -c "values ['a','b','c'][0]"
+"a"
+```
+
+```bash
+-- 1-based indexing via pragma
+super -s -c "
+pragma index_base = 1
+values ['a','b','c'][1]
+"
+"a"
+```
+
+The pragma affects array/string indexing, slicing, and functions like `SUBSTRING()`.
+
+### unnest with `into` (formerly `=>`)
+
+`over this => (...)` becomes `unnest this into (...)`:
+
+```bash
+-- OLD
+zq 'over arr => ( yield this * 2 )'
+
+-- NEW
+super -c 'unnest arr into ( values this * 2 )'
+```
+
+### unnest with multiple values (formerly `with`)
+
+`over a with b => (...)` becomes `unnest {b,a} into (...)`.
+
+**Warning:** This has behavioral changes. Inside the parentheses, `this` used to
+be just `a` in zq, but now `this` is the record `{b,a}` in super.
+
+### grep requires explicit `this` argument
+
+- Inline regexp (`/.../`) syntax removed — use strings
+- Globs no longer supported in grep
+- `this` must be passed explicitly
+
+```bash
+-- OLD (no longer works)
+zq -z "grep(/a*b/,s)"
+zq -z "yield ['a','b'] | grep(/b/)"
+
+-- NEW
+super -s -c "grep('a.*b', s)"
+super -s -c "values ['a','b'] | grep('b', this)"
+```
+
+### is and nest_dotted require explicit `this`
+
+```bash
+-- OLD (no longer works)
+zq -z "yield 2 | is(<int64>)"
+
+-- NEW
+super -s -c "values 2 | is(this, <int64>)"
+```
+
+`nest_dotted` follows the same pattern.
+
+### Cast syntax changes
+
+Function-style casting (`type(value)`) is no longer supported. Use `::` casting:
+
+```bash
+-- OLD (no longer works)
+zq -z "{a:time('2025-08-28T12:00:00Z')}"
+
+-- NEW (preferred)
+super -s -c "{a:'2025-08-28T12:00:00Z'::time}"
+{a:2025-08-28T12:00:00Z}
+```
+
+Alternative syntaxes (legal but not preferred):
+- `cast(value, <type>)`
+- `CAST(value AS type)`
+
+### Lateral subqueries require array wrapping
+
+Lateral subqueries that produce multiple values must be wrapped in `[...]`:
+
+```bash
+-- OLD (no longer works - produces error)
+super -s -c "[3,2,1] | { a: ( unnest this | values this ) }"
+{a:error("query expression produced multiple values (consider [subquery])")}
+
+-- NEW
+super -s -c "[3,2,1] | { a: [unnest this | values this] }"
+{a:[3,2,1]}
+```
+
+### User-defined operator syntax
+
+**Declaration:** Remove parentheses around parameters.
+
+```bash
+-- OLD
+op myop(a, b): ( ... )
+
+-- NEW
+op myop a, b: ( ... )
+```
+
+**Invocation:** Use space-separated arguments (or `call` keyword).
+
+```bash
+-- OLD
+myop(x, y)
+
+-- NEW
+myop x, y
+-- or: call myop x, y
+```
+
+### FROM vs from separation
+
+Pipe-operator `from` and SQL `FROM` clause are now distinct. Relational FROM
+requires a SELECT clause:
+
+```bash
+-- OLD (no longer works)
+super -c 'from ( from a )'
+
+-- NEW
+super -c 'select * from ( select * from a )'
+```
+
+### Aggregate filter clause
+
+The `where` clause on aggregates changed to SQL-standard `filter`:
+
+```bash
+-- OLD
+count() where grep('bar', this)
+
+-- NEW
+count() filter (grep('bar', this))
+```
+
+## Removed Features
+
+### Streaming aggregation functions
+
+Per-record cumulative aggregations are removed.
+
+**Row numbering** — use the `count` operator:
+
+```bash
+-- OLD: put row_num:=count(this)
+-- NEW:
+super -s -c 'values {a:1},{b:2},{c:3} | count | {row:count,...that}'
+{row:1,a:1}
+{row:2,b:2}
+{row:3,c:3}
+```
+
+**Other aggregations** (`sum`, `avg`, `min`, `max`, `collect`) — use `aggregate`,
+but note it collapses all records:
+
+```bash
+super -s -c 'values {v:10},{v:20},{v:30} | aggregate total:=sum(v)'
+{total:60}
+```
+
+**No replacement exists** for progressive patterns like streaming `collect`:
+
+```bash
+-- OLD (no longer works): yield 1,2,3 | yield collect(this)
+-- produced: [1], [1,2], [1,2,3]
+```
+
+Grouped aggregation (`collect(x) by key`) still works.
+
+### Removed functions
+
+The functions `crop()`, `fill()`, `fit()`, `order()`, and `shape()` have been
+removed. Use cast instead — see Cast syntax changes.
+
+### Inline regexp syntax
+
+`/pattern/` is no longer supported. Use string patterns: `'pattern'`
+
+### Globs in grep
+
+Globs are no longer supported in the `grep` function. Use regex patterns.
+
+## Type Changes
+
+### Count functions return int64
+
+These now return `int64` instead of `uint64`:
+- `count()` function
+- `dcount()` function
+- `uniq` operator count field
+- `count` operator output field
+
+```bash
+-- OLD: returned uint64
+super -s -c "values 1,2,3 | aggregate cnt:=count() | typeof(cnt)"
+<uint64>
+
+-- NEW: returns int64
+super -s -c "values 1,2,3 | aggregate cnt:=count() | typeof(cnt)"
+<int64>
+```
+
+## Advanced/Lake Features
+
+### Robot from f-string syntax
+
+Dynamic data source specification now uses f-string syntax. This is primarily
+relevant when using SuperDB with a lake (database):
+
+```bash
+from f'{pool_name}'
+```
+
+If you previously scanned entities within an array of strings, emulate that with
+`unnest` upstream of the robot from.
+
+## Formatting Conventions for AI Upgraders
+
+When performing upgrades, follow these formatting conventions for consistency:
+
+### Use double quotes for query strings
+
+Single-quoted strings are valid SuperDB syntax, so use double quotes for the
+shell query string to avoid confusion:
+
+```bash
+-- GOOD
+super -s -c "values 'hello'"
+
+-- AVOID (works but confusing)
+super -s -c 'values "hello"'
+```
+
+### Multi-line query formatting
+
+For multi-line queries, use this format:
+
+```bash
+super -j -c "
+  unnest this
+  | cut Id,Name
+" -
+```
+
+- Opening double-quote ends the first line
+- Query content starts on new line, indented 2 spaces from `super`
+- Closing double-quote on its own line, aligned with `super`
+
+### Switch ordering
+
+Place `-c` last, with all other switches before it:
+
+```bash
+super -s -f json -c "values this" input.json
+```

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "superdb-mcp",
+  "version": "0.51231.0",
+  "description": "MCP server for SuperDB - execute SuperSQL queries, version detection, and embedded documentation",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "superdb-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrismo/superdb-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "superdb",
+    "supersql",
+    "data",
+    "query"
+  ],
+  "author": "chrismo",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}