dirsql 0.3.126__tar.gz → 0.4.0__tar.gz

{dirsql-0.3.126 → dirsql-0.4.0}/Cargo.lock

@@ -500,7 +500,7 @@ dependencies = [
 
 [[package]]
 name = "dirsql-py-ext"
-version = "0.3.126"
+version = "0.4.0"
 dependencies = [
  "dirsql",
  "pyo3",

{dirsql-0.3.126 → dirsql-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dirsql
-Version: 0.3.126
+Version: 0.4.0
 Summary: Ephemeral SQL index over a local directory
 Keywords: sql,filesystem,directory,sqlite,index
 Author: Kevin Scott

{dirsql-0.3.126 → dirsql-0.4.0}/docs/.vitepress/config.ts

@@ -5,6 +5,17 @@ export default defineConfig({
   description: 'Ephemeral SQL index over a local directory. Watches a filesystem, ingests structured files into an ephemeral SQLite database, and exposes a SQL query interface.',
   base: '/dirsql/',
 
+  // Vite blocks dev-server requests whose Host header isn't allowlisted, so
+  // `pnpm dev --host` reached by a network hostname (e.g. a Tailscale
+  // `*.ts.net` name) 400s. Allow extra hosts from the environment so a
+  // personal hostname never has to be committed:
+  //   VITEPRESS_ALLOWED_HOSTS=my.host.ts.net pnpm dev --host
+  vite: {
+    server: {
+      allowedHosts: process.env.VITEPRESS_ALLOWED_HOSTS?.split(',') ?? []
+    }
+  },
+
   themeConfig: {
     search: {
       provider: 'local'
@@ -57,7 +68,7 @@ export default defineConfig({
             { text: 'CLI', link: '/reference/cli' },
             { text: 'Configuration File', link: '/reference/config' },
             { text: 'Command Hooks', link: '/reference/hooks' },
-            { text: 'Virtual Columns & Glob Captures', link: '/reference/columns' },
+            { text: 'Columns', link: '/reference/columns' },
             { text: 'Path-tables', link: '/reference/path-tables' },
             { text: 'HTTP API', link: '/reference/http-api' },
             { text: 'SDK', link: '/reference/sdk' },

{dirsql-0.3.126 → dirsql-0.4.0}/docs/AGENTS.md

@@ -57,7 +57,8 @@ migrated -- a page survives only if a slot wants its content):
   `dirsql` in an application.
 - **Reference** (`reference/`) -- CLI flags and defaults; the complete
   `.dirsql.toml` schema; the command hook contract (placeholders, stdout
-  protocol, exit codes, timeouts); stat columns and glob captures; the
+  protocol, exit codes, timeouts); the columns model (named tables get their
+  hook's output; path-tables get stat columns); the
   HTTP API; the SDK page (`reference/sdk.md`, one page with
   Python/TypeScript/Rust code-groups -- the sole SDK home); plus the
   Migrations include (`migrations.md`).

{dirsql-0.3.126/packages/rust → dirsql-0.4.0}/docs/getting-started.md

@@ -1,12 +1,12 @@
 # Your first dirsql database
 
 In this tutorial you will turn a directory of three tiny markdown files into
-a SQL database — with a single command, and without writing any code. You
-will:
+a SQL database. You will:
 
 1. Create the directory and files.
-2. Query them straight away with zero configuration.
-3. Declare your own table to name and reuse a shape, and query it.
+2. Query them straight away with zero configuration and no code.
+3. Declare your own named table — with a tiny parser that pulls a column out
+   of each file — and query it.
 
 It takes about five minutes.
 
@@ -140,25 +140,44 @@ A declared table fixes a shape once: you give it a name, scope it to exactly
 the files you care about, and then query it by name instead of repeating a
 path in every question. It is also the on-ramp to everything a path-table
 can't do — a named table can be kept live by the watcher, persisted across
-restarts, and given a parser that reads inside your files.
+restarts, and given a parser that reads *inside* your files.
 
-Still inside `my-notes`, create a `.dirsql.toml`:
+That parser is the point: a named table's columns are exactly what its
+`on-file` command emits. `dirsql` adds nothing on its own — so this is where
+you pull a value out of each file. Still inside `my-notes`, write a tiny
+parser that reads a note's title line (the `# Heading`) and its author (the
+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')"
+EOF
+```
+
+Now create a `.dirsql.toml` that points a table at it:
 
 ```bash
 cat > .dirsql.toml <<'EOF'
 [[table]]
-ddl  = "CREATE TABLE notes (dir TEXT, basename TEXT, size INTEGER)"
-glob = "notes/**/*.md"
+ddl     = "CREATE TABLE notes (title TEXT, author TEXT)"
+glob    = "notes/**/*.md"
+on-file = "sh note.sh {path}"
 EOF
 ```
 
-Two keys define the table:
+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.
-  Each is a [stat column](./reference/columns.md#stat-columns) `dirsql`
-  computes for every file.
+- `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.
 
 ## 5. Query the table
 
@@ -168,11 +187,11 @@ pass it explicitly with `-c`, **after** the SQL:
 ::: code-group
 
 ```bash [npm]
-npx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+npx dirsql "SELECT title, author FROM notes ORDER BY author, title" -c .dirsql.toml | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .dirsql.toml | jq
+uvx dirsql "SELECT title, author FROM notes ORDER BY author, title" -c .dirsql.toml | jq
 ```
 
 :::
@@ -180,35 +199,33 @@ uvx dirsql "SELECT dir, basename, size FROM notes ORDER BY dir, basename" -c .di
 ```json
 [
   {
-    "basename": "ideas.md",
-    "dir": "notes/alice",
-    "size": 52
+    "author": "alice",
+    "title": "Ideas"
   },
   {
-    "basename": "welcome.md",
-    "dir": "notes/alice",
-    "size": 66
+    "author": "alice",
+    "title": "Welcome"
   },
   {
-    "basename": "reading-list.md",
-    "dir": "notes/bob",
-    "size": 41
+    "author": "bob",
+    "title": "Reading list"
   }
 ]
 ```
 
-You queried `FROM notes` by name — no path, no glob to repeat. And because
-`dir` is a real SQL column, you can aggregate on it. Count each author's
-notes by their folder:
+You queried `FROM notes` by name — no path, no glob to repeat — and `title`
+came from *inside* each file, something a path-table can't reach. Because
+`author` is a real SQL column, you can aggregate on it. Count each author's
+notes:
 
 ::: code-group
 
 ```bash [npm]
-npx dirsql query "SELECT dir, COUNT(*) AS notes FROM notes GROUP BY dir ORDER BY dir" -c .dirsql.toml | jq
+npx dirsql query "SELECT author, COUNT(*) AS notes FROM notes GROUP BY author ORDER BY author" -c .dirsql.toml | jq
 ```
 
 ```bash [PyPI]
-uvx dirsql query "SELECT dir, COUNT(*) AS notes FROM notes GROUP BY dir ORDER BY dir" -c .dirsql.toml | jq
+uvx dirsql query "SELECT author, COUNT(*) AS notes FROM notes GROUP BY author ORDER BY author" -c .dirsql.toml | jq
 ```
 
 :::
@@ -216,11 +233,11 @@ uvx dirsql query "SELECT dir, COUNT(*) AS notes FROM notes GROUP BY dir ORDER BY
 ```json
 [
   {
-    "dir": "notes/alice",
+    "author": "alice",
     "notes": 2
   },
   {
-    "dir": "notes/bob",
+    "author": "bob",
     "notes": 1
   }
 ]
@@ -234,7 +251,7 @@ configuration, and a declared table when you want a named shape to reuse.
 - [Query files without a config](./howto/query-without-config.md) — more
   path-table questions you can ask with no setup at all.
 - [Define tables for your files](./howto/define-tables.md) — the full
-  `[[table]]` recipe: multiple tables, ignore patterns.
+  `[[table]]` recipe: multiple tables, each with its own `on-file` parser.
 - [Extract rows from file contents](./howto/extract-from-contents.md) —
   pull columns out of *inside* your files with an `on-file` parser.
 - [CLI](./reference/cli.md) — every flag, plus running `dirsql` as a

dirsql-0.4.0/docs/howto/columns-from-paths.md

@@ -0,0 +1,77 @@
+# Derive columns from file paths
+
+Directory layouts often encode real data — an author, a year, a thread ID —
+as path segments. An [`on-file`](../reference/config.md#table) hook receives
+each file's path and can split it into columns, so a query can group and
+filter on those segments.
+
+## 1. Split the path in a hook
+
+Suppose photos are filed by year and month:
+
+```
+photos/2024/05/beach.jpg
+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:
+
+```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])}]))
+```
+
+Point a table at it in `.dirsql.toml`:
+
+```toml
+[[table]]
+ddl     = "CREATE TABLE photos (year TEXT, month TEXT, basename TEXT)"
+glob    = "photos/*/*/*.jpg"
+on-file = "python3 pathcols.py {path}"
+```
+
+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
+because the DDL declares it *and* the hook emits it.
+
+## 2. Query the derived columns
+
+Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
+auto-load a `.dirsql.toml` from the current directory):
+
+```bash
+dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month" -c ./.dirsql.toml
+```
+
+```json
+[{"basename":"beach.jpg","month":"05","year":"2024"},{"basename":"hike.jpg","month":"11","year":"2024"},{"basename":"snow.jpg","month":"01","year":"2025"}]
+```
+
+They are real SQL columns, so aggregation works:
+
+```bash
+dirsql query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year" -c ./.dirsql.toml
+```
+
+```json
+[{"photos":2,"year":"2024"},{"photos":1,"year":"2025"}]
+```
+
+## Going further
+
+- Only need the plain filesystem stat columns (`path`, `basename`, `dir`,
+  `ext`, `size`, …) with no code? Query the path directly — a
+  [path-table](../reference/path-tables.md) gives them for free, no config.
+- The [tutorial](../getting-started.md) walks the same idea, deriving an
+  author from the folder name, starting from zero.
+- When the value you need lives inside the file rather than in its path,
+  see [Extract rows from file contents](./extract-from-contents.md).

dirsql-0.4.0/docs/howto/define-tables.md

@@ -0,0 +1,76 @@
+# Define tables for your files
+
+Map a glob of files to a named SQL table so you query exactly the files you
+care about, by name — a shape you can reuse, keep live with the watcher, and
+persist across restarts, instead of repeating an ad-hoc
+[path-table](../reference/path-tables.md) path in every query.
+
+## 1. Create a config with a table
+
+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:
+
+```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]}]))
+```
+
+Then declare the table in `.dirsql.toml`:
+
+```toml
+[[table]]
+ddl     = "CREATE TABLE posts (title TEXT, slug TEXT)"
+glob    = "posts/**/*.md"
+on-file = "python3 extract.py {path}"
+```
+
+- `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
+  a [config error](../reference/config.md#parse-errors). For plain stat
+  columns with no code, query the path directly with a path-table instead.
+
+## 2. Query the table
+
+Pass the config with [`-c`](../reference/cli.md#flags) — `dirsql` does not
+auto-load a `.dirsql.toml` from the current directory. Each matched file is
+one row:
+
+```bash
+dirsql query "SELECT title, slug FROM posts ORDER BY slug" -c ./.dirsql.toml
+```
+
+```json
+[{"slug":"again","title":"On Recursion"},{"slug":"hello","title":"Hello World"}]
+```
+
+Files that don't match the glob (a `README.txt` next to `posts/`, say) are
+simply not in the table. Only the tables you define are served.
+
+## Multiple tables
+
+Add one `[[table]]` entry per table — each with its own `glob`, `ddl`, and
+`on-file`. When a file matches several globs, it populates every matching
+table — each table is an independent view. See
+[`[[table]]`](../reference/config.md#table) for the remaining key, `strict`.
+
+## Going further
+
+- The parser mechanics — placeholders, stdout protocol, per-file failure
+  isolation — are the [`on-file` hook contract](../reference/hooks.md#on-file);
+  [Extract rows from file contents](./extract-from-contents.md) is the fuller
+  recipe.
+- Your directory layout encodes data (authors, dates, IDs)? Split the path in
+  the hook — [Derive columns from file paths](./columns-from-paths.md).
+- Why one row per file, rebuilt from disk? See
+  [how `dirsql` thinks](../explanation.md).

{dirsql-0.3.126/packages/python → dirsql-0.4.0}/docs/howto/embed.md

@@ -34,22 +34,25 @@ comments/t2/c1.json    # {"body": "following up", "author": "alice"}
 ```
 
 Unlike a config-file table, a programmatic table takes an `on_file`
-callback — your code reads each matched file and returns its rows, with
-[glob captures and stat columns](../reference/columns.md) merged on
-automatically (here, `{thread}` from the path):
+callback — your code reads each matched file and returns its rows. The row's
+columns are exactly what the callback returns; `dirsql` merges nothing on top
+(see [Columns](../reference/columns.md)), so the callback derives the `thread`
+from the file's path itself:
 
 ::: code-group
 
 ```python [Python]
 import asyncio
 import json
+import os
 
 from dirsql import DirSQL, Table
 
 
 def on_file(path: str) -> list[dict]:
+    thread = os.path.basename(os.path.dirname(path))
     with open(path, encoding="utf-8") as f:
-        return [json.load(f)]
+        return [{**json.load(f), "thread": thread}]
 
 
 async def main() -> None:
@@ -58,7 +61,7 @@ async def main() -> None:
         tables=[
             Table(
                 ddl="CREATE TABLE comments (thread TEXT, author TEXT, body TEXT)",
-                glob="comments/{thread}/*.json",
+                glob="comments/*/*.json",
                 on_file=on_file,
             )
         ],
@@ -73,6 +76,7 @@ asyncio.run(main())
 
 ```typescript [TypeScript]
 import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
 import { DirSQL } from "dirsql";
 
 const db = new DirSQL({
@@ -80,8 +84,10 @@ const db = new DirSQL({
   tables: [
     {
       ddl: "CREATE TABLE comments (thread TEXT, author TEXT, body TEXT)",
-      glob: "comments/{thread}/*.json",
-      onFile: (path) => [JSON.parse(readFileSync(path, "utf8"))],
+      glob: "comments/*/*.json",
+      onFile: (path) => [
+        { ...JSON.parse(readFileSync(path, "utf8")), thread: basename(dirname(path)) },
+      ],
     },
   ],
 });
@@ -110,6 +116,12 @@ fn on_file(path: &str) -> Vec<HashMap<String, Value>> {
             row.insert(key, Value::Text(s));
         }
     }
+    let thread = std::path::Path::new(path)
+        .parent()
+        .and_then(|p| p.file_name())
+        .and_then(|n| n.to_str())
+        .unwrap_or_default();
+    row.insert("thread".into(), Value::Text(thread.into()));
     vec![row]
 }
 
@@ -118,7 +130,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .root("./comments-root")
         .table(Table::new(
             "CREATE TABLE comments (thread TEXT, author TEXT, body TEXT)",
-            "comments/{thread}/*.json",
+            "comments/*/*.json",
             on_file,
         ))
         .build()?;

{dirsql-0.3.126/packages/rust → dirsql-0.4.0}/docs/howto/extract-from-contents.md

@@ -18,7 +18,7 @@ stdout works. With [`jq`](https://jqlang.org/):
 
 ```toml
 [[table]]
-ddl     = "CREATE TABLE books (title TEXT, author TEXT, year INTEGER, path TEXT)"
+ddl     = "CREATE TABLE books (title TEXT, author TEXT, year INTEGER)"
 glob    = "books/*.json"
 on-file = "jq -c '[{title, author, year}]' {path}"
 ```
@@ -35,17 +35,16 @@ Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
 auto-load a `.dirsql.toml` from the current directory):
 
 ```bash
-dirsql query "SELECT title, author, year, path FROM books ORDER BY year" -c ./.dirsql.toml
+dirsql query "SELECT title, author, year FROM books ORDER BY year" -c ./.dirsql.toml
 ```
 
 ```json
-[{"path":"books/bleak-house.json","author":"Charles Dickens","title":"Bleak House","year":1852},{"path":"books/middlemarch.json","author":"George Eliot","title":"Middlemarch","year":1871}]
+[{"author":"Charles Dickens","title":"Bleak House","year":1852},{"author":"George Eliot","title":"Middlemarch","year":1871}]
 ```
 
-Filesystem facts are still merged onto every row — `path` above comes from
-`dirsql`, not from `jq`. When the command emits a key that collides with a
-fact, the command wins
-([precedence](../reference/columns.md#precedence)).
+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.
 
 ## Multiple rows per file
 
@@ -54,7 +53,7 @@ row per line, slurp it:
 
 ```toml
 [[table]]
-ddl     = "CREATE TABLE events (event TEXT, user TEXT, path TEXT)"
+ddl     = "CREATE TABLE events (event TEXT, user TEXT)"
 glob    = "logs/*.jsonl"
 on-file = "jq -c -s '.' {path}"
 ```

{dirsql-0.3.126/packages/rust → dirsql-0.4.0}/docs/howto/parse-files-into-columns.md

@@ -106,10 +106,9 @@ Same command, same rows. The difference is what a declared table brings: it is
 indexed on build, kept fresh by the watcher, survives restarts with
 [`--persist`](./persist.md), and a config can declare
 [many tables](./define-tables.md) — each with its own `on-file` — where the flag
-gives every path-table one parser. A declared table also merges the filesystem
-facts back onto each row, so a `path TEXT` column in the DDL is populated by
-`dirsql` even though the parser did not emit it
-([precedence](../reference/columns.md#precedence)).
+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}`).
 
 ## Going further
 

{dirsql-0.3.126/packages/python → dirsql-0.4.0}/docs/howto/react-to-changes.md

@@ -7,13 +7,16 @@ side.
 
 Row events are emitted for **named tables**, so this flow needs a config —
 [path-tables](../reference/path-tables.md) are scanned per query and are not
-watched. Define one next to your files:
+watched. Define one next to your files. A named table's columns are whatever
+its [`on-file`](../reference/config.md#table) hook emits; here a minimal hook
+prints each file's basename:
 
 ```toml
 # .dirsql.toml
 [[table]]
-ddl  = "CREATE TABLE files (path TEXT, basename TEXT, dir TEXT, ext TEXT, size INTEGER, mtime INTEGER, ctime INTEGER)"
-glob = "**/*"
+ddl     = "CREATE TABLE files (basename TEXT)"
+glob    = "**/*"
+on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
 ```
 
 ## 1. Open the stream
@@ -44,7 +47,7 @@ The stream delivers the resulting row change:
 
 ```
 event: row
-data: {"action":"insert","file_path":"inbox/two.txt","old_row":null,"row":{"basename":"two.txt","ctime":1783170226,"dir":"inbox","ext":"txt","mtime":1783170226,"path":"inbox/two.txt","size":7},"table":"files"}
+data: {"action":"insert","file_path":"inbox/two.txt","old_row":null,"row":{"basename":"two.txt"},"table":"files"}
 ```
 
 Edits arrive as `update` events carrying both the old and new row;

{dirsql-0.3.126 → dirsql-0.4.0}/docs/howto/search-by-meaning.md

@@ -41,21 +41,25 @@ notes/tomatoes.md   # planting tomato seedlings after the last frost
 ```
 
 Next to them, `embed.py` turns one file into one row carrying its text and
-its embedding (a JSON array, stored as TEXT — `sqlite-vec` accepts JSON
-vectors directly):
+its `path`, text, and embedding (a JSON array, stored as TEXT — `sqlite-vec`
+accepts JSON vectors directly). dirsql injects no columns, so the script emits
+the path itself, deriving it from the `{path}`/`{root}` the hook passes in:
 
 ```python
 """Embed one file's text; print a dirsql row array on stdout."""
 import json
+import os
 import sys
 
 from model2vec import StaticModel
 
-path = sys.argv[1]
+path, root = sys.argv[1], sys.argv[2]
 text = open(path, encoding="utf-8").read()
 model = StaticModel.from_pretrained("minishlab/potion-base-8M")
 vector = model.encode([text])[0]
-print(json.dumps([{"text": text, "embedding": json.dumps([round(float(x), 6) for x in vector])}]))
+row = {"path": os.path.relpath(path, root), "text": text,
+       "embedding": json.dumps([round(float(x), 6) for x in vector])}
+print(json.dumps([row]))
 ```
 
 And `search.py` turns a `{"q": "..."}` request body into SQL, embedding the
@@ -98,7 +102,7 @@ entrypoint = "sqlite3_vec_init"
 [[table]]
 ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
 glob    = "notes/*.md"
-on-file = "uv run --with model2vec python embed.py {path}"
+on-file = "uv run --with model2vec python embed.py {path} {root}"
 ```
 
 The extension is named by package: the Python launcher resolves the

{dirsql-0.3.126/packages/rust → dirsql-0.4.0}/docs/howto/skip-files.md

@@ -22,8 +22,9 @@ Exclude the noise in `.dirsql.toml`:
 ignore = ["notes/drafts/**", "**/*.tmp"]
 
 [[table]]
-ddl  = "CREATE TABLE notes (path TEXT)"
-glob = "notes/**/*"
+ddl     = "CREATE TABLE notes (basename TEXT)"
+glob    = "notes/**/*"
+on-file = '''sh -c 'printf "[{\"basename\":\"%s\"}]" "${1##*/}"' sh {path}'''
 ```
 
 Patterns match against root-relative paths, the same way table globs do. An
@@ -35,11 +36,11 @@ Pass the config with [`-c`](../reference/cli.md#flags) (`dirsql` does not
 auto-load a `.dirsql.toml` from the current directory):
 
 ```bash
-dirsql query "SELECT path FROM notes ORDER BY path" -c ./.dirsql.toml
+dirsql query "SELECT basename FROM notes ORDER BY basename" -c ./.dirsql.toml
 ```
 
 ```json
-[{"path":"notes/final.md"}]
+[{"basename":"final.md"}]
 ```
 
 ## Notes

{dirsql-0.3.126 → dirsql-0.4.0}/docs/howto/write-a-plugin.md

@@ -72,7 +72,7 @@ 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}`). Recommended for published plugins: the command
+  `PATH` (`embed-file {path} {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
@@ -116,23 +116,28 @@ entrypoint = "sqlite3_vec_init"
 [[table]]
 ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
 glob    = "notes/*.md"
-on-file = "uv run --with model2vec python embed.py {path}"
+on-file = "uv run --with model2vec python embed.py {path} {root}"
 ```
 
-`embed.py` turns one file into one row carrying its text and its embedding:
+`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:
 
 ```python
 """Embed one file's text; print a dirsql row array on stdout."""
 import json
+import os
 import sys
 
 from model2vec import StaticModel
 
-path = sys.argv[1]
+path, root = sys.argv[1], sys.argv[2]
 text = open(path, encoding="utf-8").read()
 model = StaticModel.from_pretrained("minishlab/potion-base-8M")
 vector = model.encode([text])[0]
-print(json.dumps([{"text": text, "embedding": json.dumps([round(float(x), 6) for x in vector])}]))
+row = {"path": os.path.relpath(path, root), "text": text,
+       "embedding": json.dumps([round(float(x), 6) for x in vector])}
+print(json.dumps([row]))
 ```
 
 `search.py` turns a `{"q": "..."}` request body into nearest-neighbor SQL: