datanotes 2.0.0 → 3.0.0

package/dist/docs/guides/read-and-write/write-rows.md

@@ -0,0 +1,573 @@
+# Write and move rows
+
+> Insert a row, update one row or many, edit a note’s text, upsert, guard against concurrent edits, delete and move rows.
+
+The engine checks every write before it changes anything, records it in the journal, and lets you undo it with `undo_migration`. A write answers with the notes it created, changed, moved or deleted.
+
+The first example adds a row to the film diary of [Tables](https://datanotes.dev/guides/database-objects/tables/); the others work on a small diary of five classic films.
+
+When several clients write at once, the engine checks each write on the latest data. [Concurrent writes](https://datanotes.dev/develop/concurrency/) explains the rules and when to retry.
+
+## Insert a row
+
+`insert_row` writes a new note. The engine fills in the default (`status`) and an `id`, and names the note from `filename`. `body` sets the note’s text.
+
+**`insert_row`**
+
+```json
+{
+  "table": "film",
+  "values": { "title": "Metropolis", "year": 1927, "minutes": 153 },
+  "body": "Next on my list. Two and a half hours of silent film need a quiet evening.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "insert_row",
+  "files_created": 1,
+  "planned_creates": ["datanotes/main/public/film/Metropolis.md"],
+  "commits": [{ "table": "main.public.film", "version": 1, "operation": "WRITE" }],
+  "migration_id": "20261012T071946-insert_row-insert-into-film"
+}
+```
+
+`datanotes/main/public/film/Metropolis.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-5925-7551-9fc3-ca301818d73d
+title: Metropolis
+year: 1927
+minutes: 153
+status: to watch
+---
+Next on my list. Two and a half hours of silent film need a quiet evening.
+```
+
+## Pick a free file name for a new row
+
+Without `path`, the table’s filename pattern names the new note. When another note has that name, the engine adds `-2`, `-3` and so on.
+
+A `path` you pass must be free. Windows and macOS see `Nosferatu.md` and `nosferatu.md` as one file. So on every system, the engine refuses a name that another note has in another case, and names that note:
+
+**`insert_row`**
+
+```json
+{
+  "table": "film",
+  "values": { "title": "The Kid", "year": 1921 },
+  "path": "datanotes/main/public/film/nosferatu.md"
+}
+```
+
+Refused:
+
+```text
+insert_row refused — nothing was written:
+conflict datanotes/main/public/film/nosferatu.md: note already exists in another case: "datanotes/main/public/film/Nosferatu.md" (one file on Windows and macOS)
+Hint: Another note has this file name, maybe in another case (Windows and macOS see one file): pass another "path", give the row values its table's filename pattern turns into a free name, or update that note with update_row. Then call insert_row again.
+Docs: https://datanotes.dev/guides/read-and-write/write-rows.md#pick-a-free-file-name-for-a-new-row (offline: read_docs("guides/read-and-write/write-rows#pick-a-free-file-name-for-a-new-row"))
+```
+
+## Update one row
+
+`update_row` changes exactly one row, which you address by `path` or by its `id`. `set` sets columns and `unset` removes them. The engine checks the whole row before it writes anything.
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/His Girl Friday.md",
+  "set": { "status": "watched", "rating": 5, "tags": ["screwball"] }
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/His Girl Friday.md",
+      "set": { "status": "watched", "rating": 5, "tags": ["screwball"] },
+      "remove": []
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 6, "operation": "UPDATE" }],
+  "migration_id": "20261012T071951-update_row-update-film"
+}
+```
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/His Girl Friday.md",
+  "unset": ["tags"]
+}
+```
+
+The engine refuses a path that isn’t a row, and creates nothing:
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Night of the Living Dead.md",
+  "set": { "rating": 4 }
+}
+```
+
+Refused:
+
+```text
+film has no row at datanotes/main/public/film/Night of the Living Dead.md
+Hint: Name the row by its "path" (the vault path of its note, e.g. "Films/Metropolis.md") or its "id": select_rows with columns ["path", "id"] and a "where" finds them.
+Docs: https://datanotes.dev/guides/read-and-write/write-rows.md#update-one-row (offline: read_docs("guides/read-and-write/write-rows#update-one-row"))
+```
+
+## Edit a note’s text
+
+`update_row` edits the note’s text with these arguments:
+
+* **`body_sections`**: replaces the text under one heading and leaves the rest of the note alone; the engine adds a missing heading at the end
+* **`body_append`** and **`body_prepend`**: add text after or before the existing text
+* **`body`**: replaces all of the text
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Nosferatu.md",
+  "body_sections": {
+    "Rewatch": "Watched it again in October. The shadow on the stairs still works a century later."
+  },
+  "body_append": "Next: Metropolis, for more German Expressionism.\n"
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Nosferatu.md",
+      "set": {},
+      "remove": [],
+      "body": true
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 8, "operation": "UPDATE" }],
+  "migration_id": "20261012T071951-update_row-update-film-3",
+  "ambiguous_mentions": [
+    {
+      "path": "datanotes/main/public/film/Nosferatu.md",
+      "text": "Metropolis",
+      "reason": "sentence_start",
+      "candidates": ["datanotes/main/public/film/Metropolis.md"],
+      "context": "Next: Metropolis, for more German Expressionism.",
+      "hint": "\"Metropolis\" starts a sentence, a line or a label, so its capital does not make it a name: read the note and the text around it, then write the link with update_row and autolink: false, or leave the text as it is."
+    }
+  ]
+}
+```
+
+`datanotes/main/public/film/Nosferatu.md` now reads:
+
+```markdown
+---
+table: main.public.film
+id: 01a12efb-6c2e-7852-8b4b-ed121d84aec5
+title: Nosferatu
+year: 1922
+status: watched
+rating: 5
+---
+## Notes
+
+
+Max Schreck doesn’t need a single word.
+
+
+## Rewatch
+
+
+Watched it again in October. The shadow on the stairs still works a century later.
+
+
+Next: Metropolis, for more German Expressionism.
+```
+
+The engine links Metropolis, the note of another film, and lists the link in `links_added`. [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/) shows which names it links.
+
+## Guard a write against concurrent edits with `expect`
+
+A person may edit a note between an agent’s read and its write. `expect` makes the write a compare-and-set: it goes through only if the row still has those values.
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Sherlock Jr..md",
+  "expect": { "status": "to watch" },
+  "set": { "status": "watched" }
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_row",
+  "notes_changed": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Sherlock Jr..md",
+      "set": { "status": "watched" },
+      "remove": []
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 9, "operation": "UPDATE" }],
+  "migration_id": "20261012T071951-update_row-update-film-4"
+}
+```
+
+Run the same call again. `status` is no longer `to watch`, so the engine writes nothing.
+
+**`update_row`**
+
+```json
+{
+  "table": "film",
+  "path": "datanotes/main/public/film/Sherlock Jr..md",
+  "expect": { "status": "to watch" },
+  "set": { "status": "watched" }
+}
+```
+
+Refused:
+
+```text
+update_row refused — nothing was written:
+conflict datanotes/main/public/film/Sherlock Jr..md: row changed: expected status = "to watch", found "watched" — read it again
+Hint: The row changed since you read it: read it again (select_rows), then retry update_row with "expect" set to what you read.
+Docs: https://datanotes.dev/guides/read-and-write/write-rows.md#guard-a-write-against-concurrent-edits-with-expect (offline: read_docs("guides/read-and-write/write-rows#guard-a-write-against-concurrent-edits-with-expect"))
+```
+
+## Update many rows
+
+`update_rows` changes every row matching `where`. `expect_count` guards the write: the engine refuses it unless exactly that many rows match, so a filter that’s too broad changes nothing.
+
+**`update_rows`**
+
+```json
+{
+  "table": "film",
+  "where": { "status": "watched" },
+  "set": { "tags": ["seen-2026"] },
+  "expect_count": 2
+}
+```
+
+Refused:
+
+```text
+update_rows refused — nothing was written:
+conflict datanotes/main/public/film: "where" matched 3 rows, expected 2: nothing was written
+Hint: Check the rows with select_rows and the same "where", then narrow it or change expect_count.
+Docs: https://datanotes.dev/guides/read-and-write/write-rows.md#update-many-rows (offline: read_docs("guides/read-and-write/write-rows#update-many-rows"))
+```
+
+**`update_rows`**
+
+```json
+{
+  "table": "film",
+  "where": { "status": "watched" },
+  "set": { "tags": ["seen-2026"] },
+  "expect_count": 3
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "update_rows",
+  "notes_changed": 3,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/His Girl Friday.md",
+      "set": { "tags": ["seen-2026"] },
+      "remove": []
+    },
+    {
+      "path": "datanotes/main/public/film/Nosferatu.md",
+      "set": { "tags": ["seen-2026"] },
+      "remove": []
+    },
+    {
+      "path": "datanotes/main/public/film/Sherlock Jr..md",
+      "set": { "tags": ["seen-2026"] },
+      "remove": []
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 10, "operation": "UPDATE" }],
+  "migration_id": "20261012T071951-update_rows-update-film"
+}
+```
+
+## Insert or update rows with `merge_rows`
+
+`merge_rows` is an upsert: it inserts rows or updates existing ones. A row whose `on` columns match an existing row updates that row, and the engine inserts the others. The whole merge is one operation with one undo.
+
+**`merge_rows`**
+
+```json
+{
+  "table": "film",
+  "on": ["title"],
+  "rows": [
+    { "title": "Sherlock Jr.", "rating": 4 },
+    { "title": "Battleship Potemkin", "year": 1925 }
+  ]
+}
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "merge_rows",
+  "notes_changed": 1,
+  "files_created": 1,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Sherlock Jr..md",
+      "set": { "rating": 4 },
+      "remove": []
+    }
+  ],
+  "planned_creates": ["datanotes/main/public/film/Battleship Potemkin.md"],
+  "commits": [{ "table": "main.public.film", "version": 11, "operation": "MERGE" }],
+  "migration_id": "20261012T071951-merge_rows-merge-2-rows-into-film"
+}
+```
+
+**`select_rows`**
+
+```json
+{
+  "table": "film",
+  "columns": ["title", "rating", "status"],
+  "where": { "title": { "in": ["Sherlock Jr.", "Battleship Potemkin"] } }
+}
+```
+
+Answer:
+
+```json
+{
+  "table": "main.public.film",
+  "total": 2,
+  "rows": [
+    {
+      "path": "datanotes/main/public/film/Battleship Potemkin.md",
+      "title": "Battleship Potemkin",
+      "rating": null,
+      "status": "to watch"
+    },
+    {
+      "path": "datanotes/main/public/film/Sherlock Jr..md",
+      "title": "Sherlock Jr.",
+      "rating": 4,
+      "status": "watched"
+    }
+  ]
+}
+```
+
+## Delete rows into the archive
+
+By default, `delete_rows` moves the matching rows to the table’s archive folder, so you lose nothing. `mode: "delete"` moves them to the trash instead, and the journal keeps their content for undo. Always pass `where`: without it, every row matches.
+
+**`delete_rows`**
+
+```json
+{ "table": "film", "where": { "title": "Battleship Potemkin" } }
+```
+
+Answer:
+
+```json
+{
+  "ok": true,
+  "op": "delete_rows",
+  "files_moved": 1,
+  "planned_moves": [
+    {
+      "from": "datanotes/main/public/film/Battleship Potemkin.md",
+      "to": "datanotes/main/public/film/_archive/Battleship Potemkin.md"
+    }
+  ],
+  "commits": [{ "table": "main.public.film", "version": 12, "operation": "DELETE" }],
+  "migration_id": "20261012T071951-delete_rows-archive-1-rows-of-film"
+}
+```
+
+**`list_folder`**
+
+```json
+{ "folder": "datanotes/main/public/film/_archive" }
+```
+
+Answer:
+
+```json
+{
+  "folder": "datanotes/main/public/film/_archive",
+  "folders": [],
+  "files": ["datanotes/main/public/film/_archive/Battleship Potemkin.md"]
+}
+```
+
+## Move rows to another table
+
+`move_rows` moves rows to another table. During the move, it can `rename` keys, `set` values and `drop` keys, and it checks every row against the destination first. The engine reports keys the destination doesn’t know and never drops them silently. `relocate: true` also moves the notes to the destination’s folder.
+
+**`create_table`**
+
+```json
+{
+  "name": "watchlist",
+  "description": "Films I plan to watch soon",
+  "columns": [
+    {
+      "name": "title",
+      "type": "string",
+      "required": true,
+      "description": "The film's title"
+    },
+    { "name": "released", "type": "integer", "description": "Year the film came out" }
+  ],
+  "filename": "{title}"
+}
+```
+
+**`move_rows`**
+
+```json
+{
+  "table": "film",
+  "to_table": "watchlist",
+  "where": { "status": "to watch" },
+  "relocate": true
+}
+```
+
+Refused:
+
+```text
+move_rows refused — nothing was written:
+invalid datanotes/main/public/film/Battleship Potemkin.md: year is not a column of table "watchlist"
+invalid datanotes/main/public/film/Battleship Potemkin.md: status is not a column of table "watchlist"
+invalid datanotes/main/public/film/Charade.md: year is not a column of table "watchlist"
+invalid datanotes/main/public/film/Charade.md: status is not a column of table "watchlist"
+invalid datanotes/main/public/film/Metropolis.md: year is not a column of table "watchlist"
+invalid datanotes/main/public/film/Metropolis.md: status is not a column of table "watchlist"
+invalid datanotes/main/public/film/The General.md: year is not a column of table "watchlist"
+invalid datanotes/main/public/film/The General.md: status is not a column of table "watchlist"
+Hint: Write only the table's columns: describe_table lists them. To keep a new front matter key, add_column first. Then call move_rows again (dry_run: true checks without writing).
+Docs: https://datanotes.dev/guides/database-objects/tables.md#describe-a-table-before-writing-to-it (offline: read_docs("guides/database-objects/tables#describe-a-table-before-writing-to-it"))
+```
+
+The watchlist has no `status`, `tags` or `rating` column, so the call drops them, and `year` becomes `released`:
+
+**`move_rows`**
+
+```json
+{
+  "table": "film",
+  "to_table": "watchlist",
+  "where": { "status": "to watch" },
+  "rename": { "year": "released" },
+  "drop": ["status", "tags", "rating"],
+  "relocate": true
+}
+```
+
+Answer (51 lines)
+
+```json
+{
+  "ok": true,
+  "op": "move_rows",
+  "notes_changed": 4,
+  "files_moved": 4,
+  "planned_edits": [
+    {
+      "path": "datanotes/main/public/film/Battleship Potemkin.md",
+      "set": { "table": "main.public.watchlist", "released": 1925 },
+      "remove": ["year", "status"]
+    },
+    {
+      "path": "datanotes/main/public/film/Charade.md",
+      "set": { "table": "main.public.watchlist", "released": 1963 },
+      "remove": ["year", "status"]
+    },
+    {
+      "path": "datanotes/main/public/film/Metropolis.md",
+      "set": { "table": "main.public.watchlist", "released": 1927 },
+      "remove": ["year", "status"]
+    },
+    {
+      "path": "datanotes/main/public/film/The General.md",
+      "set": { "table": "main.public.watchlist", "released": 1926 },
+      "remove": ["year", "status"]
+    }
+  ],
+  "planned_moves": [
+    {
+      "from": "datanotes/main/public/film/Battleship Potemkin.md",
+      "to": "datanotes/main/public/watchlist/Battleship Potemkin.md"
+    },
+    {
+      "from": "datanotes/main/public/film/Charade.md",
+      "to": "datanotes/main/public/watchlist/Charade.md"
+    },
+    {
+      "from": "datanotes/main/public/film/Metropolis.md",
+      "to": "datanotes/main/public/watchlist/Metropolis.md"
+    },
+    {
+      "from": "datanotes/main/public/film/The General.md",
+      "to": "datanotes/main/public/watchlist/The General.md"
+    }
+  ],
+  "commits": [
+    { "table": "main.public.film", "version": 22, "operation": "MOVE ROWS" },
+    { "table": "main.public.watchlist", "version": 1, "operation": "MOVE ROWS" }
+  ],
+  "migration_id": "20261012T071951-move_rows-move-4-rows-from-film-to-watch"
+}
+```