Skip to content
Datanotes
Search
Ctrl
K
Cancel
GitHub
Menu
Get Started
Overview
Run Datanotes on Your Notes
Connect Your Agents
How It Works
Guides
Database Objects
Catalogs and Schemas
Tables
Columns and Types
Views
Bases
Relations and Hierarchies
Packs of Rows
Data Quality
Validation
CHECK Constraints
Hand Edits
check_table
Sync Between Devices
Read and Write Data
Read and Filter
Joins and Aggregates
Write and Move Rows
Automatic Links
Batch
Import Existing Notes
Search
Text Search
Hybrid Search
Semantic Search
Link Graph
History and Recovery
Journal and Undo
Table History and Time Travel
Change Data Feed
Restore
Vacuum
Back Up the History
Agents
How Agents Use Datanotes
Prompts
Reading Errors
Docs Offline
Security
Tokens and Permissions
Who Did What
Security Model
Develop
HTTP API
JavaScript Client
Concurrency
Build an App
Build on Datanotes
Change Feed and Webhooks
Logs, Traces and Telemetry
Write an Extension
Write a Recipe
Reference
Operations
Overview
Schema (DDL)
Rows (DML)
Queries
History
Auxiliary
HTTP API reference
Overview
Schema (DDL)
Overview
Create a table: `name`, in `catalog` and `schema` (default: the database's defaults); the definition
Drop a table. Refused while it has rows unless `mode: "archive"`, which removes the
Add a typed column. Sparse by default (written only on rows that have a value — use for
Rename a column in metastore.yaml and on every row. Refused if `to_column` is already a column
Remove a column from the schema and every row. Previous values are journaled; revert with
Change a column's attributes (type, min/max/step, values, required, default, label,
Alter a table: move it (`catalog`, `schema`), rename it (`name`), change
Create or replace a base: a named set of columns (same spec as `create_table`) that tables
Set the bases a table inherits from (`bases`, in order; `[]` removes them). Inherited
COMMENT ON CATALOG / SCHEMA: set the `description` of a catalog (`catalog` alone) or of one of its
Rename one value of an enum column (e.g. `high` → `very high`) in metastore.yaml and every
ALTER TABLE ADD CONSTRAINT `name` CHECK: `check` is a where filter every row must match,
Remove the CHECK constraint `name` from `table`.
Create (or `replace`) a view: a named select stored in metastore.yaml. Name it with the prefix
Remove a view from `metastore.yaml` (undo with `undo_migration`).
CREATE TABLE `target` CLONE `source`: same definition plus independent copies of its rows
Rows (DML)
Overview
Insert a row (new note). When describe_table gives the table's `instructions`, fill the row as they say. Values are validated against the columns; the note path comes from
Update every row matching `where` (required: `{}` is every row). `where`: keys AND-ed; values are equality or operators
Update exactly ONE row, addressed by its `id` (the system UUID) or its `path`; refused when
Delete rows matching `where`. `mode`: "archive" (default, move to the table's archive
Move rows matching `where` (required: `{}` is every row) to another table (e.g. split a domain out of `log` into its own
Turn existing notes (not rows of any table yet) into rows of `table`, keeping their body and
Several writes that succeed or fail together. `operations`: `[{"op": ..., ...arguments}]` where
Add the reciprocal links missing on a table's `inverse` link columns (e.g. Alice lists Carol
MERGE (upsert) `rows` into `table` by the key columns `on` (e.g. `["occurred_at"]` or
Bring generated and identity columns up to date (all rows, or only `paths`), e.g. after
Queries
Overview
Read a note or another file of the vault: `{path, content, front_matter, tags, modified_at,
The direct children of a vault folder: `{folder, folders, files}`, each a vault path, sorted;
Plain-text search: every word of `query` must occur, case- and accent-insensitive, in the
Query rows: `{table, total, rows: [{path, ...}]}`. `table` may be a view,
The rows a link column may point to, for one row: what an agent or a picker offers before writing
Find notes by meaning, not exact words: `{query, results: [{path, score, heading, snippet,
Search the notes by their words and, when semantic search is on, by their meaning:
Direct neighbours of notes: what they link to (`out`) and what links to them (`in`,
Breadth-first walk over links from `from_nodes` (`{"paths": [...]}`, `{"table", "where"}` and/or `{"tables": [...]}`).
Shortest chain of links between two sets of notes (each `{"paths": [...]}`, `{"table", "where"}`
History
Overview
Revert a journaled table operation by its `migration_id`. Refused (nothing written) when any
The operation journal, newest first: `total` (the matching operations) and `migrations`, each with
DESCRIBE HISTORY: the table's versions, newest first — `version`, `timestamp`, `operation`
Change data feed between two versions (both included, end defaults to latest): one entry
Change feed across all tables: numbered row changes (`seq`), oldest first, from engine writes
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`. Secrets are not shown.
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. Events are those of `list_changes` (hand edits with their `violations`; the hand edits the service has seen are recorded before it stops). Starts from now unless `since`. Returns the webhook with its `secret` — shown only here: give it to the receiver. Only on the user's explicit request: a webhook sends the database's changes (and, with `since`, its past ones) to that address.
Stop and remove a webhook (by `id` from list_webhooks).
RESTORE TABLE to a `version` or `timestamp`: rows and definition return to that state —
RESTORE DATABASE to a `timestamp` (each table as of its last version committed at or before it) or
Delete transaction-log history older than `retain_from_version` (default: keep only the
Auxiliary
Overview
List every table: `name`, `catalog`, `schema`, `qualified` (`personal.metrics.mood` — use it
Describe a table (`catalog.schema.table` or a shorter unambiguous name): `qualified`, `name`,
Describe the database: its folder (`root`), `metastore` (`metastore.yaml`: read it freely,
Configure the database (persisted in metastore.yaml `config:`): `root` (rename the database
Validate every row against the table (required, types, ranges, enums, links, unknown
Read-only schema inference from notes' front matter.
The semantic search index: `enabled`, `provider`, `model`, `files`, `passages`, `pending`,
Bring the semantic search index up to date: embed the notes changed since the last run (the
Put the rows of a table's closed periods into packs: one note per period (`<table> <key>.md` in the
Take rows out of their packs as notes of their own, at their paths, with the text and the modification
change feed
Overview
Record an agent's tool call in the change feed (`tool_call` events): what an MCP server reports after each call, its own tools included (`served_by`). Any token may call it.
The change feed as Server-Sent Events (id = sequence number). Resumes from Last-Event-ID or `since`.
tokens
Overview
Tell the engine the model and harness behind an agent session (what an MCP server reports): later requests carrying that session in `X-Datanotes-Actor` are journaled with it. Any token may call it.
The agent sessions that used each credential (owner only), read from the change feed: harness, model, tool calls, row changes, operations and tables, the most recent first.
List the named tokens (owner only).
Every table and view, and what each named token may read and write in it (owner only): the permission matrix, as the engine applies it.
The calling token's own entry (a named token; 400 for the owner).
Create a named token (owner only). Returns the token once.
Change a named token. A token may change its own description and autolink default; permissions (`read`, `write`, `ddl`, `maintain`) are the owner's.
Revoke a named token (owner only): it stops working at once.
Give a named token a new value (owner only): the old one stops working.
extensions
Overview
The extensions installed in the database, and its id (any token).
Record an installed extension (owner only): what datanotes extension install writes.
Forget an installed extension (owner only): what datanotes extension remove does.
service
Overview
The sections of the docs of this version closest in meaning to a query: what `search_docs` fuses with its ranking by words (hybrid search).
The engine's health at a glance (owner only; `datanotes status` prints it): engine, database, journal, git sync, change feed, webhooks, named tokens, hand edits breaking the rules in the last 24 h, logs.
The engine's settings (owner only): every key of the settings file with its value, default, whether it applies at once or after a restart; secrets are never sent.
Change the engine's settings (owner only): checked with the rules the engine loads the settings file with, saved, and journaled as set_engine_settings.
Stop the engine gracefully (owner only; `datanotes stop` calls it): it answers at once, then finishes the requests under way, makes the last git sync and store backup commit and push, releases its lock and exits.
Restart the engine in its own process (owner only): it applies the settings waiting for a restart and the settings file's edits. With dry_run, it says what a restart would do and whether it can.
This document (as `GET /datanotes/openapi.json`, with a token).
Status and version (no token needed; `authenticated` tells whether the token sent is accepted, `auth` whose it is).
This document (public: it describes the API, it holds no data).
This document in an interactive console (Swagger UI, served by the engine; public). Authorize with a token to try the routes.
The database browser: a web page that browses and administers the database, served by the engine (public; its calls need a token).
The index of the docs of this version (every page of datanotes.dev as Markdown, shipped with the package): each page with its description and route.
A page of the docs of this version as Markdown, or one of its sections with `section`, the anchor of its heading. The same text as the page with `.md` on datanotes.dev, offline.
CLI
Settings
Errors
Compatibility
Glossary
Administration
Run the Service
Run in Docker
Git Sync
Datanotes Status
Configuration
Use with Obsidian
Limits
Extensions
Database Browser
Release Notes
GitHub
Overview
extensions
Section titled “extensions”
The extensions installed in the database: their versions, tables, tools and tokens.
Operations
Section titled “Operations”
POST
/datanotes/extensions/
POST
/datanotes/extensions/record/
POST
/datanotes/extensions/delete/