Operations

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. 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 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). 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).

Schema (DDL)

Operations that define the database: tables, columns, constraints, bases and views. Schema operations (DDL) lists their parameters.

Operation	What it does	Examples
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, Tables, Columns and types, Bases, Relations and hierarchies, Write and move rows, Automatic links, Import existing notes, Table history and time travel
drop_table	Drop a table.	Tables
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, Tables, Automatic links, Import existing notes, Table history and time travel
clone_table	CREATE TABLE target CLONE source: same definition plus independent copies of its rows (deep clone), optionally as of a version / timestamp.	Tables, Bases, Table history and time travel
add_column	Add a typed column.	Columns and types, Relations and hierarchies, Import existing notes
rename_column	Rename a column in metastore.yaml and on every row.	Columns and types
drop_column	Remove a column from the schema and every row.	Columns and types
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, Columns and types, Relations and hierarchies
rename_value	Rename one value of an enum column (e.g.	Columns and types
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
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
set_table_bases	Set the bases a table inherits from (bases, in order; [] removes them).	Bases
add_constraint	ALTER TABLE ADD CONSTRAINT name CHECK: check is a where filter every row must match, e.g.	CHECK constraints
drop_constraint	Remove the CHECK constraint name from table.	CHECK constraints
create_view	Create (or replace) a view: a named select stored in metastore.yaml.	Views
drop_view	Remove a view from metastore.yaml (undo with undo_migration).	Views

Rows (DML)

Operations that write rows: insert, update, merge, delete, move, adopt and batch. Row operations (DML) lists their parameters.

Operation	What it does	Examples
insert_row	Insert a row (new note).	Catalogs, schemas and the database, Tables, Columns and types, Bases, Relations and hierarchies, Validation, CHECK constraints, Write and move rows, Automatic links, Batch writes, Import existing notes, Journal and undo, Table history and time travel, Change data feed, Restore a table or the database
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, Bases, Relations and hierarchies, CHECK constraints, Hand edits, Write and move rows, Automatic links, Batch writes, Journal and undo, Table history and time travel, Change data feed, Restore a table or the database
update_rows	Update every row matching where (required: {} is every row).	Write and move rows
merge_rows	MERGE (upsert) rows into table by the key columns on (e.g.	Write and move rows
delete_rows	Delete rows matching where.	Relations and hierarchies, Write and move rows, Table history and time travel
move_rows	Move rows matching where (required: {} is every row) to another table (e.g.	Write and move 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
batch	Several writes that succeed or fail together.	Views, Relations and hierarchies, CHECK constraints, Batch writes, Restore a table or the database
align_relations	Add the reciprocal links missing on a table’s inverse link columns (e.g.	Relations and hierarchies
recompute_columns	Bring generated and identity columns up to date (all rows, or only paths), e.g.	Hand edits

Queries

Operations that read rows and notes: select_rows, link targets, text and semantic search, the link graph. Query operations lists their parameters.

Operation	What it does	Examples
select_rows	Query rows: {table, total, rows: [{path, ...}]}.	Catalogs, schemas and the database, Tables, Columns and types, Views, Bases, Relations and hierarchies, Validation, CHECK constraints, Hand edits, Read and filter rows, Joins and aggregates, Write and move rows, Batch writes, Import existing notes, Journal and undo, Table history and time travel, Restore a table or the database
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
read_note	Read a note or another file of the vault: {path, content, front_matter, tags, modified_at, created_at, size}.	Relations and hierarchies, Hand edits, Import existing notes, Read and search notes
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, Tables, Columns and types, Write and move rows, Read and search notes
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
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
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
graph_traverse	Breadth-first walk over links from from_nodes ({"paths": [...]} and/or {"table", "where"}).	Walk the link graph
graph_path	Shortest chain of links between two sets of notes (each {"paths": [...]} and/or {"table", "where"}): found, length and path: the steps (from, label, direction, to).	Walk the link graph

History

Operations on the journal, a table’s versions, the change feed and webhooks: undo, time travel, restore and vacuum. History operations lists their parameters.

Operation	What it does	Examples
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, Journal and undo
undo_migration	Revert a journaled table operation by its migration_id.	Columns and types, Views, Journal and undo, Restore a table or the database
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, Restore a table or the database
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
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
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
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
list_changes	Change feed across all tables: numbered row changes (seq), oldest first, from engine writes and from hand edits (source: external).	Hand edits, Change data feed
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
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
delete_webhook	Stop and remove a webhook (by id from list_webhooks).	Change data feed

Auxiliary

Operations that describe and check the database, configure it and maintain its indexes. Auxiliary operations lists their parameters.

Operation	What it does	Examples
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, Views
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, Tables, Bases, Relations and hierarchies
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, Hand edits
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, Tables, Automatic links, Table history and time travel
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, Hand edits, Find rows that break the schema
infer_table	Read-only schema inference from notes’ front matter.	Hand edits, Import existing notes
describe_semantic_index	The semantic search index: enabled, provider, model, files, passages, pending, running, last_sync, last_error.	Find notes by meaning
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