datanotes 2.0.1 → 3.1.0

package/dist/docs/reference/operations/schema.md

@@ -0,0 +1,316 @@
+# Schema operations (DDL)
+
+> Operations that define the database: tables, columns, constraints, bases and views.
+
+Operations that define the database: tables, columns, constraints, bases and views. The [overview](https://datanotes.dev/reference/operations/) lists every operation by kind. The MCP server, `datanotes mcp`, offers each operation as an MCP tool of the same name, and `engineTools()` of `datanotes/mcp` gives the same definitions to [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server). `DatanotesClient.call(name, args)` runs one from code. Over HTTP each one is `POST /datanotes/operations/<name>/`, with its arguments as the JSON body: the [HTTP API reference](https://datanotes.dev/api/) lists them.
+
+Every write is validated. Writes to rows and to the schema are journaled and undone with `undo_migration`; `configure_database`, the webhook operations, `vacuum_table` and `sync_semantic_index` are not journaled.
+
+## `create_table`
+
+**Create Table** · write
+
+Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`. Names: lowercase letters, digits, `_` (no dots: pass the catalog and the schema as their own arguments).
+
+* `description` (required): what a row of the table records. Every column needs its own `description` too, what it holds: the table is refused otherwise, with every missing one listed. Descriptions are how agents and people understand the schema, so write them for a reader who never saw the notes. The engine writes those of `id` and of `identity` “uuid” / “created” columns.
+* `columns`: specs like `{"name": "kind", "type": "enum", "values": ["a","b"], "required": true, "description": "What kind of entry the row is"}`. Types: string, integer, number, boolean, date, datetime, enum, link, list (+ `items`), json. Attributes: required, default (`"{now}"`/`"{today}"`), min, max, step, values, `ordered` (enum in order: filters/avg use the position), ref (link target, full `catalog.schema.table` or “self”), unique, label, description, aliases, `generated` (e.g. `"date(occurred_at)"`, `"{name} {surname}"`), `identity` (“filename” | “created”), `vocabulary` (allowed values = names of another table’s rows), `hierarchy: true` (one parent link to its own table), `dense` (written on every row), `inverse` on a link column: the column of the `ref` table that links back (`friends` ↔ `friends`, `children` ↔ `parents`, `partner` ↔ `partner`); writes keep both sides in step.
+* `time_column`: rows named by that date/datetime; otherwise `filename` (e.g. `"{name}"`).
+* The table’s options, as alter_table names them: `aliases` (how agents find it, with the description), `partition`, `exclude`, `archive`, `history` (keep its versions; default: the database’s setting), `autolink_target` (true / false: may automatic links link its rows? default: yes, unless its rows are named by a date or a time, as with `time_column`).
+* `row_template`: markdown body of new rows. Shared columns come from bases: `set_table_bases`.
+* `tags`: key/value labels of the table, strings (`{"domain": "health"}`); list_tables and describe_table return them, alter_table changes them. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them. Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet). Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+| Parameter         | Type         | Required | Default | Description |
+| ----------------- | ------------ | -------- | ------- | ----------- |
+| `name`            | string       | yes      |         |             |
+| `description`     | string \\    | null     |         | `null`      |
+| `columns`         | object\[]    | yes      |         |             |
+| `catalog`         | string \\    | null     |         | `null`      |
+| `schema`          | string \\    | null     |         | `null`      |
+| `time_column`     | string \\    | null     |         | `null`      |
+| `filename`        | string \\    | null     |         | `null`      |
+| `partition`       | string \\    | null     |         | `null`      |
+| `exclude`         | string\[] \\ | null     |         | `null`      |
+| `archive`         | string \\    | null     |         | `null`      |
+| `aliases`         | string\[] \\ | null     |         | `null`      |
+| `history`         | boolean \\   | null     |         | `null`      |
+| `autolink_target` | boolean \\   | null     |         | `null`      |
+| `row_template`    | string \\    | null     |         | `null`      |
+| `fields`          | object \\    | null     |         | `null`      |
+| `tags`            | object \\    | null     |         | `null`      |
+| `dry_run`         | boolean      |          | `false` |             |
+
+## `drop_table`
+
+**Drop Table** · destructive write
+
+Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the definition from `metastore.yaml` and moves all rows to the table’s archive folder (nothing is hard-deleted; undo restores). The transaction log is kept: `restore_table` can bring it back. Refused while a CHECK that follows links, or a `ref_where` / `ref_by`, of another table reads this table through a link (link targets are not rewritten): the conflicts name them; drop or change them first.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/).
+
+| Parameter | Type           | Required | Default | Description |
+| --------- | -------------- | -------- | ------- | ----------- |
+| `table`   | string         | yes      |         |             |
+| `mode`    | `"archive"` \\ | null     |         | `null`      |
+| `dry_run` | boolean        |          | `false` |             |
+
+## `alter_table`
+
+**Alter Table** · destructive write
+
+Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `history` (true | false | “default”), `autolink_target` (true | false | “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. `{"domain": "health"}`; a `null` value removes that tag; `clear_tags: true` removes every tag first, so with `tags` the table keeps exactly those), `archive` (folder name inside the table folder) or `fields` (untyped fields, name → default; a `null` value removes one). Rows, archive and transaction log follow; links are updated; renamed rows keep their old name in `aliases`. A change of metadata only (tags, description, aliases, history, autolink_target, row_template, fields) rewrites the table entry alone: no row is moved or rewritten. Refused when a row cannot fill a pattern. Renaming or moving the table is refused while a CHECK that follows links, or a `ref_where` / `ref_by`, of another table reads it through a link (link targets are not rewritten): the conflicts name them. Use `dry_run` to see `planned_moves`; undo with undo_migration.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+| Parameter         | Type         | Required       | Default | Description                                                          |
+| ----------------- | ------------ | -------------- | ------- | -------------------------------------------------------------------- |
+| `table`           | string       | yes            |         |                                                                      |
+| `catalog`         | string \\    | null           |         | `null`                                                               |
+| `schema`          | string \\    | null           |         | `null`                                                               |
+| `name`            | string \\    | null           |         | `null`                                                               |
+| `partition`       | string \\    | null           |         | `null`                                                               |
+| `filename`        | string \\    | null           |         | `null`                                                               |
+| `description`     | string \\    | null           |         | `null`                                                               |
+| `aliases`         | string\[] \\ | null           |         | `null`                                                               |
+| `history`         | boolean \\   | `"default"` \\ | null    |                                                                      |
+| `autolink_target` | boolean \\   | `"default"` \\ | null    |                                                                      |
+| `exclude`         | string\[] \\ | null           |         | `null`                                                               |
+| `row_template`    | string \\    | null           |         | `null`                                                               |
+| `tags`            | object \\    | null           |         | `null`                                                               |
+| `clear_tags`      | boolean      |                | `false` | Remove every tag first (with `tags`: the table keeps exactly those). |
+| `archive`         | string \\    | null           |         | `null`                                                               |
+| `fields`          | object \\    | null           |         | `null`                                                               |
+| `dry_run`         | boolean      |                | `false` |                                                                      |
+
+## `clone_table`
+
+**Clone Table** · write
+
+CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`. `copy_rows: false` copies the definition only (CREATE TABLE LIKE). `target`: `catalog.schema.table`, `schema.table` (in the source’s catalog) or a name (source’s catalog and schema). Useful for experiments, e.g. a sandbox copy in the `agent` catalog. The clone is a new table, so it needs the descriptions create_table does: a source without them is refused, naming what to describe first (alter_table, alter_column). A past version lacking one gets the one the source has now.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/).
+
+| Parameter   | Type       | Required | Default | Description                                                                    |
+| ----------- | ---------- | -------- | ------- | ------------------------------------------------------------------------------ |
+| `source`    | string     | yes      |         |                                                                                |
+| `target`    | string     | yes      |         |                                                                                |
+| `version`   | integer \\ | null     |         | `null`                                                                         |
+| `timestamp` | string \\  | null     |         | `null`                                                                         |
+| `copy_rows` | boolean    |          | `true`  | Copy the rows (default); false copies the definition only (CREATE TABLE LIKE). |
+| `dry_run`   | boolean    |          | `false` |                                                                                |
+
+## `add_column`
+
+**Add Column** · write
+
+Add a typed column. Sparse by default (written only on rows that have a value — use for metrics, e.g. `{"name": "metric_mood", "type": "integer", "min": 1, "max": 5, "label": "Mood", "aliases": ["mood"], "description": "Mood of the day, 1 = bad, 5 = great"}`). `description` is required: what the column holds, for the agents and people who read the schema (the engine writes it for `identity` “uuid” / “created” columns). `dense: true` in the spec adds it to every row with its `default`. Call `describe_table` first: never add a column whose meaning an existing column (name/label/aliases/description) already covers. Column names are permanent identifiers; only `rename_column` changes them. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them. Generated link columns: `generated: "link({occurred_at:YYYY-MM-DD})"` with `ref` = the days table links each row to the row of `ref` named by the template (its folder read from the schema; the target may not exist yet). Filtered link targets (link columns): `ref_where` (a `where` every target must match) and `ref_by` (a column of the row picks the target level: `{"column": "kind", "levels": ["area", "project", "workstream"]}` or `{"column": "kind", "map": {"area": null, "project": ["area"]}}`; null = top level, no link; `target_column` when the target names it differently: an enum target column must have every value the map allows, a string one takes any value). A link to no row of the table, or to the row itself, is refused too. Existing rows that break them refuse the change; `list_link_targets` lists the valid targets of a row.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/).
+
+| Parameter | Type    | Required | Default | Description                                                                                                |
+| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------- |
+| `table`   | string  | yes      |         |                                                                                                            |
+| `column`  | object  | yes      |         | The column’s spec: name, type, description and its other attributes; `dense: true` writes it on every row. |
+| `dry_run` | boolean |          | `false` |                                                                                                            |
+
+## `rename_column`
+
+**Rename Column** · destructive write
+
+Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column of the table; a row that has a stray `to_column` key with a different value is a conflict, and nothing is written. CHECKs, `ref_where` and `ref_by` that read the column (in this table, or through a link from another table: `parent.kind`) follow the new name. Views and note text that mention the old name are not rewritten.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Columns and types](https://datanotes.dev/guides/database-objects/columns/).
+
+| Parameter     | Type    | Required | Default | Description |
+| ------------- | ------- | -------- | ------- | ----------- |
+| `table`       | string  | yes      |         |             |
+| `from_column` | string  | yes      |         |             |
+| `to_column`   | string  | yes      |         |             |
+| `dry_run`     | boolean |          | `false` |             |
+
+## `drop_column`
+
+**Drop Column** · destructive write
+
+Remove a column from the schema and every row. Previous values are journaled; revert with `undo_migration`. Refused while a CHECK, `ref_where` or `ref_by` of any table reads the column (directly or through a link): the conflicts name them; drop or change them first.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Columns and types](https://datanotes.dev/guides/database-objects/columns/).
+
+| Parameter | Type    | Required | Default | Description        |
+| --------- | ------- | -------- | ------- | ------------------ |
+| `table`   | string  | yes      |         |                    |
+| `column`  | string  | yes      |         | The column’s name. |
+| `dry_run` | boolean |          | `false` |                    |
+
+## `alter_column`
+
+**Alter Column** · destructive write
+
+Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false). Refused with the list of violating rows when existing values do not satisfy the new definition. A different scale means a different column: add a new one instead of rescaling. To rename one enum value use `rename_value`. Dropping an enum value that a `ref_by` (of any table) allows as a target level is refused, naming it.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/).
+
+| Parameter | Type    | Required | Default | Description        |
+| --------- | ------- | -------- | ------- | ------------------ |
+| `table`   | string  | yes      |         |                    |
+| `column`  | string  | yes      |         | The column’s name. |
+| `changes` | object  | yes      |         |                    |
+| `dry_run` | boolean |          | `false` |                    |
+
+## `rename_value`
+
+**Rename Value** · destructive write
+
+Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every row, keeping its position, so an ordered scale is unchanged. CHECKs and `ref_where` conditions on the column (also through a link from another table) and `ref_by` levels / maps that name the value use the new one. Note text (queries, prose) is not rewritten. Refused if `to_value` already exists. Undo with `undo_migration`. Adding or removing classes changes the scale: create a new table instead.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Columns and types](https://datanotes.dev/guides/database-objects/columns/).
+
+| Parameter    | Type    | Required | Default | Description |
+| ------------ | ------- | -------- | ------- | ----------- |
+| `table`      | string  | yes      |         |             |
+| `column`     | string  | yes      |         |             |
+| `from_value` | string  | yes      |         |             |
+| `to_value`   | string  | yes      |         |             |
+| `dry_run`    | boolean |          | `false` |             |
+
+## `comment_on`
+
+**Comment On** · destructive write
+
+COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place. `description` “” removes it. An unknown catalog or schema is refused with the existing ones. describe_database and `system.information_schema.catalogs` / `schemata` show it. Undo with `undo_migration`. A table’s description: alter_table.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/).
+
+| Parameter     | Type      | Required | Default | Description                         |
+| ------------- | --------- | -------- | ------- | ----------------------------------- |
+| `catalog`     | string    | yes      |         |                                     |
+| `schema`      | string \\ | null     |         | `null`                              |
+| `description` | string    | yes      |         | The new description; “” removes it. |
+| `dry_run`     | boolean   |          | `false` |                                     |
+
+## `define_base`
+
+**Define Base** · destructive write
+
+Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`). Tables using it get the columns with the same name and meaning; `ref: "self"` means the inheriting table (e.g. a `parent` column with `hierarchy: true`). `bases` builds on other bases. Descriptions are required, as in create_table: `description` says what the tables of the base share, and each column has its `description` (a column given without one keeps the one the base had for it). Replacing a base changes every inheriting table: `rename_columns` (`{"old": "new"}`) renames the column on their rows, `drop_columns` removes it from their rows; dropping a column without listing it is refused. A renamed column is followed into the CHECKs and `ref_where` / `ref_by` that read it (the base’s own included); dropping one they read is refused, naming them. All affected rows are validated before any write, inherited `ref_where` / `ref_by` and CHECKs that follow links included. Enum columns: `values` and, for each, its meaning in `value_descriptions` (`{"stated": "the user said it", …}`): describe_table shows them and a refused value lists them.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Bases](https://datanotes.dev/guides/database-objects/bases/).
+
+| Parameter        | Type         | Required | Default | Description |
+| ---------------- | ------------ | -------- | ------- | ----------- |
+| `name`           | string       | yes      |         |             |
+| `columns`        | object\[]    | yes      |         |             |
+| `bases`          | string\[] \\ | null     |         | `null`      |
+| `description`    | string \\    | null     |         | `null`      |
+| `rename_columns` | object \\    | null     |         | `null`      |
+| `drop_columns`   | string\[] \\ | null     |         | `null`      |
+| `dry_run`        | boolean      |          | `false` |             |
+
+## `set_table_bases`
+
+**Set Table Bases** · destructive write
+
+Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited columns come after `id` and before the table’s own columns. An own column with the name of an inherited one is replaced by the inherited definition (rows must fit it, its `ref_where` / `ref_by` included); a table may only restyle an inherited column (label, description, aliases, note, dense) with `alter_column`. Dense and generated/identity columns are filled on existing rows.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Bases](https://datanotes.dev/guides/database-objects/bases/).
+
+| Parameter | Type      | Required | Default | Description |
+| --------- | --------- | -------- | ------- | ----------- |
+| `table`   | string    | yes      |         |             |
+| `bases`   | string\[] | yes      |         |             |
+| `dry_run` | boolean   |          | `false` |             |
+
+## `add_constraint`
+
+**Add Constraint** · write
+
+ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g. `{"value": {"gte": 1, "lte": 5}}`. A condition on a column the row leaves empty passes, like SQL; inside `or` / `and` / `not` an empty value is tested as it is (`{"exists": true}` there fails). A key may follow a link column to the row it names, as in queries: `{"parent.kind": "project"}` (further dots follow further links). An empty link passes at the top level and fails inside `or` / `and` / `not`; only the first link of a longer path is skipped when empty (`parent.parent.kind` fails for a row whose parent has no parent). A link to a row that does not exist fails; on a list of links every linked row must match. `not` turns that into a pass: `{"not": {"parent.kind": "area"}}` passes a link to a missing row, so add `"parent.kind": {"exists": true}` to require a real one. Links resolve as in the vault (by path, from the row’s note: same-named rows in two folders stay apart); renaming or moving a linked row keeps them (they follow it). Refused while existing rows violate it (they are listed); then enforced on every write, by the same rule. A write that changes a linked row re-checks the rows that link to it and is refused, listing them, when it breaks them, naming the changed row (in a batch, re-link them first: each step is checked on the vault the earlier ones left); the inverse links a write adds, undo_migration and restore_table are checked too. rename_column / rename_value follow into CHECKs; drop_column of a column a CHECK reads is refused.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/).
+
+| Parameter | Type    | Required | Default | Description |
+| --------- | ------- | -------- | ------- | ----------- |
+| `table`   | string  | yes      |         |             |
+| `name`    | string  | yes      |         |             |
+| `check`   | object  | yes      |         |             |
+| `dry_run` | boolean |          | `false` |             |
+
+## `drop_constraint`
+
+**Drop Constraint** · destructive write
+
+Remove the CHECK constraint `name` from `table`.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/).
+
+| Parameter | Type    | Required | Default | Description |
+| --------- | ------- | -------- | ------- | ----------- |
+| `table`   | string  | yes      |         |             |
+| `name`    | string  | yes      |         |             |
+| `dry_run` | boolean |          | `false` |             |
+
+## `create_view`
+
+**Create View** · destructive write
+
+Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix `vw_` (e.g. `vw_open_tasks`): views share names and folders with tables. `query` takes the select_rows parameters (table, columns, where, order_by, limit, join, group_by, aggregates, expand; relative dates keep it current) and must run now. Or `query: {union: [{table, columns, where}, …], columns, where, order_by, limit, expand}` stacks the rows of several tables (UNION ALL, each row tagged `_source`). Its filters may read the note the view is shown for: `{this.<property>}` (`{this.date+1d}`, `{this.date-1w}` shift a date), `{this.link}`, `{this.name}`, `{this.path}`, filled in from select_rows `this_note` (one view serves every daily note, every project note). `description` and `aliases` let agents find it; `labels` are column headings. Views are selected with `select_rows(table=<view>)`, which may narrow them further (where, columns, order_by, limit; a `where` operator the view already has on a column replaces it). A view writes no note: it lives only in metastore.yaml.
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Views](https://datanotes.dev/guides/database-objects/views/).
+
+| Parameter     | Type         | Required | Default | Description |
+| ------------- | ------------ | -------- | ------- | ----------- |
+| `name`        | string       | yes      |         |             |
+| `query`       | object       | yes      |         |             |
+| `catalog`     | string \\    | null     |         | `null`      |
+| `schema`      | string \\    | null     |         | `null`      |
+| `description` | string \\    | null     |         | `null`      |
+| `aliases`     | string\[] \\ | null     |         | `null`      |
+| `labels`      | object \\    | null     |         | `null`      |
+| `replace`     | boolean      |          | `false` |             |
+| `dry_run`     | boolean      |          | `false` |             |
+
+## `drop_view`
+
+**Drop View** · destructive write
+
+Remove a view from `metastore.yaml` (undo with `undo_migration`).
+
+The schema changes only through operations like this one: never edit metastore.yaml by hand (no validation, no undo).
+
+Examples: [Views](https://datanotes.dev/guides/database-objects/views/).
+
+| Parameter | Type    | Required | Default | Description |
+| --------- | ------- | -------- | ------- | ----------- |
+| `view`    | string  | yes      |         |             |
+| `dry_run` | boolean |          | `false` |             |

package/dist/docs/reference/operations.md

@@ -0,0 +1,96 @@
+# Operations
+
+> Every operation of the HTTP API, offered to agents as an MCP tool of the same name, grouped by kind.
+
+The engine has 54 operations of five kinds, like the statements of a SQL reference. The MCP server, `datanotes mcp`, offers each operation as an MCP tool of the same name, and `engineTools()` of `datanotes/mcp` gives the same definitions to [your own MCP server](https://datanotes.dev/develop/build-on-datanotes/#build-your-own-mcp-server). `DatanotesClient.call(name, args)` runs one from code. Over HTTP each one is `POST /datanotes/operations/<name>/`, with its arguments as the JSON body: the [HTTP API reference](https://datanotes.dev/api/) lists them.
+
+Next to them, `datanotes mcp` offers three tools that read these docs offline, `list_docs`, `read_docs` and `search_docs`; they aren’t operations of the engine ([Read the docs offline](https://datanotes.dev/guides/agents/docs-offline/)). `search_docs` takes required and excluded words, and becomes a hybrid search when the engine has semantic search on ([Search by words and by meaning](https://datanotes.dev/guides/agents/docs-offline/#search-by-words-and-by-meaning)).
+
+## Schema (DDL)
+
+Operations that define the database: tables, columns, constraints, bases and views. [Schema operations (DDL)](https://datanotes.dev/reference/operations/schema/) lists their parameters.
+
+| Operation                                                          | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`create_table`](https://datanotes.dev/reference/operations/schema/#create_table)       | Create a table: `name`, in `catalog` and `schema` (default: the database’s defaults); the definition goes in metastore.yaml, the rows in `<root>/<catalog>/<schema>/<name>/`.                                                                                                                                                                                                                                                                                                  | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
+| [`drop_table`](https://datanotes.dev/reference/operations/schema/#drop_table)           | Drop a table.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | [Tables](https://datanotes.dev/guides/database-objects/tables/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`alter_table`](https://datanotes.dev/reference/operations/schema/#alter_table)         | Alter a table: move it (`catalog`, `schema`), rename it (`name`), change `partition` / `filename` patterns, `description` (changes, never goes: “” is refused), `aliases`, `exclude` folders, `row_template` (“” removes it), `history` (true \| false \| “default”), `autolink_target` (true \| false \| “default”: may automatic links link its rows? default: yes, unless its rows are named by a date or a time) or `tags` (key/value labels merged into the table’s, e.g. | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                |
+| [`clone_table`](https://datanotes.dev/reference/operations/schema/#clone_table)         | CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows (deep clone), optionally as of a `version` / `timestamp`.                                                                                                                                                                                                                                                                                                                            | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                                                                                                                                                                                       |
+| [`add_column`](https://datanotes.dev/reference/operations/schema/#add_column)           | Add a typed column.                                                                                                                                                                                                                                                                                                                                                                                                                                                            | [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                                                                                                                                                                                                                                     |
+| [`rename_column`](https://datanotes.dev/reference/operations/schema/#rename_column)     | Rename a column in metastore.yaml and on every row.                                                                                                                                                                                                                                                                                                                                                                                                                            | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`drop_column`](https://datanotes.dev/reference/operations/schema/#drop_column)         | Remove a column from the schema and every row.                                                                                                                                                                                                                                                                                                                                                                                                                                 | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`alter_column`](https://datanotes.dev/reference/operations/schema/#alter_column)       | Change a column’s attributes (type, min/max/step, values, required, default, label, aliases, description, note, `ref_where`, `ref_by` (see list_link_targets); `null` removes an attribute, except `description`, which changes but never goes (null or “” is refused); `dense` true/false).                                                                                                                                                                                   | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`rename_value`](https://datanotes.dev/reference/operations/schema/#rename_value)       | Rename one value of an enum column (e.g.                                                                                                                                                                                                                                                                                                                                                                                                                                       | [Columns and types](https://datanotes.dev/guides/database-objects/columns/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| [`comment_on`](https://datanotes.dev/reference/operations/schema/#comment_on)           | COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its schemas (`catalog` and `schema`) in metastore.yaml: what it holds, so agents pick the right place.                                                                                                                                                                                                                                                                          | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`define_base`](https://datanotes.dev/reference/operations/schema/#define_base)         | Create or replace a base: a named set of columns (same spec as `create_table`) that tables inherit, like a parent class (`bases` in `metastore.yaml`).                                                                                                                                                                                                                                                                                                                         | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`set_table_bases`](https://datanotes.dev/reference/operations/schema/#set_table_bases) | Set the bases a table inherits from (`bases`, in order; `[]` removes them).                                                                                                                                                                                                                                                                                                                                                                                                    | [Bases](https://datanotes.dev/guides/database-objects/bases/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`add_constraint`](https://datanotes.dev/reference/operations/schema/#add_constraint)   | ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match, e.g.                                                                                                                                                                                                                                                                                                                                                                                  | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`drop_constraint`](https://datanotes.dev/reference/operations/schema/#drop_constraint) | Remove the CHECK constraint `name` from `table`.                                                                                                                                                                                                                                                                                                                                                                                                                               | [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`create_view`](https://datanotes.dev/reference/operations/schema/#create_view)         | Create (or `replace`) a view: a named select stored in metastore.yaml.                                                                                                                                                                                                                                                                                                                                                                                                         | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`drop_view`](https://datanotes.dev/reference/operations/schema/#drop_view)             | Remove a view from `metastore.yaml` (undo with `undo_migration`).                                                                                                                                                                                                                                                                                                                                                                                                              | [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+## Rows (DML)
+
+Operations that write rows: insert, update, merge, delete, move, adopt and batch. [Row operations (DML)](https://datanotes.dev/reference/operations/rows/) lists their parameters.
+
+| Operation                                                            | What it does                                                                                                                                                                                                                                                                 | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`insert_row`](https://datanotes.dev/reference/operations/rows/#insert_row)               | Insert a row (new note).                                                                                                                                                                                                                                                     | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
+| [`update_row`](https://datanotes.dev/reference/operations/rows/#update_row)               | Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when the row does not exist (or id and path disagree).                                                                                                                                | [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/)                                                                                                                                                                                                  |
+| [`update_rows`](https://datanotes.dev/reference/operations/rows/#update_rows)             | Update every row matching `where` (required: `{}` is every row).                                                                                                                                                                                                             | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| [`merge_rows`](https://datanotes.dev/reference/operations/rows/#merge_rows)               | MERGE (upsert) `rows` into `table` by the key columns `on` (e.g.                                                                                                                                                                                                             | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| [`delete_rows`](https://datanotes.dev/reference/operations/rows/#delete_rows)             | Delete rows matching `where`.                                                                                                                                                                                                                                                | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| [`move_rows`](https://datanotes.dev/reference/operations/rows/#move_rows)                 | Move rows matching `where` (required: `{}` is every row) to another table (e.g.                                                                                                                                                                                              | [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| [`adopt_rows`](https://datanotes.dev/reference/operations/rows/#adopt_rows)               | Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and links: `rename` keys (`{"data": "occurred_at"}`), `set` for all, `per_row` values by note path (`{"Home/x.md": {"zone": "[[Kitchen]]"}}`), `drop` keys the table does not have. | [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| [`batch`](https://datanotes.dev/reference/operations/rows/#batch)                         | Several writes that succeed or fail together.                                                                                                                                                                                                                                | [Views](https://datanotes.dev/guides/database-objects/views/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`align_relations`](https://datanotes.dev/reference/operations/rows/#align_relations)     | Add the reciprocal links missing on a table’s `inverse` link columns (e.g.                                                                                                                                                                                                   | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`recompute_columns`](https://datanotes.dev/reference/operations/rows/#recompute_columns) | Bring generated and identity columns up to date (all rows, or only `paths`), e.g.                                                                                                                                                                                            | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+
+## Queries
+
+Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph. [Query operations](https://datanotes.dev/reference/operations/queries/) lists their parameters.
+
+| Operation                                                               | What it does                                                                                                                                                                                                | Examples                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`select_rows`](https://datanotes.dev/reference/operations/queries/#select_rows)             | Query rows: `{table, total, rows: [{path, ...}]}`.                                                                                                                                                          | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Views](https://datanotes.dev/guides/database-objects/views/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Validation](https://datanotes.dev/guides/data-quality/validation/), [CHECK constraints](https://datanotes.dev/guides/data-quality/check-constraints/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Read and filter rows](https://datanotes.dev/guides/read-and-write/read-and-filter/), [Joins and aggregates](https://datanotes.dev/guides/read-and-write/joins-and-aggregates/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Batch writes](https://datanotes.dev/guides/read-and-write/batch/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
+| [`list_link_targets`](https://datanotes.dev/reference/operations/queries/#list_link_targets) | The rows a link column may point to, for one row: what an agent or a picker offers before writing the link.                                                                                                 | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| [`read_note`](https://datanotes.dev/reference/operations/queries/#read_note)                 | Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at, created_at, size}`.                                                                                             | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/), [Read and search notes](https://datanotes.dev/guides/search/text/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| [`list_folder`](https://datanotes.dev/reference/operations/queries/#list_folder)             | The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted; dot-files and dot-folders are left out.                                                                       | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Write and move rows](https://datanotes.dev/guides/read-and-write/write-rows/), [Read and search notes](https://datanotes.dev/guides/search/text/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| [`search_notes`](https://datanotes.dev/reference/operations/queries/#search_notes)           | Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the note’s path or text; there are no operators.                                                                      | [Read and search notes](https://datanotes.dev/guides/search/text/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| [`semantic_search`](https://datanotes.dev/reference/operations/queries/#semantic_search)     | Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet, table?}]}`, one result per note (its best passage), best first.                                                  | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`graph_neighbors`](https://datanotes.dev/reference/operations/queries/#graph_neighbors)     | Direct neighbours of notes: what they link to (`out`) and what links to them (`in`, backlinks), with counts per edge label.                                                                                 | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`graph_traverse`](https://datanotes.dev/reference/operations/queries/#graph_traverse)       | Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).                                                                                      | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [`graph_path`](https://datanotes.dev/reference/operations/queries/#graph_path)               | Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`): `found`, `length` and `path`: the steps (`from`, `label`, `direction`, `to`). | [Walk the link graph](https://datanotes.dev/guides/search/link-graph/)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+
+## History
+
+Operations on the journal, a table’s versions, the change feed and webhooks: undo, time travel, restore and vacuum. [History operations](https://datanotes.dev/reference/operations/history/) lists their parameters.
+
+| Operation                                                             | What it does                                                                                                                                                                                                                                                                                                                                                                  | Examples                                                                                                                                                                                                             |
+| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`list_migrations`](https://datanotes.dev/reference/operations/history/#list_migrations)   | The operation journal, newest first: `total` (the matching operations) and `migrations`, each with `migration_id` (for undo_migration), `op`, `summary`, `table` (when it was about one), `executed_at`, `notes_changed`, `files_changed`, `undone`, `undoes`, `files_failed`, `by` (the agent), and `members` (a batch’s operations) or `batch` (the batch of an operation). | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/)                                                                                                                |
+| [`undo_migration`](https://datanotes.dev/reference/operations/history/#undo_migration)     | Revert a journaled table operation by its `migration_id`.                                                                                                                                                                                                                                                                                                                     | [Columns and types](https://datanotes.dev/guides/database-objects/columns/), [Views](https://datanotes.dev/guides/database-objects/views/), [Journal and undo](https://datanotes.dev/guides/history/journal-and-undo/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/) |
+| [`describe_history`](https://datanotes.dev/reference/operations/history/#describe_history) | DESCRIBE HISTORY: the table’s versions, newest first — `version`, `timestamp`, `operation` (CREATE TABLE, WRITE, UPDATE, DELETE, MERGE, ALTER TABLE, ADD COLUMNS, RESTORE, UNDO, …; `EXTERNAL_EDIT` = changed outside the engine: an editor, git, sync), `operation_metrics` and `migration_id` (undo).                                                                       | [Table history and time travel](https://datanotes.dev/guides/history/table-history/), [Restore a table or the database](https://datanotes.dev/guides/history/restore/)                                                                                         |
+| [`table_changes`](https://datanotes.dev/reference/operations/history/#table_changes)       | Change data feed between two versions (both included, end defaults to latest): one entry per row change with its values plus `_change_type` (insert, delete, update_preimage, update_postimage, metadata), `_commit_version`, `_commit_timestamp`, `_operation`, `path`.                                                                                                      | [Table history and time travel](https://datanotes.dev/guides/history/table-history/)                                                                                                                                                      |
+| [`restore_table`](https://datanotes.dev/reference/operations/history/#restore_table)       | RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state — rows added since are deleted, changed rows get their old content, removed rows come back (a dropped table is re-created).                                                                                                                                                             | [Restore a table or the database](https://datanotes.dev/guides/history/restore/)                                                                                                                                                          |
+| [`restore_database`](https://datanotes.dev/reference/operations/history/#restore_database) | RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or to `before_migration` (a `migration_id` or a `batch`: every table as it was just before that operation ran — to rewind an agent’s run).                                                                                                                                    | [Restore a table or the database](https://datanotes.dev/guides/history/restore/)                                                                                                                                                          |
+| [`vacuum_table`](https://datanotes.dev/reference/operations/history/#vacuum_table)         | Delete transaction-log history older than `retain_from_version` (default: keep only the latest version); time travel before it becomes impossible.                                                                                                                                                                                                                            | [Vacuum old history](https://datanotes.dev/guides/history/vacuum/)                                                                                                                                                                        |
+| [`list_changes`](https://datanotes.dev/reference/operations/history/#list_changes)         | Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes and from hand edits (`source: external`).                                                                                                                                                                                                                                       | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Change data feed](https://datanotes.dev/guides/history/change-data-feed/)                                                                                                                |
+| [`list_webhooks`](https://datanotes.dev/reference/operations/history/#list_webhooks)       | Webhooks of the change feed: id, url, filter (tables, ops, columns, exclude_actor), `cursor` (last change delivered), `status` (ok, failing, disabled), `last_delivery`, `last_error`.                                                                                                                                                                                        | [Change data feed](https://datanotes.dev/guides/history/change-data-feed/)                                                                                                                                                                |
+| [`create_webhook`](https://datanotes.dev/reference/operations/history/#create_webhook)     | Push row changes to a URL (a service that would rather be called than poll `list_changes`): batches of up to 100 events POSTed as `{webhook, events, last}`, signed with `X-Datanotes-Signature: sha256=<HMAC of the body>`, retried with backoff until a 2xx.                                                                                                                | [Change data feed](https://datanotes.dev/guides/history/change-data-feed/)                                                                                                                                                                |
+| [`delete_webhook`](https://datanotes.dev/reference/operations/history/#delete_webhook)     | Stop and remove a webhook (by `id` from list_webhooks).                                                                                                                                                                                                                                                                                                                       | [Change data feed](https://datanotes.dev/guides/history/change-data-feed/)                                                                                                                                                                |
+
+## Auxiliary
+
+Operations that describe and check the database, configure it and maintain its indexes. [Auxiliary operations](https://datanotes.dev/reference/operations/auxiliary/) lists their parameters.
+
+| Operation                                                                             | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Examples                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`list_tables`](https://datanotes.dev/reference/operations/auxiliary/#list_tables)                         | List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it wherever a table is expected; `metrics.mood` or `mood` also work when unambiguous), `path` and, when declared, `description`, `aliases` (other words for what it records) and `tags`.                                                                                                                                                                                                                                                                                                                                                                        | [Tables](https://datanotes.dev/guides/database-objects/tables/), [Views](https://datanotes.dev/guides/database-objects/views/)                                                                                                                                                                          |
+| [`describe_table`](https://datanotes.dev/reference/operations/auxiliary/#describe_table)                   | Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`, `catalog`, `schema`, `description`, `aliases`, `layout` (`folder`, `row_folder`: the folder pattern of new rows, `archive`), `options` (`partition`, `filename`, `archive`, `exclude`), typed `columns` with label/aliases/description and the dense flag, `untyped_fields`, `row_count`, and when set: `tags`, `bases` (the bases it inherits from, in order), `constraints` (its CHECKs, name → where), `row_template`, `history`, `autolink_target`, `fields` (their values).                                                                            | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Bases](https://datanotes.dev/guides/database-objects/bases/), [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/)                  |
+| [`describe_database`](https://datanotes.dev/reference/operations/auxiliary/#describe_database)             | Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely, but it is read-only for agents and changes only through the schema operations), configuration (default catalog and schema, row partition and file-name formats, archive folder, time zone, history, automatic links), journal folder, `bases` (shared column sets and the tables using them), `catalogs` → `schemas` → `tables` (with `row_count`, `tags`, and `unreadable_count` when some rows’ front matter cannot be read) and `views`; catalogs and schemas show their `comment` (set with `comment_on`).                                                 | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/)                                                                                                                          |
+| [`configure_database`](https://datanotes.dev/reference/operations/auxiliary/#configure_database)           | Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database folder; links follow; revert by renaming back), `default_catalog`, `default_schema`, `default_partition` (“” = flat) and `default_filename` (date formats for new time-based tables), `archive_folder`, `timezone` (IANA; completes date-times written without offset), `history` (transaction log for every table: true in a database the engine creates, false when `config` lacks it, as in a metastore from before 3.0.0; change it only on the user’s request), `autolink` (the text a write puts in a body links the notes it mentions; on by default). | [Catalogs, schemas and the database](https://datanotes.dev/guides/database-objects/catalogs-and-schemas/), [Tables](https://datanotes.dev/guides/database-objects/tables/), [Automatic links](https://datanotes.dev/guides/read-and-write/automatic-links/), [Table history and time travel](https://datanotes.dev/guides/history/table-history/) |
+| [`check_table`](https://datanotes.dev/reference/operations/auxiliary/#check_table)                         | Validate every row against the table (required, types, ranges, enums, links, unknown columns, CHECK constraints, those that follow links included, filtered link targets (ref_where / ref_by), stale generated/identity values, missing inverse links, front matter that cannot be read: code `unreadable`, with no column, for a note whose `table` line names the table but whose YAML is broken, which every other read leaves out).                                                                                                                                                                                                                   | [Relations and hierarchies](https://datanotes.dev/guides/database-objects/relations/), [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Find rows that break the schema](https://datanotes.dev/guides/data-quality/check-table/)                                                                        |
+| [`infer_table`](https://datanotes.dev/reference/operations/auxiliary/#infer_table)                         | Read-only schema inference from notes’ front matter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | [Hand edits](https://datanotes.dev/guides/data-quality/hand-edits/), [Import existing notes](https://datanotes.dev/guides/read-and-write/import-notes/)                                                                                                                                                 |
+| [`describe_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#describe_semantic_index) | The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`, `running`, `last_sync`, `last_error`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |
+| [`sync_semantic_index`](https://datanotes.dev/reference/operations/auxiliary/#sync_semantic_index)         | Bring the semantic search index up to date: embed the notes changed since the last run (the engine also does it on its own about ten seconds after edits).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | [Find notes by meaning](https://datanotes.dev/guides/search/semantic/)                                                                                                                                                                                                             |