Glossary
The words these docs use, in alphabetical order. Each one links to the page that explains it.
Who made a write: the credential as auth (owner or a token’s name), and, when the caller sends them, the harness, model, session and tool. The journal, the history and the change feed record it. See Who did what.
A program driven by a language model, such as Claude, Cursor or Codex, that calls the engine’s operations as tools through the MCP server. See How agents work with your vault.
A program that calls the HTTP API with its own named token, such as a script, a service or an MCP server of your own. Each app has its own named token. See Build on Datanotes.
Automatic link
Section titled “Automatic link”A link the engine adds where the text of a write mentions another note by name. A doubtful mention stays as text, and the write returns it in ambiguous_mentions with the notes it may name. The autolink setting turns it off. See Automatic links.
A named set of columns that tables inherit, like a parent class. One query reads every table that extends a base. See Bases.
Backlinks
Section titled “Backlinks”The notes that link to a given note. file_backlink_count counts them, and the graph operations follow them with the direction in. See Read and filter rows.
A list of writes that succeed or fail together, as one journal entry that one undo reverts. See Batch writes.
Catalog
Section titled “Catalog”The top level of the database’s hierarchy: a catalog holds schemas, and a schema holds tables. A table’s full name is catalog.schema.table. See Catalogs, schemas and the database.
Change feed
Section titled “Change feed”The numbered list of every change in the vault, writes and hand edits alike, that programs poll, stream or receive by webhook. Also called the change data feed. See Change data feed.
CHECK constraint
Section titled “CHECK constraint”A rule, written as a filter, that every row of a table must pass. It can follow links into other tables. See CHECK constraints.
Column
Section titled “Column”A typed front matter key of a table’s rows. Its type can be a string, a number, a date, an enum or a link, and it has attributes such as required, unique and default. See Columns and types.
Data home
Section titled “Data home”The folder that holds the engine’s stores, one per database: %LOCALAPPDATA%\Datanotes on Windows, ~/Library/Application Support/Datanotes on macOS and ~/.local/share/datanotes on Linux. DATANOTES_DATA_HOME moves it. See Run the engine as a service.
Database folder
Section titled “Database folder”The folder that holds metastore.yaml. With --database, it’s the folder you pass, and metastore.yaml sits at its root. With --vault, it’s a folder inside the vault, datanotes/ by default: the engine finds it at each start, and configure_database with root moves it. See One database per vault.
Database id
Section titled “Database id”A UUID at the top of metastore.yaml, as id, that names the database. The engine writes it when it creates the database, and finds the database’s store by it. A copy of a vault gets its own with datanotes store new-id. See Run a copy of a vault.
Engine
Section titled “Engine”The process that runs a vault as a database, datanotes serve. It checks and journals every write and serves the HTTP API. See Run the engine as a service.
Front matter
Section titled “Front matter”The YAML block at the top of a note, between two --- lines. Each key of a row’s front matter holds the value of one column. See How it works.
Hand edit
Section titled “Hand edit”A change to a note made outside the engine: in an editor, with git or through a sync tool. The engine checks it against the tables’ rules but never refuses it. See Hand edits.
History
Section titled “History”A table’s transaction log, when it’s turned on: every version of the table, for time travel and restores. See Table history and time travel.
Hybrid search
Section titled “Hybrid search”A search that ranks by words and by meaning, then merges the two rankings with Reciprocal Rank Fusion. search_docs works this way when the engine has semantic search on. See Search by words and by meaning.
Journal
Section titled “Journal”The record of every write to rows and to the schema, with the data to undo it and its actor, in journal/ in the engine’s store. See Journal and undo.
The Model Context Protocol, the way agents call tools. datanotes mcp, the MCP server of Datanotes, offers the operations of the engine as tools, the webhook tools only on request. See Connect your agents.
Metastore
Section titled “Metastore”The file that defines every catalog, schema, table, column, base and view: metastore.yaml, at the root of the database folder. It changes only through operations. See How it works.
Migration
Section titled “Migration”One journal entry: a write, with its migration_id. list_migrations lists them, and undo_migration reverts one. See Journal and undo.
Module
Section titled “Module”A JavaScript entry point of the datanotes package: datanotes/client calls the HTTP API, datanotes/local finds the local engine, and datanotes/mcp gives the engine’s tools to an MCP server of your own. See Call the engine from JavaScript.
A Markdown file in the vault. A note with a front matter key table that names a table is a row; any other note is an ordinary note. See How it works.
Operation
Section titled “Operation”A call the engine runs, such as create_table, insert_row or select_rows. Each one is an HTTP route and an MCP tool of the same name. See Operations.
Owner token
Section titled “Owner token”The token that can do everything, generated at the engine’s first start and kept in its settings file. See Tokens and permissions.
A note whose front matter key table names a table, wherever it lives in the vault. Its front matter keys are the row’s columns. Each row has an id that never changes. See Tables.
Schema
Section titled “Schema”The level between catalogs and tables: a schema holds tables and views. See Catalogs, schemas and the database.
The engine’s folder for one database, outside the vault: <data home>/<database id>/. It holds the settings, the tokens, the journal, the transaction logs, the change feed and the logs. Results name its files with a store: prefix. See Run the engine as a service.
Store backup
Section titled “Store backup”The store kept as a git repository of its own and pushed to a private remote, such as a GitHub repository. It keeps the journal, the transaction logs, the change feed and the named tokens’ hashes, never the settings or a secret. Every 60 seconds by default, when the store changed, it commits between two operations, then pushes. datanotes store restore brings it back on a new machine. See Back up the history.
A set of rows with the same columns, defined in the metastore. See Tables.
A credential for the HTTP API, sent as Authorization: Bearer. The owner token can do everything; a named token has only the permissions you give it. See Tokens and permissions.
Transaction log
Section titled “Transaction log”The numbered versions of a table with history on, in transaction_log/ in the engine’s store. See How it works.
The folder of notes the engine serves. Note editors such as Obsidian, Foam or Zettlr work on a folder like this one too. A vault is optional: with --database, the database folder is the folder the engine serves. With --vault, the engine serves a whole vault, and the database is a folder inside it. Either way, rows and ordinary notes link to each other, and the engine serves every note. Paths are relative to the folder the engine serves, and the engine never writes outside it. Not every note is a row. See How it works.
Version
Section titled “Version”One numbered state of a table in its transaction log. select_rows reads a table at a version or a time. See Table history and time travel.
A query stored under a name in the metastore, read like a table. See Views.
Webhook
Section titled “Webhook”A web address the engine posts the change feed to. See Follow the change feed and webhooks.
Wikilink
Section titled “Wikilink”A link between notes written [[Note]], or [[Note|alias]] with an alias as the text it shows. A link column holds wikilinks to rows of its ref table. See Relations and hierarchies.