dirsql 0.3.73__tar.gz → 0.3.75__tar.gz

{dirsql-0.3.73 → dirsql-0.3.75}/Cargo.lock

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

{dirsql-0.3.73 → dirsql-0.3.75}/PKG-INFO

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

{dirsql-0.3.73 → dirsql-0.3.75}/docs/AGENTS.md

@@ -57,7 +57,7 @@ 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); virtual columns and glob captures; the
+  protocol, exit codes, timeouts); stat columns and glob captures; 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.73 → dirsql-0.3.75}/docs/getting-started.md

@@ -112,30 +112,30 @@ through `jq` to pretty-print. Now select some columns:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT _path, _size FROM files ORDER BY _path"}' \
+  -d '{"sql":"SELECT path, size FROM files ORDER BY path"}' \
   | jq
 ```
 
 ```json
 [
   {
-    "_path": "notes/alice/ideas.md",
-    "_size": 52
+    "path": "notes/alice/ideas.md",
+    "size": 52
   },
   {
-    "_path": "notes/alice/welcome.md",
-    "_size": 66
+    "path": "notes/alice/welcome.md",
+    "size": 66
   },
   {
-    "_path": "notes/bob/reading-list.md",
-    "_size": 41
+    "path": "notes/bob/reading-list.md",
+    "size": 41
   }
 ]
 ```
 
-`_path` and `_size` are two of the built-in file columns `dirsql` collects
-for every file — see [virtual columns](./reference/columns.md#virtual-columns)
-for the full list. (The `_size` values are byte counts; they match the
+`path` and `size` are two of the built-in file columns `dirsql` collects
+for every file — see [stat columns](./reference/columns.md#stat-columns)
+for the full list. (The `size` values are byte counts; they match the
 output above because you pasted the files exactly.)
 
 You have a working SQL database over your files. Next, teach it the
@@ -152,7 +152,7 @@ In your second terminal, still inside `my-notes`, create a `.dirsql.toml`:
 ```bash
 cat > .dirsql.toml <<'EOF'
 [[table]]
-ddl  = "CREATE TABLE notes (author TEXT, _basename TEXT, _size INTEGER)"
+ddl  = "CREATE TABLE notes (author TEXT, basename TEXT, size INTEGER)"
 glob = "notes/{author}/*.md"
 EOF
 ```
@@ -192,25 +192,25 @@ terminal:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT author, _basename, _size FROM notes ORDER BY author, _basename"}' \
+  -d '{"sql":"SELECT author, basename, size FROM notes ORDER BY author, basename"}' \
   | jq
 ```
 
 ```json
 [
   {
-    "_basename": "ideas.md",
-    "_size": 52,
+    "basename": "ideas.md",
+    "size": 52,
     "author": "alice"
   },
   {
-    "_basename": "welcome.md",
-    "_size": 66,
+    "basename": "welcome.md",
+    "size": 66,
     "author": "alice"
   },
   {
-    "_basename": "reading-list.md",
-    "_size": 41,
+    "basename": "reading-list.md",
+    "size": 41,
     "author": "bob"
   }
 ]

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/howto/columns-from-paths.md

@@ -18,7 +18,7 @@ Capture both directory levels in `.dirsql.toml`:
 
 ```toml
 [[table]]
-ddl  = "CREATE TABLE photos (year TEXT, month TEXT, _basename TEXT)"
+ddl  = "CREATE TABLE photos (year TEXT, month TEXT, basename TEXT)"
 glob = "photos/{year}/{month}/*.jpg"
 ```
 
@@ -30,11 +30,11 @@ within one path segment) are in
 ## 2. Query the captured columns
 
 ```bash
-dirsql query "SELECT year, month, _basename FROM photos ORDER BY year, month"
+dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month"
 ```
 
 ```json
-[{"_basename":"beach.jpg","month":"05","year":"2024"},{"_basename":"hike.jpg","month":"11","year":"2024"},{"_basename":"snow.jpg","month":"01","year":"2025"}]
+[{"basename":"beach.jpg","month":"05","year":"2024"},{"basename":"hike.jpg","month":"11","year":"2024"},{"basename":"snow.jpg","month":"01","year":"2025"}]
 ```
 
 Captures are real SQL columns, so aggregation works:
@@ -49,8 +49,8 @@ dirsql query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year"
 
 ## Going further
 
-- Captures combine freely with [virtual columns](../reference/columns.md#virtual-columns)
-  (`_basename` above) — both are filesystem facts merged onto every row.
+- Captures combine freely with [stat columns](../reference/columns.md#stat-columns)
+  (`basename` above) — both are filesystem facts merged onto every row.
 - The [tutorial](../getting-started.md) walks the same idea with an
   `{author}` capture, starting from zero.
 - When the value you need lives inside the file rather than in its path,

{dirsql-0.3.73/packages/python → dirsql-0.3.75}/docs/howto/define-tables.md

@@ -13,14 +13,14 @@ directory you want to index, create a `.dirsql.toml` with one
 
 ```toml
 [[table]]
-ddl  = "CREATE TABLE posts (_path TEXT, _size INTEGER, _mtime INTEGER)"
+ddl  = "CREATE TABLE posts (path TEXT, size INTEGER, mtime INTEGER)"
 glob = "posts/**/*.md"
 ```
 
 - `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. Here
-  all three are [virtual columns](../reference/columns.md#virtual-columns) —
+  all three are [stat columns](../reference/columns.md#stat-columns) —
   filesystem facts `dirsql` computes for every file. Facts are opt-in by
   DDL: only the ones you declare become columns.
 
@@ -29,11 +29,11 @@ glob = "posts/**/*.md"
 Each matched file is one row:
 
 ```bash
-dirsql query "SELECT _path, _size FROM posts ORDER BY _path"
+dirsql query "SELECT path, size FROM posts ORDER BY path"
 ```
 
 ```json
-[{"_path":"posts/2024/hello.md","_size":21},{"_path":"posts/2025/again.md","_size":55}]
+[{"path":"posts/2024/hello.md","size":21},{"path":"posts/2025/again.md","size":55}]
 ```
 
 Files that don't match the glob (a `README.txt` next to `posts/`, say) are

{dirsql-0.3.73 → dirsql-0.3.75}/docs/howto/embed.md

@@ -35,7 +35,7 @@ comments/t2/c1.json    # {"body": "following up", "author": "alice"}
 
 Unlike a config-file table, a programmatic table takes an `extract`
 callback — your code reads each matched file and returns its rows, with
-[glob captures and virtual columns](../reference/columns.md) merged on
+[glob captures and stat columns](../reference/columns.md) merged on
 automatically (here, `{thread}` from the path):
 
 ::: code-group

{dirsql-0.3.73/packages/python → dirsql-0.3.75}/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, path TEXT)"
 glob    = "books/*.json"
 on-file = "jq -c '[{title, author, year}]' {path}"
 ```
@@ -32,14 +32,14 @@ by every hook.
 ## 2. Query the extracted columns
 
 ```bash
-dirsql query "SELECT title, author, year, _path FROM books ORDER BY year"
+dirsql query "SELECT title, author, year, path FROM books ORDER BY year"
 ```
 
 ```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}]
+[{"path":"books/bleak-house.json","author":"Charles Dickens","title":"Bleak House","year":1852},{"path":"books/middlemarch.json","author":"George Eliot","title":"Middlemarch","year":1871}]
 ```
 
-Filesystem facts are still merged onto every row — `_path` above comes from
+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)).
@@ -51,7 +51,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, path TEXT)"
 glob    = "logs/*.jsonl"
 on-file = "jq -c -s '.' {path}"
 ```

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/howto/react-to-changes.md

@@ -33,7 +33,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","ctime":1783170226,"dir":"inbox","ext":"txt","mtime":1783170226,"path":"inbox/two.txt","size":7},"table":"files"}
 ```
 
 Edits arrive as `update` events carrying both the old and new row;

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/howto/search-by-meaning.md

@@ -66,7 +66,7 @@ model = StaticModel.from_pretrained("minishlab/potion-base-8M")
 vector = model.encode([body["q"]])[0]
 needle = json.dumps([round(float(x), 6) for x in vector])
 print(
-    "SELECT _path, ROUND(vec_distance_cosine(embedding, '%s'), 3) AS distance "
+    "SELECT path, ROUND(vec_distance_cosine(embedding, '%s'), 3) AS distance "
     "FROM notes ORDER BY distance LIMIT 3" % needle
 )
 ```
@@ -89,7 +89,7 @@ path       = "sqlite_vec"          # Python module name; see note below
 entrypoint = "sqlite3_vec_init"
 
 [[table]]
-ddl     = "CREATE TABLE notes (_path TEXT, text TEXT, embedding TEXT)"
+ddl     = "CREATE TABLE notes (path TEXT, text TEXT, embedding TEXT)"
 glob    = "notes/*.md"
 on-file = "uv run --with model2vec python embed.py {path}"
 ```
@@ -110,7 +110,7 @@ uvx --with sqlite-vec dirsql query '{"q": "how do I cook pasta?"}'
 ```
 
 ```json
-[{"_path":"notes/pasta.md","distance":0.315},{"_path":"notes/tomatoes.md","distance":0.881},{"_path":"notes/branches.md","distance":0.92}]
+[{"path":"notes/pasta.md","distance":0.315},{"path":"notes/tomatoes.md","distance":0.881},{"path":"notes/branches.md","distance":0.92}]
 ```
 
 ```bash
@@ -118,7 +118,7 @@ uvx --with sqlite-vec dirsql query '{"q": "reviewing code on github"}'
 ```
 
 ```json
-[{"_path":"notes/branches.md","distance":0.51},{"_path":"notes/pasta.md","distance":1.033},{"_path":"notes/tomatoes.md","distance":1.074}]
+[{"path":"notes/branches.md","distance":0.51},{"path":"notes/pasta.md","distance":1.033},{"path":"notes/tomatoes.md","distance":1.074}]
 ```
 
 Neither question shares a keyword with its top note — "cook" appears

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/howto/skip-files.md

@@ -22,7 +22,7 @@ Exclude the noise in `.dirsql.toml`:
 ignore = ["notes/drafts/**", "**/*.tmp"]
 
 [[table]]
-ddl  = "CREATE TABLE notes (_path TEXT)"
+ddl  = "CREATE TABLE notes (path TEXT)"
 glob = "notes/**/*"
 ```
 
@@ -32,11 +32,11 @@ ignored file never reaches any table — even one whose glob would match it.
 ## 2. Confirm what made it in
 
 ```bash
-dirsql query "SELECT _path FROM notes ORDER BY _path"
+dirsql query "SELECT path FROM notes ORDER BY path"
 ```
 
 ```json
-[{"_path":"notes/final.md"}]
+[{"path":"notes/final.md"}]
 ```
 
 ## Notes

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/reference/cli.md

@@ -5,8 +5,8 @@ The `dirsql` binary has three modes:
 | Invocation | Behavior |
 |---|---|
 | `dirsql` (no subcommand) | Start a long-lived HTTP server exposing a SQL view of a directory. See [HTTP API](./http-api.md). |
-| `dirsql query "<sql>"` | Build the index, run one query, print the rows as JSON, exit. No server, no watch. |
-| `dirsql init` | Generate a starter `.dirsql.toml` by running `claude` over a directory. |
+| `dirsql query "<sql>"` | Query the file system as JSON |
+| `dirsql init` | Generate a `.dirsql.toml` |
 
 ## Installation
 
@@ -68,12 +68,12 @@ default `./.dirsql.toml`) with a single table named `files`:
 
 - Glob: `**/*` — every file under the root, at any depth, no ignores.
 - One row per file, with all seven
-  [virtual columns](./columns.md): `_path`, `_basename`, `_dir`, `_ext`,
-  `_size`, `_mtime`, `_ctime`.
+  [stat columns](./columns.md): `path`, `basename`, `dir`, `ext`,
+  `size`, `mtime`, `ctime`.
 
 ```bash
 curl -s localhost:7117/query -H 'content-type: application/json' \
-  -d '{"sql":"SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"}'
+  -d '{"sql":"SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"}'
 ```
 
 A config file, when present, fully overrules this default. A *missing*
@@ -100,12 +100,11 @@ with a JSON body describing the failure:
 
 ## `dirsql query`
 
-Run one SQL query from the shell — for ad-hoc inspection, scripting, and
-docs verification snippets — without booting the server and `curl`ing it:
+Run a SQL query from the shell:
 
 ```bash
-dirsql query "SELECT _basename, _size FROM files ORDER BY _size DESC LIMIT 5"
-# [{"_basename":"model.bin","_size":104857600}, …]
+dirsql query "SELECT basename, size FROM files ORDER BY size DESC LIMIT 5"
+# [{"basename":"model.bin","size":104857600}, …]
 
 dirsql query "SELECT COUNT(*) AS n FROM posts" | jq '.[0].n'
 ```
@@ -140,34 +139,29 @@ stderr, with exit code `1`.
 
 ## `dirsql init`
 
-Generates a `.dirsql.toml` by running the `claude` CLI over the target
-directory. The generated config contains only filesystem-fact tables
-(`[[table]]` entries whose columns come from [glob captures and virtual
-columns](./columns.md)) — never content-derived columns.
+Writes a starter `.dirsql.toml`:
 
 ```bash
 dirsql init
 ```
 
+You can further tweak this config as needed.
+
 ### Flags
 
 | Flag | Default | Description |
 |---|---|---|
-| `--root <path>` | current directory | Directory to scan. |
-| `--output <path>` | `<root>/.dirsql.toml` | Where to write the generated config. |
+| `--root <path>` | current directory | Directory the default `--output` path is resolved against. |
+| `--output <path>` | `<root>/.dirsql.toml` | Where to write the config. |
 | `--force` | off | Overwrite the output file if it already exists. |
 
 ### Requirements and failure modes
 
-`init` requires `claude` on `PATH`, signed in; there is no separate API key.
 All failures exit `1` with a message on stderr:
 
 | Condition | Behavior |
 |---|---|
-| Output file exists and `--force` not passed | Fails before invoking `claude` (no LLM call is made). |
-| `claude` not found on `PATH` | Fails with a pointer to the Claude Code install docs. |
-| `claude` exits non-zero | Fails with `claude`'s stderr; no partial config is written. |
-| `claude` produces non-UTF-8 output | Fails; nothing is written. |
+| Output file exists and `--force` not passed | Fails; nothing is written. |
+| Output path unwritable (e.g. missing parent directory) | Fails with the underlying I/O error. |
 
-On success, `claude`'s stdout is written verbatim to the output path and
-`init` exits `0`.
+On success, `init` exits `0`.

dirsql-0.3.75/docs/reference/columns.md

@@ -0,0 +1,80 @@
+# Stat columns and glob captures
+
+Every table — config-defined or programmatic — gets filesystem facts merged
+onto its rows automatically: seven **stat columns** derived from the file's
+path and stat metadata, plus one column per **`{name}` capture** in the
+table's glob.
+
+These are ordinary, physically stored `TEXT`/`INTEGER` columns, computed
+once per file at scan time and written like any other column value — not
+SQLite's `GENERATED ... VIRTUAL` columns (computed on the fly, never stored)
+and not part of a `CREATE VIRTUAL TABLE` (dirsql tables are always real
+tables). "Stat" describes where the value comes from — the file's path and
+`stat` metadata, as opposed to its content — not how it's stored.
+
+Facts are **opt-in by DDL**: only facts whose name appears as a column in
+the table's `CREATE TABLE` are populated; the rest are silently dropped.
+Declaring them requires nothing else. The names below aren't a protected or
+enforced namespace — nothing stops you from declaring a column with one of
+these names for an unrelated purpose, in which case dirsql's computed value
+lands there like any other fact (unless your own row source — an `on-file`
+command or SDK `extract` callback — supplies its own value for that name;
+see [Precedence](#precedence)).
+
+## Stat columns
+
+| Column | Type | Value |
+|---|---|---|
+| `path` | TEXT | The file's path relative to the scan root (e.g. `posts/hello.md`). |
+| `basename` | TEXT | The filename, including extension (`hello.md`). |
+| `dir` | TEXT | The parent directory relative to the root (`posts`); the empty string for files directly under the root. |
+| `ext` | TEXT | The file extension without the leading dot (`md`). Original case is preserved — `Photo.JPG` yields `JPG`; use `LOWER(ext)` for case-insensitive matching. `NULL` when the file has no extension. |
+| `size` | INTEGER | File size in bytes. |
+| `mtime` | INTEGER | Last-modified time, Unix seconds. |
+| `ctime` | INTEGER | Creation (birth) time, Unix seconds. `NULL` when the platform or filesystem cannot supply it. |
+
+A fact that cannot be computed (an unreadable file's `size`/`mtime`/
+`ctime`, a missing extension's `ext`) is absent from the row: `NULL` in
+the default relaxed mode, a missing-column error for a
+[`strict`](./config.md#table) table that declares it.
+
+```sql
+SELECT basename, size
+FROM posts
+WHERE mtime > strftime('%s', '2024-01-01')
+ORDER BY mtime DESC;
+```
+
+## Glob captures
+
+A `{name}` segment in a table's glob captures part of each matched path as
+a TEXT column named `name`:
+
+```toml
+[[table]]
+ddl  = "CREATE TABLE comments (thread_id TEXT, basename TEXT, mtime INTEGER)"
+glob = "_comments/{thread_id}/*.jsonl"
+```
+
+A file at `_comments/abc123/2024-05-05.jsonl` produces a row with
+`thread_id = "abc123"`.
+
+- A capture name must be a valid identifier: a letter or underscore
+  followed by letters, digits, or underscores (`[a-zA-Z_][a-zA-Z0-9_]*`).
+- A capture matches **within a single path segment** — one or more
+  characters, never a `/`. For matching purposes, `{name}` behaves like
+  `*`.
+- A glob may contain multiple captures (`{year}/{month}/*.jpg`).
+- Like stat columns, a capture populates a column only when the DDL
+  declares a column of the same name.
+
+## Precedence
+
+Values produced by a table's own row source — an `on-file` command's JSON
+output or an SDK `extract` callback's return value — **win** over
+auto-injected facts of the same name. An extract that explicitly emits
+`path` is honored.
+
+Injection order per row: stat columns first, then glob captures, then
+the row source's own values, each layer overwriting the previous, all
+filtered to the DDL's declared columns.

{dirsql-0.3.73/packages/rust → dirsql-0.3.75}/docs/reference/config.md

@@ -97,7 +97,7 @@ per-file command.
 |---|---|---|
 | `ddl` | yes | A SQLite `CREATE TABLE` statement. The table name is parsed from it. Only columns declared here are populated; auto-injected facts not in the DDL are dropped. |
 | `glob` | yes | Glob pattern matched against root-relative paths. May contain `{name}` [capture segments](./columns.md#glob-captures). First matching table wins when a file matches several globs. |
-| `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 command/extract output, a glob capture, or a virtual column). When `false`, extra keys are dropped and missing columns become `NULL`. |
+| `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 command/extract output, a glob capture, or a stat column). When `false`, extra keys are dropped and missing columns become `NULL`. |
 | `on-file` | no | A command run once per matched file; its stdout (a JSON array of row objects) becomes the file's rows. Must be non-empty. See [Command hooks](./hooks.md#on-file). |
 
 Without `on-file`, a table produces exactly one row per matched file, built
@@ -108,7 +108,7 @@ callback.
 
 ```toml
 [[table]]
-ddl  = "CREATE TABLE comments (thread_id TEXT, _basename TEXT, _mtime INTEGER)"
+ddl  = "CREATE TABLE comments (thread_id TEXT, basename TEXT, mtime INTEGER)"
 glob = "_comments/{thread_id}/*.jsonl"
 
 [[table]]
@@ -157,10 +157,10 @@ path       = "sqlite_vec"            # Python module name; on Node use the
 entrypoint = "sqlite3_vec_init"
 
 [[table]]
-ddl  = "CREATE TABLE comments (thread_id TEXT, _basename TEXT, _mtime INTEGER)"
+ddl  = "CREATE TABLE comments (thread_id TEXT, basename TEXT, mtime INTEGER)"
 glob = "_comments/{thread_id}/*.jsonl"
 
 [[table]]
-ddl  = "CREATE TABLE documents (_path TEXT, _basename TEXT, _size INTEGER)"
+ddl  = "CREATE TABLE documents (path TEXT, basename TEXT, size INTEGER)"
 glob = "**/index.md"
 ```

{dirsql-0.3.73 → dirsql-0.3.75}/packages/python/Cargo.toml

@@ -4,7 +4,7 @@ name = "dirsql-py-ext"
 # pypi/maturin handler can rewrite it via `write-version` before
 # `maturin build`. `pyproject.toml` declares `dynamic = ["version"]`
 # and maturin reads this field. Mirrors `packages/rust/Cargo.toml`.
-version = "0.3.73"
+version = "0.3.75"
 edition.workspace = true
 publish = false
 readme = "README.md"

{dirsql-0.3.73 → dirsql-0.3.75}/packages/python/docs/AGENTS.md

@@ -57,7 +57,7 @@ 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); virtual columns and glob captures; the
+  protocol, exit codes, timeouts); stat columns and glob captures; 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.73/packages/rust → dirsql-0.3.75/packages/python}/docs/getting-started.md

@@ -112,30 +112,30 @@ through `jq` to pretty-print. Now select some columns:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT _path, _size FROM files ORDER BY _path"}' \
+  -d '{"sql":"SELECT path, size FROM files ORDER BY path"}' \
   | jq
 ```
 
 ```json
 [
   {
-    "_path": "notes/alice/ideas.md",
-    "_size": 52
+    "path": "notes/alice/ideas.md",
+    "size": 52
   },
   {
-    "_path": "notes/alice/welcome.md",
-    "_size": 66
+    "path": "notes/alice/welcome.md",
+    "size": 66
   },
   {
-    "_path": "notes/bob/reading-list.md",
-    "_size": 41
+    "path": "notes/bob/reading-list.md",
+    "size": 41
   }
 ]
 ```
 
-`_path` and `_size` are two of the built-in file columns `dirsql` collects
-for every file — see [virtual columns](./reference/columns.md#virtual-columns)
-for the full list. (The `_size` values are byte counts; they match the
+`path` and `size` are two of the built-in file columns `dirsql` collects
+for every file — see [stat columns](./reference/columns.md#stat-columns)
+for the full list. (The `size` values are byte counts; they match the
 output above because you pasted the files exactly.)
 
 You have a working SQL database over your files. Next, teach it the
@@ -152,7 +152,7 @@ In your second terminal, still inside `my-notes`, create a `.dirsql.toml`:
 ```bash
 cat > .dirsql.toml <<'EOF'
 [[table]]
-ddl  = "CREATE TABLE notes (author TEXT, _basename TEXT, _size INTEGER)"
+ddl  = "CREATE TABLE notes (author TEXT, basename TEXT, size INTEGER)"
 glob = "notes/{author}/*.md"
 EOF
 ```
@@ -192,25 +192,25 @@ terminal:
 ```bash
 curl -s http://localhost:7117/query \
   -H 'content-type: application/json' \
-  -d '{"sql":"SELECT author, _basename, _size FROM notes ORDER BY author, _basename"}' \
+  -d '{"sql":"SELECT author, basename, size FROM notes ORDER BY author, basename"}' \
   | jq
 ```
 
 ```json
 [
   {
-    "_basename": "ideas.md",
-    "_size": 52,
+    "basename": "ideas.md",
+    "size": 52,
     "author": "alice"
   },
   {
-    "_basename": "welcome.md",
-    "_size": 66,
+    "basename": "welcome.md",
+    "size": 66,
     "author": "alice"
   },
   {
-    "_basename": "reading-list.md",
-    "_size": 41,
+    "basename": "reading-list.md",
+    "size": 41,
     "author": "bob"
   }
 ]

{dirsql-0.3.73 → dirsql-0.3.75}/packages/python/docs/howto/columns-from-paths.md

@@ -18,7 +18,7 @@ Capture both directory levels in `.dirsql.toml`:
 
 ```toml
 [[table]]
-ddl  = "CREATE TABLE photos (year TEXT, month TEXT, _basename TEXT)"
+ddl  = "CREATE TABLE photos (year TEXT, month TEXT, basename TEXT)"
 glob = "photos/{year}/{month}/*.jpg"
 ```
 
@@ -30,11 +30,11 @@ within one path segment) are in
 ## 2. Query the captured columns
 
 ```bash
-dirsql query "SELECT year, month, _basename FROM photos ORDER BY year, month"
+dirsql query "SELECT year, month, basename FROM photos ORDER BY year, month"
 ```
 
 ```json
-[{"_basename":"beach.jpg","month":"05","year":"2024"},{"_basename":"hike.jpg","month":"11","year":"2024"},{"_basename":"snow.jpg","month":"01","year":"2025"}]
+[{"basename":"beach.jpg","month":"05","year":"2024"},{"basename":"hike.jpg","month":"11","year":"2024"},{"basename":"snow.jpg","month":"01","year":"2025"}]
 ```
 
 Captures are real SQL columns, so aggregation works:
@@ -49,8 +49,8 @@ dirsql query "SELECT year, COUNT(*) AS photos FROM photos GROUP BY year"
 
 ## Going further
 
-- Captures combine freely with [virtual columns](../reference/columns.md#virtual-columns)
-  (`_basename` above) — both are filesystem facts merged onto every row.
+- Captures combine freely with [stat columns](../reference/columns.md#stat-columns)
+  (`basename` above) — both are filesystem facts merged onto every row.
 - The [tutorial](../getting-started.md) walks the same idea with an
   `{author}` capture, starting from zero.
 - When the value you need lives inside the file rather than in its path,