datanotes 3.3.1 → 3.4.0

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

@@ -35,7 +35,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 3, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053819-add_column-add-column-minutes-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-minutes-to-film"
 }
 ```
 
@@ -118,7 +118,7 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 5, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053819-add_column-add-column-favourite-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-favourite-to-film"
 }
 ```
 
@@ -176,7 +176,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 6, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053819-add_column-add-column-status-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-status-to-film"
 }
 ```
 
@@ -283,7 +283,7 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 9, "operation": "UPDATE" }],
-  "migration_id": "20261024T053819-rename_value-rename-film-status-value-seen-"
+  "migration_id": "20261024T063903-rename_value-rename-film-status-value-seen-"
 }
 ```
 
@@ -338,7 +338,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 10, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261024T053819-alter_column-alter-column-status-in-film"
+  "migration_id": "20261024T063903-alter_column-alter-column-status-in-film"
 }
 ```
 
@@ -402,7 +402,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 11, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261024T053819-alter_column-alter-column-minutes-in-film"
+  "migration_id": "20261024T063903-alter_column-alter-column-minutes-in-film"
 }
 ```
 
@@ -424,7 +424,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 12, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261024T053819-alter_column-alter-column-minutes-in-film-2"
+  "migration_id": "20261024T063903-alter_column-alter-column-minutes-in-film-2"
 }
 ```
 
@@ -454,7 +454,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 13, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261024T053819-alter_column-alter-column-minutes-in-film-3"
+  "migration_id": "20261024T063903-alter_column-alter-column-minutes-in-film-3"
 }
 ```
 
@@ -463,7 +463,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c855-700d-a1ce-24a15e0b4225
+id: 01a16ca2-622e-77f6-96b8-9b911fafe9fb
 title: Nosferatu
 year: 1922
 favourite: false
@@ -490,7 +490,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 14, "operation": "CHANGE COLUMN" }
   ],
-  "migration_id": "20261024T053819-alter_column-alter-column-minutes-in-film-4"
+  "migration_id": "20261024T063903-alter_column-alter-column-minutes-in-film-4"
 }
 ```
 
@@ -499,7 +499,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c855-700d-a1ce-24a15e0b4225
+id: 01a16ca2-622e-77f6-96b8-9b911fafe9fb
 title: Nosferatu
 year: 1922
 favourite: false
@@ -541,7 +541,7 @@ Answer:
   "commits": [
     { "table": "main.public.film", "version": 15, "operation": "RENAME COLUMN" }
   ],
-  "migration_id": "20261024T053819-rename_column-rename-column-favourite-to-lov"
+  "migration_id": "20261024T063903-rename_column-rename-column-favourite-to-lov"
 }
 ```
 
@@ -603,14 +603,14 @@ Answer:
   ],
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 16, "operation": "DROP COLUMNS" }],
-  "migration_id": "20261024T053819-drop_column-drop-column-loved_it-from-film"
+  "migration_id": "20261024T063903-drop_column-drop-column-loved_it-from-film"
 }
 ```
 
 **`undo_migration`**
 
 ```json
-{ "migration_id": "20261024T053819-drop_column-drop-column-loved_it-from-film" }
+{ "migration_id": "20261024T063903-drop_column-drop-column-loved_it-from-film" }
 ```
 
 Answer:
@@ -619,8 +619,8 @@ Answer:
 {
   "ok": true,
   "op": "undo_migration",
-  "undoes": "20261024T053819-drop_column-drop-column-loved_it-from-film",
-  "migration_id": "20261024T053819-undo_migration-undo-20261024t053819-drop_colu",
+  "undoes": "20261024T063903-drop_column-drop-column-loved_it-from-film",
+  "migration_id": "20261024T063903-undo_migration-undo-20261024t063903-drop_colu",
   "conflicts": [],
   "failed": []
 }
@@ -681,7 +681,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 18, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053820-add_column-add-column-added-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-added-to-film"
 }
 ```
 
@@ -714,7 +714,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Sherlock Jr..md"],
   "commits": [{ "table": "main.public.film", "version": 20, "operation": "WRITE" }],
-  "migration_id": "20261024T053820-insert_row-insert-into-film"
+  "migration_id": "20261024T063903-insert_row-insert-into-film-3"
 }
 ```
 
@@ -723,12 +723,12 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c8f6-7574-84e1-70fd6a9c3d59
+id: 01a16ca2-62f5-7e75-b2e7-e4aab44a8a93
 loved_it: false
 title: Sherlock Jr.
 year: 1924
 added: 2026-10-24
-added_at: 2026-10-24T05:38:20Z
+added_at: 2026-10-24T06:39:03Z
 ---
 ```
 
@@ -759,7 +759,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 21, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053820-add_column-add-column-seen_at-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-seen_at-to-film"
 }
 ```
 
@@ -784,7 +784,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 22, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053820-add_column-add-column-viewings-to-film"
+  "migration_id": "20261024T063903-add_column-add-column-viewings-to-film"
 }
 ```
 
@@ -833,7 +833,7 @@ Answer:
     }
   ],
   "commits": [{ "table": "main.public.film", "version": 23, "operation": "UPDATE" }],
-  "migration_id": "20261024T053820-update_row-update-film"
+  "migration_id": "20261024T063903-update_row-update-film-4"
 }
 ```
 
@@ -842,7 +842,7 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c855-700d-a1ce-24a15e0b4225
+id: 01a16ca2-622e-77f6-96b8-9b911fafe9fb
 title: Nosferatu
 year: 1922
 loved_it: false
@@ -884,13 +884,14 @@ Docs: https://datanotes.dev/guides/database-objects/columns.md#describe-what-eac
 
 ## Compute a column from other columns
 
-The engine computes a `generated` column from other columns on every write, and you can’t set it yourself. The expression takes one of three forms:
+The engine computes a `generated` column from other columns on every write, and you can’t set it yourself. The expression takes one of four forms:
 
 * **A column name**: the value of that column
 * **`date(col)`**: the date of `col`, with an optional day shift
 * **A template**: text with `{col}` and `{col:FORMAT}` placeholders
+* **An aggregate**: a count or a total of the items of a `json` list, shown in the next section
 
-`min(…)`, `max(…)` and `coalesce(…)` pick among several columns.
+In a template, `min(…)`, `max(…)` and `coalesce(…)` pick among several columns.
 
 **`create_table`**
 
@@ -942,7 +943,7 @@ Answer:
   "op": "create_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.watch", "version": 0, "operation": "CREATE TABLE" }],
-  "migration_id": "20261024T053820-create_table-create-table-main-public-watch"
+  "migration_id": "20261024T063903-create_table-create-table-main-public-watch"
 }
 ```
 
@@ -968,7 +969,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/watch/2026-10-03T2130.md"],
   "commits": [{ "table": "main.public.watch", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261024T053820-insert_row-insert-into-watch"
+  "migration_id": "20261024T063903-insert_row-insert-into-watch"
 }
 ```
 
@@ -977,7 +978,7 @@ Answer:
 ```markdown
 ---
 table: main.public.watch
-id: 01a16c6a-c91c-75d4-af58-f40270afa72e
+id: 01a16ca2-6327-778b-85f9-d586c0c733a8
 film: His Girl Friday
 occurred_at: 2026-10-03T21:30
 where: home
@@ -1011,6 +1012,168 @@ Docs: https://datanotes.dev/guides/database-objects/columns.md#compute-a-column-
 
 `time_column` names each row’s file after that date-time: here, the time the viewing started. The name follows the database’s `filename` format, `YYYY-MM-DD[T]HHmm` by default.
 
+## Count and total the items of a json list
+
+A `generated` column can count the items of a `json` list of objects. It can also total one field of them. The engine recomputes it on every write of the row, so a total never falls behind its list. These functions read the list:
+
+* **`count(films)`**: the number of items
+* **`count(films.minutes)`**: the items that have a `minutes` value
+* **`sum(films.minutes)`**: the total of the field
+* **`avg(…)`, `min(…)`, `max(…)`**: the average, the smallest and the largest value
+
+A filter after a comma keeps only some items: `count(films, rewatch = true)`. It compares one field with `"text"`, a number, `true` or `false`. It uses `=`, `!=`, `<`, `<=`, `>` or `>=`, and the four orderings compare numbers. `!=` keeps every item that `=` leaves out, items without the field included.
+
+**`create_table`**
+
+```json
+{
+  "name": "marathon",
+  "description": "Nights when I watch several films in a row",
+  "columns": [
+    {
+      "name": "night",
+      "type": "date",
+      "required": true,
+      "description": "The night of the marathon"
+    },
+    {
+      "name": "films",
+      "type": "json",
+      "description": "The films of the night: title, minutes and rewatch"
+    },
+    {
+      "name": "film_count",
+      "type": "integer",
+      "generated": "count(films)",
+      "description": "How many films I watched"
+    },
+    {
+      "name": "rewatches",
+      "type": "integer",
+      "generated": "count(films, rewatch = true)",
+      "description": "Films I had seen before"
+    },
+    {
+      "name": "total_min",
+      "type": "integer",
+      "generated": "sum(films.minutes)",
+      "description": "Minutes of film in the night"
+    },
+    {
+      "name": "longest_min",
+      "type": "integer",
+      "generated": "max(films.minutes)",
+      "description": "Running time of the longest film"
+    },
+    {
+      "name": "avg_min",
+      "type": "number",
+      "generated": "avg(films.minutes, rewatch != true)",
+      "description": "Average running time of the new films"
+    }
+  ],
+  "filename": "{night}"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "create_table",
+  "planned_texts": ["datanotes/metastore.yaml"],
+  "commits": [
+    { "table": "main.public.marathon", "version": 0, "operation": "CREATE TABLE" }
+  ],
+  "migration_id": "20261024T063903-create_table-create-table-main-public-marat"
+}
+```
+
+**`insert_row`**
+
+```json
+{
+  "table": "marathon",
+  "values": {
+    "night": "2026-10-31",
+    "films": [
+      { "title": "Nosferatu", "minutes": 94, "rewatch": true },
+      { "title": "Vampyr", "minutes": 73 },
+      { "title": "Frankenstein", "minutes": 70 }
+    ]
+  }
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "insert_row",
+  "files_created": 1,
+  "planned_creates": ["datanotes/main/public/marathon/2026-10-31.md"],
+  "commits": [{ "table": "main.public.marathon", "version": 1, "operation": "WRITE" }],
+  "migration_id": "20261024T063903-insert_row-insert-into-marathon"
+}
+```
+
+`datanotes/main/public/marathon/2026-10-31.md` now reads:
+
+```markdown
+---
+table: main.public.marathon
+id: 01a16ca2-633b-782d-afde-11976841ccee
+night: 2026-10-31
+films:
+  - title: Nosferatu
+    minutes: 94
+    rewatch: true
+  - title: Vampyr
+    minutes: 73
+  - title: Frankenstein
+    minutes: 70
+film_count: 3
+rewatches: 1
+total_min: 237
+longest_min: 94
+avg_min: 71.5
+---
+```
+
+The type of the column must fit the result. `count` makes a whole number, and `avg` needs a `number` column. An aggregate of a column that isn’t `json` is refused too:
+
+**`add_column`**
+
+```json
+{
+  "table": "marathon",
+  "column": {
+    "name": "nights",
+    "type": "integer",
+    "generated": "count(night)",
+    "description": "Not a list"
+  }
+}
+```
+
+Refused:
+
+```text
+columns[8]: "generated" aggregates "night", which is not a json column
+Hint: count() reads a json column (type json, or a list of json) holding a list of objects, such as [{side: left, min: 12}]; "night" has type date. describe_table shows the type of each column.
+Docs: https://datanotes.dev/guides/database-objects/columns.md#count-and-total-the-items-of-a-json-list (offline: read_docs("guides/database-objects/columns#count-and-total-the-items-of-a-json-list"))
+```
+
+Values the engine can’t total leave the column empty instead of storing a wrong number:
+
+* **No list, or an empty one**: `count` and `sum` are 0, and `avg`, `min` and `max` are empty
+* **An item without the field**: the engine leaves it out
+* **A field that isn’t a number**: the total is empty, as when the column isn’t a list
+
+An `integer` column refuses a write whose total isn’t whole. After a hand edit of the list, `check_table` reports the stale totals and `recompute_columns` fixes them.
+
 ## Let the engine fill identity columns
 
 The engine fills an `identity` column on its own. `filename` keeps the note’s file name, and `created` records when the engine created the row and never changes. Every table also has `id`, the identity column that holds the row’s universally unique identifier (UUID). The meaning of `id` and `created` never changes, so the engine writes their descriptions too.
@@ -1037,7 +1200,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 24, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053820-add_column-add-column-note_name-to-film"
+  "migration_id": "20261024T063904-add_column-add-column-note_name-to-film"
 }
 ```
 
@@ -1058,7 +1221,7 @@ Answer:
   "op": "add_column",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.film", "version": 25, "operation": "ADD COLUMNS" }],
-  "migration_id": "20261024T053820-add_column-add-column-created-to-film"
+  "migration_id": "20261024T063904-add_column-add-column-created-to-film"
 }
 ```
 
@@ -1077,7 +1240,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/film/Charade.md"],
   "commits": [{ "table": "main.public.film", "version": 26, "operation": "WRITE" }],
-  "migration_id": "20261024T053820-insert_row-insert-into-film-2"
+  "migration_id": "20261024T063904-insert_row-insert-into-film"
 }
 ```
 
@@ -1086,14 +1249,14 @@ Answer:
 ```markdown
 ---
 table: main.public.film
-id: 01a16c6a-c932-724c-b71e-793d0c0744ff
+id: 01a16ca2-636a-7001-a23b-b75df0897156
 loved_it: false
 title: Charade
 year: 1963
 added: 2026-10-24
-added_at: 2026-10-24T05:38:20Z
+added_at: 2026-10-24T06:39:04Z
 note_name: Charade
-created: 2026-10-24T05:38:20Z
+created: 2026-10-24T06:39:04Z
 ---
 ```
 
@@ -1134,7 +1297,7 @@ Answer:
   "op": "create_table",
   "planned_texts": ["datanotes/metastore.yaml"],
   "commits": [{ "table": "main.public.actor", "version": 0, "operation": "CREATE TABLE" }],
-  "migration_id": "20261024T053821-create_table-create-table-main-public-actor"
+  "migration_id": "20261024T063905-create_table-create-table-main-public-actor"
 }
 ```
 
@@ -1153,7 +1316,7 @@ Answer:
   "files_created": 1,
   "planned_creates": ["datanotes/main/public/actor/1904/Cary Grant.md"],
   "commits": [{ "table": "main.public.actor", "version": 1, "operation": "WRITE" }],
-  "migration_id": "20261024T053821-insert_row-insert-into-actor"
+  "migration_id": "20261024T063905-insert_row-insert-into-actor"
 }
 ```
 
@@ -1190,7 +1353,7 @@ The engine wrote this file with the columns from this page, in the operations’
 
 ```yaml
 # Metastore (Datanotes): catalogs, schemas, tables, columns, views.
-id: 01a16c6a-c84a-7a99-9e17-51884bf8c6da
+id: 01a16ca2-6220-75b7-ab5a-a37b8500206f
 config:
   history: true
 
@@ -1307,6 +1470,46 @@ catalogs:
                 type: string
                 description: A one-line summary of the viewing, for lists
                 generated: "{film} ({occurred_at:DD/MM HH:mm}, {where})"
+          marathon:
+            description: Nights when I watch several films in a row
+            options:
+              filename: "{night}"
+              archive: _archive
+            columns:
+              - name: id
+                type: string
+                required: true
+                description: "Unique id of the row (UUIDv7): set when the row is created, never changes"
+                unique: true
+                identity: uuid
+                dense: true
+              - name: night
+                type: date
+                required: true
+                description: The night of the marathon
+              - name: films
+                type: json
+                description: "The films of the night: title, minutes and rewatch"
+              - name: film_count
+                type: integer
+                description: How many films I watched
+                generated: count(films)
+              - name: rewatches
+                type: integer
+                description: Films I had seen before
+                generated: count(films, rewatch = true)
+              - name: total_min
+                type: integer
+                description: Minutes of film in the night
+                generated: sum(films.minutes)
+              - name: longest_min
+                type: integer
+                description: Running time of the longest film
+                generated: max(films.minutes)
+              - name: avg_min
+                type: number
+                description: Average running time of the new films
+                generated: avg(films.minutes, rewatch != true)
           actor:
             description: Actors of the films I watch
             options: