Crate vaultdb_core 

vaultdb-core

A markdown-as-database engine. Treats folders of .md files with YAML frontmatter as queryable structured data, with [[wikilinks]] forming a first-class link graph. Both the tabular (frontmatter) and graph (link) shapes are equally first-class — you can filter records by frontmatter, by graph predicates (“links to anything tagged X”), or by any combination.

Quick start

use vaultdb_core::{Expr, Predicate, Query, Value, Vault};

let vault = Vault::discover(std::path::Path::new(".")).unwrap();
let q = Query {
    folder: "notes".into(),
    filter: Some(Expr::Predicate(Predicate::Equals {
        field: "status".into(),
        value: Value::String("active".into()),
    })),
    select: None,
    sort: None,
    limit: Some(10),
    recursive: false,
};
let records = vault.query(&q).unwrap();

Public API surface

• Vault: entry point. Discover, load, query, build the link graph.
• Record and Value: the row + cell types.
• Expr, Predicate, LinkPredicate, Query: the query AST.
• LinkGraph, GraphScope, Direction, UnresolvedLink: the link graph and its traversal/scoping types.
• UpdateBuilder, DeleteBuilder, MoveBuilder, RenameBuilder: typed mutation API. Each has UpdateBuilder::plan-style preview and execute commit methods.
• render: serialize query results to CSV / JSON / YAML / XLSX and write them to a vault-scoped path. The CLI’s --output flag and the MCP read tools’ export parameter both use this. XLSX is behind the xlsx Cargo feature.
• LoadResult, ParseError: parse-diagnostic surfacing for Vault::load_records.
• VaultdbError, Result: error types.

Design philosophy

No daemon, no cache, no state files. Every read traverses the filesystem fresh. Stateful concerns (file watchers, full-text indexes, typed schemas) belong in consumers, not in vaultdb-core.

Re-exports

pub use error::ParseError;

pub use error::Result;

pub use error::VaultdbError;

pub use links::Direction;

pub use links::GraphScope;

pub use links::LinkGraph;

pub use links::UnresolvedLink;

pub use mutation::CreateBuilder;

pub use mutation::DeleteBuilder;

pub use mutation::MoveBuilder;

pub use mutation::MutationError;

pub use mutation::MutationReport;

pub use mutation::PlannedChange;

pub use mutation::RenameBuilder;

pub use mutation::UpdateBuilder;

pub use query::CompareOp;

pub use query::Expr;

pub use query::LinkPredicate;

pub use query::Predicate;

pub use query::Query;

pub use query::SortKey;

pub use record::Record;

pub use record::Value;

pub use render::Format as ExportFormat;

pub use render::export_records;

pub use render::export_value;

pub use render::resolve_export_path;

pub use vault::LoadResult;

pub use vault::QueryIter;

pub use vault::Vault;

pub use writer::WriteOptions;

Modules

dsl

Parser for the where-DSL — the human-readable filter syntax used by Expr::parse, the CLI’s --where flag, and vaultdb-mcp’s tool parameters. The grammar lives at src/where_dsl.pest; this module drives pest and lowers the resulting parse tree into the public crate::query::Expr AST.

error

Error types: VaultdbError for fatal failures, ParseError for non-fatal per-file diagnostics returned by crate::LoadResult.

filter

Evaluator for the public crate::query::Expr AST.

frontmatter

YAML frontmatter parsing. Internal — the public surface is crate::Vault::load_records / crate::Vault::find_by_name.

journal

Crash-recovery journal for crate::RenameBuilder::execute.

links

LinkGraph (the citation graph from a vault’s [[wikilinks]]) plus the traversal types: Direction, GraphScope, UnresolvedLink. Supports outgoing/incoming queries, BFS traversal, and unresolved-link discovery.

lock

Vault-scoped exclusive lock used to serialize mutations across processes.

mutation

Public typed mutation API for vault edits.

query

Public AST types for vault queries.

record

Record (one parsed .md file) and Value (the typed cell values). Records have virtual fields (_name, _path, _modified, etc.) computed lazily from the path and frontmatter.

render

Export rendering: serialize query results into CSV, JSON, YAML, or XLSX and atomically write them to a vault-scoped path.

schema

Schema inference and validation. infer_schema walks records to discover field types and cardinalities; validate_record checks a record against a schema; schema_to_yaml renders a schema to YAML for persistence.

vault

Vault: the library entry point. Discovers a vault from .obsidian/, lists files, loads records, runs structured queries, builds the link graph. Also defines LoadResult, the parse-diagnostic-bearing return type from Vault::load_records.

writer

Frontmatter write primitives. set_field, unset_field, add_tag, remove_tag each return (new_content, ChangeDescription) without touching disk; apply flushes a WriteResult to the filesystem. The public mutation builders in crate::mutation wrap these.