datanotes 3.3.0 → 3.3.1

package/dist/docs/guides/database-objects/tables.md

@@ -58,7 +58,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261020T173828-create_table-create-table-main-public-film",
+  "migration_id": "20261024T053819-create_table-create-table-main-public-film",
   "summary": null
 }
 ```
@@ -67,7 +67,7 @@ Answer:
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a15a64-a676-7657-9ff4-7a1e6bcc5df3
+id: 01a16c6a-c732-7310-8bb4-c9f28c15517c
 config:
   history: true
 
@@ -379,24 +379,24 @@ Answer:
   "ok": true,
   "op": "insert_row",
   "files_created": 1,
-  "planned_creates": ["datanotes/main/public/watch/2026-10-20 Nosferatu.md"],
+  "planned_creates": ["datanotes/main/public/watch/2026-10-24 Nosferatu.md"],
   "commits": [{ "table": "main.public.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261020T173828-insert_row-insert-into-watch"
+  "migration_id": "20261024T053819-insert_row-insert-into-watch"
 }
 ```
 
-`datanotes/main/public/watch/2026-10-20 Nosferatu.md` now reads:
+`datanotes/main/public/watch/2026-10-24 Nosferatu.md` now reads:
 
 ```markdown
 ---
 table: main.public.watch
 cssclasses:
   - watch
-id: 01a15a64-a8fb-73f8-a4e2-4263d12c1d9d
+id: 01a16c6a-c7d4-7cbb-a3cc-e6066a366800
 film: Nosferatu
 where: outdoor screening
 place: the park by the river
-occurred_at: 2026-10-20T17:38:28Z
+occurred_at: 2026-10-24T05:38:19Z
 ---
 Watched Nosferatu (outdoor screening).
 
@@ -440,7 +440,7 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.watch", "version": 2, "operation": "ALTER TABLE" }],
-  "migration_id": "20261020T173828-alter_table-alter-table-main-public-watch"
+  "migration_id": "20261024T053819-alter_table-alter-table-main-public-watch"
 }
 ```
 
@@ -483,7 +483,51 @@ Answer:
 
 ## Rename or move a table
 
-`alter_table` renames a table with `name`, or moves it to another `catalog` or `schema`. Here `actors` becomes `actor`, singular like the other tables. The rows’ folder and their front matter key `table` follow, and the engine rewrites the links to them. `dry_run` lists the notes that would move.
+`alter_table` renames a table with `name`, or moves it to another `catalog` or `schema`. Here `actors` becomes `actor`, singular like the other tables. The rows’ folder and their front matter key `table` follow, and the engine rewrites the links to them.
+
+The definitions that name the table follow it too:
+
+* the `ref` of every link column, lists of links and base columns included
+* the `vocabulary` of every string column
+* the tables a view reads, in `table`, `union` and `join`
+
+`dry_run` lists the notes that would move, and `schema_references` lists the names it would rewrite. Here a film’s `lead` links an actor, and the view `cast_list` reads the actors.
+
+**`add_column`**
+
+```json
+{
+  "table": "classics.film",
+  "column": {
+    "name": "lead",
+    "type": "link",
+    "ref": "diary.classics.actors",
+    "description": "The actor in the leading role"
+  }
+}
+```
+
+**`update_row`**
+
+```json
+{
+  "table": "classics.film",
+  "path": "datanotes/diary/classics/film/Nosferatu.md",
+  "set": { "lead": "[[Max Schreck]]" }
+}
+```
+
+**`create_view`**
+
+```json
+{
+  "catalog": "diary",
+  "schema": "classics",
+  "name": "cast_list",
+  "query": { "table": "diary.classics.actors", "columns": ["name"], "order_by": "name" },
+  "description": "Every actor, by name"
+}
+```
 
 **`alter_table`**
 
@@ -515,7 +559,22 @@ Answer:
       "to": "datanotes/diary/classics/actor/Max Schreck.md"
     }
   ],
-  "planned_texts": ["datanotes/metastore.yaml"]
+  "planned_texts": ["datanotes/metastore.yaml"],
+  "schema_references": [
+    {
+      "table": "diary.classics.film",
+      "column": "lead",
+      "key": "ref",
+      "from": "diary.classics.actors",
+      "to": "diary.classics.actor"
+    },
+    {
+      "view": "diary.classics.cast_list",
+      "key": "table",
+      "from": "diary.classics.actors",
+      "to": "diary.classics.actor"
+    }
+  ]
 }
 ```
 
@@ -525,7 +584,7 @@ Answer:
 { "table": "classics.actors", "name": "actor" }
 ```
 
-Answer:
+Answer (44 lines)
 
 ```json
 {
@@ -552,9 +611,25 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.actor", "version": 6, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.actor", "version": 6, "operation": "ALTER TABLE" },
+    { "table": "diary.classics.film", "version": 14, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-move-table-diary-classics-acto"
+  "migration_id": "20261024T053837-alter_table-move-table-diary-classics-acto",
+  "schema_references": [
+    {
+      "table": "diary.classics.film",
+      "column": "lead",
+      "key": "ref",
+      "from": "diary.classics.actors",
+      "to": "diary.classics.actor"
+    },
+    {
+      "view": "diary.classics.cast_list",
+      "key": "table",
+      "from": "diary.classics.actors",
+      "to": "diary.classics.actor"
+    }
+  ]
 }
 ```
 
@@ -566,7 +641,7 @@ Then move it to a schema of its own:
 { "table": "classics.actor", "catalog": "diary", "schema": "credits" }
 ```
 
-Answer:
+Answer (44 lines)
 
 ```json
 {
@@ -593,9 +668,25 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
+    { "table": "diary.classics.film", "version": 15, "operation": "ALTER TABLE" },
     { "table": "diary.credits.actor", "version": 7, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-move-table-diary-classics-acto-2"
+  "migration_id": "20261024T053837-alter_table-move-table-diary-classics-acto-2",
+  "schema_references": [
+    {
+      "table": "diary.classics.film",
+      "column": "lead",
+      "key": "ref",
+      "from": "diary.classics.actor",
+      "to": "diary.credits.actor"
+    },
+    {
+      "view": "diary.classics.cast_list",
+      "key": "table",
+      "from": "diary.classics.actor",
+      "to": "diary.credits.actor"
+    }
+  ]
 }
 ```
 
@@ -615,6 +706,39 @@ Answer:
 }
 ```
 
+The link column and the view now name `diary.credits.actor`, so the view still answers and `check_table` finds no broken link:
+
+**`select_rows`**
+
+```json
+{ "table": "cast_list" }
+```
+
+Answer:
+
+```json
+{
+  "table": "diary.credits.actor",
+  "total": 1,
+  "rows": [
+    { "path": "datanotes/diary/credits/actor/Max Schreck.md", "name": "Max Schreck" }
+  ],
+  "view": "diary.classics.cast_list"
+}
+```
+
+**`check_table`**
+
+```json
+{ "table": "classics.film" }
+```
+
+Answer:
+
+```json
+{ "table": "film", "rows_checked": 2, "total": 0, "violations": [] }
+```
+
 ## Change sub-folders and file names
 
 `alter_table` also changes `partition`, the sub-folders, and `filename`, the name pattern. The engine renames every row to fit, and refuses the change when a row can’t fill the pattern.
@@ -657,9 +781,9 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 13, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 17, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-3"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-5"
 }
 ```
 
@@ -709,9 +833,9 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 14, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 18, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-4"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-6"
 }
 ```
 
@@ -751,9 +875,9 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 15, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 19, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-5"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-7"
 }
 ```
 
@@ -771,9 +895,9 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 16, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 20, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-6"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-8"
 }
 ```
 
@@ -791,9 +915,9 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 17, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 21, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-7"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-9"
 }
 ```
 
@@ -819,8 +943,8 @@ Answer:
   "op": "insert_row",
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/1925/Battleship Potemkin (1925).md"],
-  "commits": [{ "table": "diary.classics.film", "version": 18, "operation": "WRITE" }],
-  "migration_id": "20261020T173845-insert_row-insert-into-film-3"
+  "commits": [{ "table": "diary.classics.film", "version": 22, "operation": "WRITE" }],
+  "migration_id": "20261024T053837-insert_row-insert-into-film-4"
 }
 ```
 
@@ -830,7 +954,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a15a64-ea48-70a1-84d2-829cc3c9da62
+id: 01a16c6b-0f27-7090-8d6f-7412c09f30e9
 title: Battleship Potemkin
 year: 1925
 minutes: 75
@@ -859,9 +983,9 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 19, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 23, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-8"
+  "migration_id": "20261024T053837-alter_table-alter-table-diary-classics-fil-10"
 }
 ```
 
@@ -882,8 +1006,8 @@ Answer:
   "op": "insert_row",
   "files_created": 1,
   "planned_creates": ["datanotes/diary/classics/film/1924/Sherlock Jr. (1924).md"],
-  "commits": [{ "table": "diary.classics.film", "version": 20, "operation": "WRITE" }],
-  "migration_id": "20261020T173845-insert_row-insert-into-film-4"
+  "commits": [{ "table": "diary.classics.film", "version": 24, "operation": "WRITE" }],
+  "migration_id": "20261024T053838-insert_row-insert-into-film"
 }
 ```
 
@@ -893,7 +1017,7 @@ Answer:
 ---
 table: diary.classics.film
 cut: restored
-id: 01a15a64-ea5e-737b-a2ef-e105a2e98fdc
+id: 01a16c6b-0f36-716a-acd2-d5e466f33d94
 title: Sherlock Jr.
 year: 1924
 minutes: 45
@@ -924,9 +1048,9 @@ Answer:
   "op": "alter_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [
-    { "table": "diary.classics.film", "version": 21, "operation": "ALTER TABLE" }
+    { "table": "diary.classics.film", "version": 25, "operation": "ALTER TABLE" }
   ],
-  "migration_id": "20261020T173845-alter_table-alter-table-diary-classics-fil-9"
+  "migration_id": "20261024T053838-alter_table-alter-table-diary-classics-fil"
 }
 ```
 
@@ -1008,7 +1132,7 @@ Answer:
 ```json
 {
   "ok": true,
-  "migration_id": "20261020T173845-create_table-create-table-diary-log-watch"
+  "migration_id": "20261024T053838-create_table-create-table-diary-log-watch"
 }
 ```
 
@@ -1037,7 +1161,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/diary/log/watch/2026/10/2026-10-06 2130.md"],
   "commits": [{ "table": "diary.log.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261020T173845-insert_row-insert-into-watch"
+  "migration_id": "20261024T053838-insert_row-insert-into-watch"
 }
 ```
 
@@ -1046,7 +1170,7 @@ Answer:
 ```markdown
 ---
 table: diary.log.watch
-id: 01a15a64-eaa5-7d15-957a-55f01a116533
+id: 01a16c6b-0f60-7b71-8d2f-3889591b195e
 film: "[[Nosferatu (1922)]]"
 occurred_at: 2026-10-06T21:30:00+02:00
 where: outdoor screening
@@ -1082,7 +1206,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_copy", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261020T173845-clone_table-clone-diary-classics-film-to-s"
+  "migration_id": "20261024T053838-clone_table-clone-diary-classics-film-to-s"
 }
 ```
 
@@ -1148,7 +1272,7 @@ Answer:
   "commits": [
     { "table": "sandbox.classics.film_empty", "version": 0, "operation": "CLONE" }
   ],
-  "migration_id": "20261020T173845-clone_table-clone-diary-classics-film-to-s-2"
+  "migration_id": "20261024T053838-clone_table-clone-diary-classics-film-to-s-2"
 }
 ```
 
@@ -1166,7 +1290,7 @@ Answer:
   "catalog": "sandbox",
   "schema": "classics",
   "rows": 0,
-  "columns": ["id", "added_on", "title", "year", "minutes", "status", "rating"]
+  "columns": ["id", "added_on", "title", "year", "minutes", "status", "rating", "lead"]
 }
 ```
 
@@ -1230,7 +1354,7 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.scratch", "version": 2, "operation": "DROP TABLE" }],
-  "migration_id": "20261020T173828-drop_table-drop-table-scratch"
+  "migration_id": "20261024T053819-drop_table-drop-table-scratch"
 }
 ```
 
@@ -1254,7 +1378,7 @@ The engine wrote this file in its own words. It holds `film`, `watch` and `revie
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a15a64-a676-7657-9ff4-7a1e6bcc5df3
+id: 01a16c6a-c732-7310-8bb4-c9f28c15517c
 config:
   history: true