dirsql 0.4.61__tar.gz → 0.4.63__tar.gz

{dirsql-0.4.61 → dirsql-0.4.63}/Cargo.lock

@@ -552,7 +552,7 @@ checksum = "6184e33543162437515c2e2b48714794e37845ec9851711914eec9d308f6ebe8"
 
 [[package]]
 name = "dirsql"
-version = "0.4.61"
+version = "0.4.63"
 dependencies = [
  "assert_cmd",
  "axum",
@@ -600,7 +600,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.4.61"
+version = "0.4.63"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.4.61 → dirsql-0.4.63}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.4.61
+Version: 0.4.63
 Requires-Dist: bin-shim>=0.1
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index

{dirsql-0.4.61 → dirsql-0.4.63}/docs/getting-started.md

@@ -81,11 +81,15 @@ The first run downloads the package (`npx` asks for confirmation — answer
 `y`; `uvx` prints download progress), then prints the result:
 
 ```
-[{"files":3}]
+files
+-----
+3
+
+1 row
 ```
 
 Three files, three rows. That one command scanned the directory, handed
-SQLite one row per file, ran your SQL, and printed the answer as JSON.
+SQLite one row per file, ran your SQL, and printed the answer.
 
 There is no named table here — you never declared one. `'./'` is a
 [path-table](./reference/path-tables.md): a quoted path written where a table
@@ -94,8 +98,9 @@ in. The path *is* the query.
 
 ## 3. Select some columns
 
-The response is always a JSON array of row objects, so from here on we pipe
-it through `jq` to pretty-print. Ask for two columns instead of a count:
+At a terminal `dirsql` prints a table; when its output is piped, it prints a
+JSON array of row objects instead. From here on we pipe it through `jq` to
+pretty-print. Ask for two columns instead of a count:
 
 ::: code-group
 
@@ -151,11 +156,17 @@ folder name), and prints them as a JSON row:
 ```bash
 cat > note.sh <<'EOF'
 #!/usr/bin/env sh
-title=$(sed -n 's/^# //p' "$1" | head -n1)
-author=$(basename "$(dirname "$1")")
-printf '[{"title":%s,"author":%s}]' \
-  "$(jq -Rn --arg t "$title" '$t')" \
-  "$(jq -Rn --arg a "$author" '$a')"
+printf '['
+sep=''
+for f; do
+  title=$(sed -n 's/^# //p' "$f" | head -n1)
+  author=$(basename "$(dirname "$f")")
+  printf '%s{"title":%s,"author":%s}' "$sep" \
+    "$(jq -Rn --arg t "$title" '$t')" \
+    "$(jq -Rn --arg a "$author" '$a')"
+  sep=','
+done
+printf ']'
 EOF
 ```
 
@@ -167,7 +178,7 @@ cat > .dirsql.toml <<'EOF'
 name = "notes"
 ddl     = "CREATE TABLE notes (title TEXT, author TEXT)"
 glob    = "notes/**/*.md"
-on-file = "sh note.sh {path}"
+on-file = "sh note.sh"
 EOF
 ```
 
@@ -176,9 +187,10 @@ Three keys define the table:
 - `glob` selects which files feed the table — every `.md` at any depth under
   `notes/`, relative to the directory the config sits in.
 - `ddl` is ordinary `CREATE TABLE` SQL naming the columns you want to keep.
-- `on-file` is the command run once per matched file; `{path}` is the file's
-  path, and its printed JSON row becomes the file's row. The columns are
-  exactly what it emits — `title` from the heading, `author` from the folder.
+- `on-file` is the command run once for the table, with every matched file's
+  path appended as an argument; the JSON array it prints is the table's rows.
+  The columns are exactly what it emits — `title` from the heading, `author`
+  from the folder.
 
 ## 5. Query the table
 

{dirsql-0.4.61 → dirsql-0.4.63}/docs/howto/columns-from-paths.md

@@ -15,18 +15,21 @@ photos/2024/11/hike.jpg
 photos/2025/01/snow.jpg
 ```
 
-Write a small parser, `pathcols.py`, that turns the path into a row. It
-receives the file's absolute path as its argument and prints a JSON array of
-row objects:
+Write a small parser, `pathcols.py`, that turns each path into a row. It
+receives the matched files' absolute paths as its arguments and prints one
+JSON array of row objects:
 
 ```python
 #!/usr/bin/env python3
 import json, os, sys
 
-parts = sys.argv[1].split(os.sep)
-# .../photos/<year>/<month>/<file>
-print(json.dumps([{"year": parts[-3], "month": parts[-2],
-                   "basename": os.path.basename(sys.argv[1])}]))
+rows = []
+for path in sys.argv[1:]:
+    parts = path.split(os.sep)
+    # .../photos/<year>/<month>/<file>
+    rows.append({"year": parts[-3], "month": parts[-2],
+                 "basename": os.path.basename(path)})
+print(json.dumps(rows))
 ```
 
 Point a table at it in `.dirsql.toml`:
@@ -36,12 +39,12 @@ Point a table at it in `.dirsql.toml`:
 name = "photos"
 ddl     = "CREATE TABLE photos (year TEXT, month TEXT, basename TEXT)"
 glob    = "photos/*/*/*.jpg"
-on-file = "python3 pathcols.py {path}"
+on-file = "python3 pathcols.py"
 ```
 
-The hook emits every column the table has — dirsql injects nothing. `{path}`
-is the matched file's absolute path, one of the placeholders in the
-[command hook contract](../reference/hooks.md#on-file). A column appears only
+The hook emits every column the table has — dirsql injects nothing. The
+matched files' absolute paths arrive as the command's trailing arguments, per
+the [command hook contract](../reference/hooks.md#on-file). A column appears only
 because the DDL declares it *and* the hook emits it.
 
 ## 2. Query the derived columns

{dirsql-0.4.61/packages/python → dirsql-0.4.63}/docs/howto/define-tables.md

@@ -10,16 +10,19 @@ persist across restarts, instead of repeating an ad-hoc
 Suppose your blog posts live under `posts/`, one markdown file each. A named
 table needs three keys: a `glob` that selects the files, a `ddl` that names
 the columns, and an [`on-file`](../reference/config.md#table) hook that emits
-each file's rows. Put a small parser next to the config — `extract.py`, which
-reads a post's title line and prints a JSON array of row objects:
+the table's rows. Put a small parser next to the config — `extract.py`, which
+reads each post's title line and prints one JSON array of row objects:
 
 ```python
 #!/usr/bin/env python3
 import json, os, sys
 
-text = open(sys.argv[1], encoding="utf-8").read()
-title = next((l[2:].strip() for l in text.splitlines() if l.startswith("# ")), None)
-print(json.dumps([{"title": title, "slug": os.path.basename(sys.argv[1])[:-3]}]))
+rows = []
+for path in sys.argv[1:]:
+    text = open(path, encoding="utf-8").read()
+    title = next((l[2:].strip() for l in text.splitlines() if l.startswith("# ")), None)
+    rows.append({"title": title, "slug": os.path.basename(path)[:-3]})
+print(json.dumps(rows))
 ```
 
 Then declare the table in `.dirsql.toml`:
@@ -29,15 +32,15 @@ Then declare the table in `.dirsql.toml`:
 name = "posts"
 ddl     = "CREATE TABLE posts (title TEXT, slug TEXT)"
 glob    = "posts/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ```
 
 - `glob` selects the files: every `.md` under `posts/`, at any depth, relative
   to the directory containing the config.
 - `ddl` is a plain SQLite `CREATE TABLE` naming the columns you want to keep.
 - `on-file` is **required** — it is where the table's rows come from. dirsql
-  injects nothing; the hook emits every column, reading the file (it has
-  `{path}`) and deriving whatever it needs. A `[[table]]` with no `on-file` is
+  injects nothing; the hook emits every column, reading the files (their
+  paths are its arguments) and deriving whatever it needs. A `[[table]]` with no `on-file` is
   a [config error](../reference/config.md#parse-errors). For plain stat
   columns with no code, query the path directly with a path-table instead.
 
@@ -75,7 +78,7 @@ two triggers:
 [[table]]
 name    = "posts"
 glob    = "posts/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE posts (title TEXT, slug TEXT, body TEXT);
 CREATE INDEX posts_slug ON posts(slug);

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/howto/extract-from-contents.md

@@ -21,11 +21,11 @@ stdout works. With [`jq`](https://jqlang.org/):
 name = "books"
 ddl     = "CREATE TABLE books (title TEXT, author TEXT, year INTEGER)"
 glob    = "books/*.json"
-on-file = "jq -c '[{title, author, year}]' {path}"
+on-file = "jq -c -n '[inputs | {title, author, year}]'"
 ```
 
-`{path}` is the matched file's absolute path — one of the
-placeholders defined by the
+The command runs once for the table, with every matched file's absolute path
+appended as an argument, and prints one array for all of them — the
 [command hook contract](../reference/hooks.md#on-file), which also covers
 the argv splitting, working directory, stdout protocol, and timeout shared
 by every hook.
@@ -45,7 +45,7 @@ dirsql query "SELECT title, author, year FROM books ORDER BY year" -c ./.dirsql.
 
 The table's columns are exactly what the command emits, narrowed to the DDL —
 `dirsql` adds nothing. To include the file's `path`, have the command emit it
-(it has `{path}`); dirsql will not merge it in for you.
+(it has the path); dirsql will not merge it in for you.
 
 ## Multiple rows per file
 
@@ -57,7 +57,7 @@ row per line, slurp it:
 name = "events"
 ddl     = "CREATE TABLE events (event TEXT, user TEXT)"
 glob    = "logs/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 ```
 
 ```bash

{dirsql-0.4.61 → dirsql-0.4.63}/docs/howto/parse-files-into-columns.md

@@ -32,40 +32,43 @@ To get them, you need a parser.
 
 ## 2. Attach a parser with `--on-file`
 
-Any program that reads one file and prints a **JSON array of row objects** on
-stdout is a parser. Here is a small one, `extract.py`, that reads a post's
-frontmatter:
+Any program that reads the files named by its arguments and prints a **JSON
+array of row objects** on stdout is a parser. Here is a small one,
+`extract.py`, that reads each post's frontmatter:
 
 ```python
 #!/usr/bin/env python3
 import json, re, sys
 
-text = open(sys.argv[1], encoding="utf-8").read()
-m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
-fields = dict(
-    (k.strip(), v.strip())
-    for k, _, v in (line.partition(":") for line in (m.group(1).splitlines() if m else []))
-)
-print(json.dumps([{"title": fields.get("title"), "author": fields.get("author")}]))
+rows = []
+for path in sys.argv[1:]:
+    text = open(path, encoding="utf-8").read()
+    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    fields = dict(
+        (k.strip(), v.strip())
+        for k, _, v in (line.partition(":") for line in (m.group(1).splitlines() if m else []))
+    )
+    rows.append({"title": fields.get("title"), "author": fields.get("author")})
+print(json.dumps(rows))
 ```
 
 Point the path-table at it with `--on-file`:
 
 ```bash
 dirsql query "SELECT title, author FROM './posts/*.md' ORDER BY title" \
-  --on-file 'python3 extract.py {path}'
+  --on-file 'python3 extract.py'
 ```
 
 ```json
 [{"author":"Ada Lovelace","title":"Hello World"},{"author":"Alan Turing","title":"On Recursion"}]
 ```
 
-Now the parser's output *is* the table. `--on-file` runs the command once per
-matched file; `{path}` is the file's absolute path, one of the placeholders in
-the shared [`on-file` hook contract](../reference/hooks.md#on-file) (argv
-splitting, timeout, and per-file failure isolation all come from there). The
-stat columns are no longer reachable — a parser that wants the path emits it,
-since it already has `{path}`. See
+Now the parser's output *is* the table. `--on-file` runs the command once,
+with every matched file's absolute path appended as an argument, under the
+shared [`on-file` hook contract](../reference/hooks.md#on-file) (argv
+splitting, timeout, and failure semantics all come from there). The stat
+columns are no longer reachable — a parser that wants the path emits it, since
+it already has the path. See
 [Parsing rows with `--on-file`](../reference/path-tables.md#parsing-rows-with-on-file)
 for the full behavior.
 
@@ -87,7 +90,7 @@ command in verbatim:
 name = "posts"
 ddl     = "CREATE TABLE posts (title TEXT, author TEXT)"
 glob    = "posts/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ```
 
 The `on-file` value is byte-for-byte the string you passed to `--on-file`. The
@@ -109,7 +112,7 @@ indexed on build, kept fresh by the watcher, survives restarts with
 [many tables](./define-tables.md) — each with its own `on-file` — where the flag
 gives every path-table one parser. In both spellings the table's columns are
 exactly what the parser emits: `dirsql` merges no filesystem facts back on. A
-row that needs the file's `path` emits it (the parser has `{path}`).
+row that needs the file's `path` emits it (the parser has the path).
 
 ## Going further
 

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/howto/react-to-changes.md

@@ -17,7 +17,7 @@ prints each file's basename:
 name = "files"
 ddl     = "CREATE TABLE files (basename TEXT)"
 glob    = "**/*"
-on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
+on-file = '''sh -c 'printf "["; sep=""; for p; do printf "%s{\"basename\":\"%s\"}" "$sep" "${p##*/}"; sep=","; done; printf "]"' sh'''
 ```
 
 ## 1. Open the stream

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/howto/search-indexes.md

@@ -31,7 +31,7 @@ external-content index beside the row table and let the two triggers feed it:
 [[table]]
 name    = "notes"
 glob    = "notes/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 
@@ -150,7 +150,7 @@ inserted vector for the "embedding" column. Expected 8 dimensions but received 4
 [[table]]
 name    = "notes"
 glob    = "notes/**/*.md"
-on-file = "python3 extract.py {path}"
+on-file = "python3 extract.py"
 ddl     = '''
 CREATE TABLE notes (slug TEXT, title TEXT, body TEXT);
 

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/howto/skip-files.md

@@ -25,7 +25,7 @@ ignore = ["notes/drafts/**", "**/*.tmp"]
 name = "notes"
 ddl     = "CREATE TABLE notes (basename TEXT)"
 glob    = "notes/**/*"
-on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
+on-file = '''sh -c 'printf "["; sep=""; for p; do printf "%s{\"basename\":\"%s\"}" "$sep" "${p##*/}"; sep=","; done; printf "]"' sh'''
 ```
 
 Patterns match against root-relative paths, the same way table globs do. An

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/howto/write-a-plugin.md

@@ -60,11 +60,12 @@ its `embed()` SQL function),
 and [`ignore`](../reference/config.md#dirsql-keys).
 
 There are **no plugin-specific keys and no plugin-specific restrictions**. The
-config schema is content-only: the index `root` and `--persist` are
-[runner-owned flags](../reference/config.md#dirsql-keys) (`--root`, `--persist
-[PATH]`), decided by whoever runs `dirsql`, never by a config file — so a
-plugin has nothing to say about them. Whatever you can put in your own
-`.dirsql.toml`, a plugin can put in its fragment, and vice-versa.
+config schema is content-only: the index root and persistence are
+[runner-owned](../reference/config.md#dirsql-keys) — the root is the directory
+`dirsql` is run from (or an SDK's explicit `root`), persistence is the
+`--persist [PATH]` flag — decided by whoever runs `dirsql`, never by a config
+file, so a plugin has nothing to say about them. Whatever you can put in your
+own `.dirsql.toml`, a plugin can put in its fragment, and vice-versa.
 
 ## Hook commands
 
@@ -72,11 +73,11 @@ Both hook command styles from the [hook contract](../reference/hooks.md) work
 in a plugin fragment:
 
 - **Console scripts** — a `bin`-style entry point your package installs on
-  `PATH` (`embed-file {path} {root}`). Recommended for published plugins: the command
+  `PATH` (`embed-file {root}`). Recommended for published plugins: the command
   is bound to your package's interpreter and dependencies, and it is
   language-neutral (the fragment names a command, not a Python file).
 - **Relative scripts** — a path resolved against the fragment's own directory
-  (`uv run python embed.py {path}`). Convenient while developing the plugin
+  (`uv run python embed.py {root}`). Convenient while developing the plugin
   in-tree.
 
 Two facts from the [execution contract](../reference/hooks.md#execution-contract)
@@ -84,12 +85,12 @@ matter most for a published plugin:
 
 - **A hook runs in its declaring config's directory.** For a plugin that is
   the installed fragment's directory — inside **site-packages**. That is a
-  read-only, shared location: **run from it, never write to it.** Use the
-  absolute [`{path}`](../reference/hooks.md#on-file) placeholder to read the
-  matched file, and [`{root}`](../reference/hooks.md#on-file) to reach the
-  user's project directory. Write any cache to `{root}` or a real cache dir,
+  read-only, shared location: **run from it, never write to it.** Read the
+  matched files from the absolute paths the hook appends as arguments, and use
+  [`{root}`](../reference/hooks.md#on-file) to reach the user's project
+  directory. Write any cache to `{root}` or a real cache dir,
   never next to the fragment.
-- **`{path}` is absolute and `{root}` is the index root**, so a command is
+- **The paths are absolute and `{root}` is the index root**, so a command is
   self-sufficient from any working directory — it works whether the plugin
   lives in the project or in site-packages.
 
@@ -111,28 +112,30 @@ entrypoint = "sqlite3_vec_init"
 name = "notes"
 ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
 glob    = "notes/*.md"
-on-file = "uv run --with model2vec python embed.py {path} {root}"
+on-file = "uv run --with model2vec python embed.py {root}"
 ```
 
-`embed.py` turns one file into one row carrying its path, text, and embedding.
-dirsql injects no columns, so the script emits the path itself, from the
-`{path}`/`{root}` the hook passes in:
+`embed.py` turns each file into one row carrying its path, text, and
+embedding. dirsql injects no columns, so the script emits the path itself,
+from the `{root}` the hook passes in and the paths it appends:
 
 ```python
-"""Embed one file's text; print a dirsql row array on stdout."""
+"""Embed each file's text; print one dirsql row array on stdout."""
 import json
 import os
 import sys
 
 from model2vec import StaticModel
 
-path, root = sys.argv[1], sys.argv[2]
-text = open(path, encoding="utf-8").read()
+root, paths = sys.argv[1], sys.argv[2:]
+texts = [open(path, encoding="utf-8").read() for path in paths]
 model = StaticModel.from_pretrained("minishlab/potion-base-8M")
-vector = model.encode([text])[0]
-row = {"path": os.path.relpath(path, root), "text": text,
-       "embedding": json.dumps([round(float(x), 6) for x in vector])}
-print(json.dumps([row]))
+rows = [
+    {"path": os.path.relpath(path, root), "text": text,
+     "embedding": json.dumps([round(float(x), 6) for x in vector])}
+    for path, text, vector in zip(paths, texts, model.encode(texts))
+]
+print(json.dumps(rows))
 ```
 
 The relative `embed.py` above resolves against the fragment directory, which

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/plugins.md

@@ -93,9 +93,10 @@ scope.
 ### Vector cache
 
 Computed vectors are cached at `~/.cache/dirsql/embeddings/` (respecting
-`XDG_CACHE_HOME`), keyed on the SHA-256 of the value bytes plus the model
-identifier. Changing either recomputes — switching models never serves stale
-vectors — and re-running a query over unchanged files is cache hits all the
-way. There is no eviction: the directory is **safe to wipe at any time**; the
-only cost is re-embedding. The cache never lives inside a queried tree — the
-worker writes nothing into the directories you query.
+`XDG_CACHE_HOME`): one SQLite database per model identifier, each row keyed
+on the SHA-256 of the value bytes. Changing the value or the model recomputes
+— switching models never serves stale vectors — and re-running a query over
+unchanged files is cache hits all the way, a whole batch answered by one
+query. There is no eviction: the directory is **safe to wipe at any time**;
+the only cost is re-embedding. The cache never lives inside a queried tree —
+the worker writes nothing into the directories you query.

{dirsql-0.4.61 → dirsql-0.4.63}/docs/reference/cli.md

@@ -1,11 +1,13 @@
 # CLI
 
-Query is the default: `dirsql "<sql>"` runs one query and prints JSON rows.
+Query is the default: `dirsql "<sql>"` runs one query and prints the rows —
+a table at a terminal, a JSON array when piped (see
+[Output format](#output-format)).
 The `dirsql` binary has these modes:
 
 | Invocation | Behavior |
 |---|---|
-| `dirsql "<sql>"` | Run one query over the directory and print the rows as JSON. The default; identical to `dirsql query "<sql>"`. |
+| `dirsql "<sql>"` | Run one query over the directory and print the rows. The default; identical to `dirsql query "<sql>"`. |
 | `dirsql query "<sql>"` | Explicit synonym for the default one-shot query. |
 | `dirsql server` | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
 | `dirsql init` | Generate a `.dirsql.toml`. |
@@ -53,7 +55,7 @@ pipeline, same flags, same output. See that section for config discovery,
 
 ```bash
 dirsql
-# dirsql 0.2.7 — this directory is a database.
+# dirsql <version> — this directory is a database.
 #
 #   SELECT basename, size FROM './' ORDER BY size DESC LIMIT 5;
 #   SELECT path FROM './**/*.md' WHERE content LIKE '%TODO%';
@@ -331,9 +333,10 @@ is a hard error — `error: the subcommand 'query' cannot be used with
 for the server they follow the subcommand: `dirsql server -c <cfg>`.)
 :::
 
-The subcommand builds the index, runs the SQL, prints the result rows as a
-JSON array on stdout (byte-identical to the [`POST /query`](./http-api.md)
-response body), and exits `0`.
+The subcommand builds the index, runs the SQL, prints the result rows on
+stdout — a table at a terminal, otherwise a JSON array byte-identical to the
+[`POST /query`](./http-api.md) response body (see
+[Output format](#output-format)) — and exits `0`.
 
 `dirsql query` is a thin adapter over the **same query pipeline the server
 uses**, so behavior is identical to `POST /query` by construction:
@@ -367,12 +370,12 @@ array of row objects) instead of the stat columns:
 
 ```sh
 dirsql query "SELECT title, author FROM './posts/*.md'" \
-  --on-file 'extract.py {path}'
+  --on-file 'extract.py'
 ```
 
 The command follows the [`on-file` hook contract](./hooks.md#on-file) — argv
-splitting, `{path}`/`{root}` placeholders, per-file failure isolation, and the
-timeout. The parser's output is the whole schema; the stat columns are not
+splitting, the `{root}` placeholder, every matched path as a trailing
+argument, the failure semantics, and the timeout. The parser's output is the whole schema; the stat columns are not
 reachable on a parsed path-table. `--on-file` may be given **at most once** (a
 repeat is an error pointing at config files) and never touches config-declared
 tables. It is a `query`-only flag — server mode rejects it as an unknown
@@ -413,7 +416,7 @@ The output does **not** auto-load. Once you've tweaked it, pass it explicitly
 to run against it:
 
 ```bash
-dirsql "SELECT * FROM files" -c ./.dirsql.toml
+dirsql "SELECT * FROM records" -c ./.dirsql.toml
 ```
 
 ### Flags

{dirsql-0.4.61/packages/python → dirsql-0.4.63}/docs/reference/columns.md

@@ -12,8 +12,8 @@ A named [`[[table]]`](./config.md#table) — or an SDK
 [`on-file` hook](./hooks.md#on-file) emits, narrowed to the columns the DDL
 declares. dirsql adds nothing on top: no `path`, no `size`, no value derived
 from the filename. A hook that wants any of those computes them itself. The
-hook receives the file's `{path}` (an SDK `on_file` callback receives the same
-path as its argument) and may stat or read the file however it likes.
+hook receives every matched file's path as an argument (an SDK `on_file`
+callback receives one path) and may stat or read the files however it likes.
 
 The hook is **required**. A `[[table]]` with no `on-file` is a
 [config-load error](./config.md#parse-errors): with nothing supplying columns,
@@ -58,12 +58,12 @@ ORDER BY mtime DESC;
 [Attaching a parser](./path-tables.md#parsing-rows-with-on-file) to a
 path-table with `--on-file` **replaces** these stat columns with the parser's
 own output — the two modes stay cleanly separate, exactly as for a named
-table. A parser that wants the path emits it; it has `{path}`.
+table. A parser that wants the path emits it; it has the paths.
 
 ## Deriving columns from the path
 
 To turn path segments (an author, a year, a thread id) into columns, a hook
-splits `{path}` and emits the pieces — the same as any other column it
+splits the path and emits the pieces — the same as any other column it
 produces. dirsql does not do this for you: a `{name}` segment in a glob is
 rewritten to `*` and matches a single path segment, but captures no value.
 [Derive columns from file paths](../howto/columns-from-paths.md) walks a

{dirsql-0.4.61/packages/rust → dirsql-0.4.63}/docs/reference/config.md

@@ -221,12 +221,12 @@ what its required `on-file` command emits — dirsql injects nothing (see
 | `name` | yes | The table's SQL name — the name you query it by. Declared, never derived from `ddl`: dirsql does not read the DDL text. The `ddl` must create a table by this name; if it doesn't, loading fails. |
 | `ddl` | yes | A SQL batch, run verbatim — any number of statements. It must create a table called `name`; that table holds the file rows, and only the columns it declares are kept (keys the `on-file` command emits that are not declared are dropped). The rest of the batch is yours: indexes, virtual tables, triggers. See [Batch `ddl`](#batch-ddl). |
 | `glob` | yes | Glob pattern matched against root-relative paths. Every table whose glob matches a file receives that file's rows — a file can populate multiple tables. A `{name}` segment is rewritten to `*` (it matches one path segment but captures nothing). |
-| `on-file` | **yes** | A command run once per matched file; its stdout (a JSON array of row objects) becomes the file's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
+| `on-file` | **yes** | A command run once per table, with every matched file's absolute path appended as a trailing argument; its stdout (one JSON array of row objects) is the table's rows. Must be non-empty. A `[[table]]` with no `on-file` is a load error (see [parse errors](#parse-errors)). See [Command hooks](./hooks.md#on-file). |
 | `strict` | no (default `false`) | When `true`, rows whose keys do not exactly match the declared columns are rejected with an error: extra keys error, and every declared column must be supplied by the `on-file` output. When `false`, extra keys are dropped and missing columns become `NULL`. |
 
 `on-file` is required because a table's rows come from nowhere else. dirsql
 does not read file contents or merge filesystem facts on your behalf: the
-command reads the file (it receives `{path}`) and prints the rows, and those
+command reads the files (it receives their paths as arguments) and prints the rows, and those
 rows — filtered to the DDL — are the table. For plain stat columns with no
 command, query the path directly with a [path-table](./path-tables.md)
 instead of declaring a table.
@@ -236,13 +236,13 @@ instead of declaring a table.
 name = "comments"
 ddl     = "CREATE TABLE comments (path TEXT, author TEXT, body TEXT)"
 glob    = "_comments/*/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 
 [[table]]
 name = "papers"
 ddl     = "CREATE TABLE papers (paper_id TEXT, title TEXT)"
 glob    = "**/meta.json"
-on-file = "uv run python extract_papers.py {path}"
+on-file = "uv run python extract_papers.py"
 strict  = true
 ```
 
@@ -255,7 +255,7 @@ statement:
 [[table]]
 name    = "messages"
 glob    = "sessions/*/messages/*.json"
-on-file = "jq -c '.' {path}"
+on-file = "jq -c -s add"
 ddl     = '''
 CREATE TABLE messages (session TEXT, idx INT, role TEXT, text TEXT);
 CREATE INDEX messages_session ON messages(session);
@@ -419,11 +419,11 @@ timeout       = "600s"
 name = "comments"
 ddl     = "CREATE TABLE comments (author TEXT, body TEXT)"
 glob    = "_comments/*/*.jsonl"
-on-file = "jq -c -s '.' {path}"
+on-file = "jq -c -s '.'"
 
 [[table]]
 name = "documents"
 ddl     = "CREATE TABLE documents (title TEXT, summary TEXT)"
 glob    = "**/index.md"
-on-file = "uv run python extract_doc.py {path}"
+on-file = "uv run python extract_doc.py"
 ```