dirsql 0.4.65 → 0.4.67

package/README.md

@@ -2,7 +2,7 @@
 
 Ephemeral SQL index over a local directory. `dirsql` watches a filesystem, ingests structured files into an in-memory SQLite database, and exposes a SQL query interface -- the filesystem is always the source of truth. Built on the Rust core via napi-rs bindings.
 
-[Documentation](https://thekevinscott.github.io/dirsql/?lang=typescript)
+[Documentation](https://dirsql.dev/?lang=typescript)
 
 Also available as [`dirsql` on crates.io](https://crates.io/crates/dirsql) and [`dirsql` on PyPI](https://pypi.org/project/dirsql/).
 
@@ -89,7 +89,7 @@ Each event has `.action` (`'insert'` | `'update'` | `'delete'` | `'error'`), `.t
 
 ## CLI
 
-`npx dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `npx dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI reference](https://thekevinscott.github.io/dirsql/reference/cli).
+`npx dirsql "<sql>"` runs one query and prints the rows as JSON — the default. `npx dirsql server` starts an HTTP server exposing the SDK over HTTP: `POST /query` for SQL and `GET /events` for a Server-Sent Events change stream. Requires **Node >= 20.11**. See the [CLI reference](https://dirsql.dev/reference/cli).
 
 ## License
 

package/docs/getting-started.md

@@ -156,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
 ```
 
@@ -172,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
 ```
 
@@ -181,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
 

package/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

package/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);

package/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

package/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
 

package/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

package/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);
 

package/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

package/docs/howto/write-a-plugin.md

@@ -73,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)
@@ -85,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.
 
@@ -112,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

package/docs/reference/cli.md

@@ -370,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

package/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

package/docs/reference/config.md

@@ -24,7 +24,7 @@ the config file's location. See [`--config`](./cli.md#flags).
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
+| `ignore` | array of strings | `[]` | Glob patterns matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. Matched files are skipped entirely — excluded from the initial scan and from watch events. |
 
 There is no timeout key. `on-file` hook runs are unbounded; to bound one, wrap
 its command in `timeout(1)` (see [Command hooks](./hooks.md#bounding-a-hook)).
@@ -43,6 +43,16 @@ directory.
 ignore = ["node_modules/**", ".git/**"]
 ```
 
+### Glob rule
+
+Every glob in dirsql — `ignore`, a `[[table]]`'s `glob`, and a
+[path-table](./path-tables.md#writing-the-path) — reads as the shell does:
+`*` and `?` match within one path segment and never cross `/`; `**` matches
+any depth. So `ignore = ["*"]` hides only the files directly inside the root,
+`ignore = ["build/*"]` hides `build/a.o` but not `build/sub/b.o`, and
+`glob = "*.json"` selects only the top-level `.json` files; write
+`**/*.json` to select them at every depth.
+
 Persistence is not a config key. Keep the SQLite index on disk between runs
 with the [`--persist [PATH]` CLI flag](./cli.md#dirsql-server) — a machine-local
 operational choice that belongs to the runner, not to shareable config.
@@ -220,13 +230,13 @@ 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). |
+| `glob` | yes | Glob pattern matched against root-relative paths, under the [one glob rule](#glob-rule): `*` matches one level, `**` any depth. 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 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 +246,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 +265,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 +429,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"
 ```

package/docs/reference/hooks.md

@@ -10,7 +10,7 @@ external command under the execution contract below.
 
 The command string is split into an argv with shell-like quoting: whitespace
 separates arguments, and single or double quotes group them (so
-`sh -c 'grep foo {path} | sort'` keeps the quoted script as a single
+`sh -c 'grep foo "$@" | sort' sh` keeps the quoted script as a single
 argument). **No shell is invoked** — there is no globbing, piping, `$VAR`
 expansion, or `&&`/`;` chaining. To get shell features, ask for a shell
 explicitly with `sh -c '…'`.
@@ -65,7 +65,7 @@ bound a hook, make the bound part of the command by wrapping it in
 `timeout(1)`:
 
 ```toml
-on-file = "timeout 30 my-extractor {path}"
+on-file = "timeout 30 my-extractor"
 ```
 
 When the wrapper kills an overrunning command, the run exits non-zero and
@@ -117,9 +117,14 @@ flag is the inline form, the config key the declared form (see
 [Parse your files into columns](../howto/parse-files-into-columns.md)). In both
 spellings the table's columns are exactly what the command emits, narrowed to
 the DDL — `dirsql` injects no filesystem facts either way. A command that wants
-the path or stat metadata emits it (it has `{path}`).
+the path or stat metadata emits it (it has the paths).
 
 | Placeholder | Value |
 |---|---|
-| `{path}` | The matched file's **absolute** path. `on-file = "extract.py {path}"` — self-sufficient from any working directory, so the command resolves it even when the config lives outside the index. |
-| `{root}` | The index root directory. Derive a root-relative path with `relpath({path}, {root})`. |
+| `{root}` | The index root directory. Derive a root-relative path with `relpath(path, {root})`. |
+
+The matched files' **absolute** paths are not placeholders: they are appended
+to the command as trailing arguments, after everything written in the
+command, so `on-file = "extract.py"` receives them as `sys.argv[1:]` — one run
+per table, self-sufficient from any working directory. A command that still
+spells `{path}` is rejected at startup.

package/docs/reference/path-tables.md

@@ -47,8 +47,13 @@ beneath it; the non-recursive form is spelled explicitly with `*`.
 | `'./docs/**/*.md'` | markdown files at any depth under `docs/` |
 | `'./notes/today.md'` | exactly that one file — one file is one row |
 
-A path containing `*`, `?` or `[` is a glob and is used exactly as written: `*`
-matches within a single directory, `**` crosses directories.
+A path containing `*`, `?`, `[` or `{` is a glob and is used exactly as
+written: `*` matches within a single directory, `**` crosses directories.
+
+The scan starts at the last directory named outright before the first glob
+component -- `'./small/*.md'` walks `small/` and nothing else -- so a query
+over one directory costs what `find ./small` costs, however large the
+directories beside it.
 
 A path naming a single file yields exactly one row. dirsql never splits a file
 into rows on its own — that is what a table's `on_file` hook is for.
@@ -139,18 +144,18 @@ the `dirsql query` flag [`--on-file`](/reference/cli):
 
 ```sh
 dirsql query "SELECT title, author FROM './posts/*.md'" \
-  --on-file 'extract.py {path}'
+  --on-file 'extract.py'
 ```
 
-The command runs once per matched file and prints a JSON array of row objects,
-exactly like a declared table's [`on-file` hook](/reference/hooks) — same argv
-splitting, same `{path}`/`{root}` placeholders, same timeout. Its output *is*
-the table:
+The command runs once, with every matched file's absolute path appended as an
+argument, and prints one JSON array of row objects, exactly like a declared
+table's [`on-file` hook](/reference/hooks) — same argv splitting, same `{root}`
+placeholder, same timeout. Its output *is* the table:
 
 - **The parser supplies the whole schema.** Columns are inferred from the keys
   across the emitted rows. The stat columns (`path`, `size`, …) are **not**
   reachable on a parsed path-table — a parser that wants the path emits it (it
-  has `{path}`). The two modes stay cleanly separate.
+  has the paths). The two modes stay cleanly separate.
 - **Failures are isolated per file.** A file whose parser fails (spawn, non-zero
   exit, timeout, or no output) or whose output is not a JSON array of rows
   contributes no rows; a one-line warning naming the file goes to stderr and the
@@ -186,8 +191,9 @@ bug to design around.
 The table itself is per-connection: it lives in `temp`, so it cannot leak into
 `sqlite_master` or survive a restart. Under `--persist` a *parsed* table's rows
 outlive the connection in the cache (above), but the table is still minted
-fresh each run and the scan still decides what exists. The reserved top-level
-`.dirsql/` directory is excluded from the scan, as everywhere else.
+fresh each run and the scan still decides what exists. A `.dirsql/` directory
+at the top of the directory the scan starts in is reserved and excluded, as
+everywhere else.
 
 ### When to promote to a declared table
 
@@ -207,7 +213,9 @@ choice is stated as one trade in
 ## Skip rules
 
 A path-table scan applies the same [`ignore`](/reference/config) patterns your
-declared tables use, plus two built-in defaults so a zero-config
+declared tables use — matched against root-relative paths under the same
+[glob rule](/reference/config#glob-rule) as the path itself, `*` one level and
+`**` any depth — plus two built-in defaults so a zero-config
 `SELECT * FROM './'` does not drown in machinery:
 
 - `**/node_modules/**`
@@ -234,8 +242,8 @@ defaults and configured `ignore` patterns still apply.
 
 ### Naming a skipped directory
 
-Skip rules are judged on the part of the path *below* what you named outright,
-so pointing at a skipped directory — built-in or gitignored — still scans it:
+Skip rules are judged from the directory the scan starts in, so pointing at a
+skipped directory — built-in or gitignored — still scans it:
 
 ```sql
 SELECT path FROM './';                     -- no node_modules rows
@@ -243,8 +251,8 @@ SELECT path FROM './node_modules/*/package.json';  -- scans it anyway
 SELECT path FROM './dist';                 -- scans dist/ even when gitignored
 ```
 
-A `.gitignore` at or below the directory you named still filters beneath it;
-only rules inherited from above it are set aside.
+A `.gitignore` at or below the directory the scan starts in still filters
+beneath it; one above it is never read.
 
 ### Hidden files
 

package/docs/reference/sdk.md

@@ -116,8 +116,9 @@ shortcut was removed in #603 — use
 - `root` — Directory to index. When omitted, the index roots at the process
   cwd (even when `config` is supplied).
 - `tables` — Programmatic [`Table`](#table) definitions.
-- `ignore` — Glob patterns matched against root-relative paths; matched
-  files are skipped entirely (scan and watch).
+- `ignore` — Glob patterns matched against root-relative paths under the
+  [glob rule](./config.md#glob-rule) (`*` one level, `**` any depth);
+  matched files are skipped entirely (scan and watch).
 - `no_ignore` / `noIgnore` — Scan files a `.gitignore` would hide.
   [Path-tables](./path-tables.md#skip-rules) respect `.gitignore` files by
   default; the built-in `node_modules`/`.git` skips and any `ignore` patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dirsql",
-  "version": "0.4.65",
+  "version": "0.4.67",
   "description": "Ephemeral SQL index over a local directory",
   "license": "MIT",
   "repository": "https://github.com/thekevinscott/dirsql",
@@ -221,10 +221,10 @@
     ]
   },
   "optionalDependencies": {
-    "@dirsql/lib-linux-x64-gnu": "0.4.65",
-    "@dirsql/lib-linux-arm64-gnu": "0.4.65",
-    "@dirsql/lib-darwin-x64": "0.4.65",
-    "@dirsql/lib-darwin-arm64": "0.4.65",
-    "@dirsql/lib-win32-x64-msvc": "0.4.65"
+    "@dirsql/lib-linux-x64-gnu": "0.4.67",
+    "@dirsql/lib-linux-arm64-gnu": "0.4.67",
+    "@dirsql/lib-darwin-x64": "0.4.67",
+    "@dirsql/lib-darwin-arm64": "0.4.67",
+    "@dirsql/lib-win32-x64-msvc": "0.4.67"
   }
 }