Struct Vault 

pub struct Vault {
    pub root: PathBuf,
}

Represents a discovered Obsidian vault.

Fields

root: PathBuf

Implementations

impl Vault

pub fn discover(start: &Path) -> Result<Self>

Discover vault root by walking up from start looking for .obsidian/.

pub fn with_root(root: PathBuf) -> Self

Create a Vault with an explicit root path (skips discovery).

pub fn recover(&self) -> Result<usize>

Replay any pending journals from previously-crashed mutations.

Currently the only mutation that writes a journal is crate::RenameBuilder::execute — a rename that crashed between the file rename and finishing every backlink rewrite leaves a journal at <vault>/.vaultdb/rename-journal/. This method replays each pending journal idempotently and returns the count of journals processed.

Long-lived consumers (eduport-tauri, etc.) should call this at startup. Each mutation also runs replay implicitly under the vault lock, so the only behavioural difference is timing: explicit recovery surfaces leftover work earlier.

pub fn resolve_folder(&self, folder: &str) -> Result<PathBuf>

Resolve a folder argument (relative to vault root) to an absolute path.

pub fn list_files(&self, folder: &Path, recursive: bool) -> Result<Vec<PathBuf>>

List all .md files in a folder. If recursive, walks subdirectories.

pub fn load_records( &self, folder: &Path, recursive: bool, verbose: bool, ) -> Result<LoadResult>

Load records from a folder, collecting per-file parse diagnostics.

Files with no frontmatter are loaded as empty records (queryable via virtual fields). Files with invalid frontmatter are collected into LoadResult.parse_errors rather than dropped.

verbose is preserved for compatibility with the CLI’s -v flag — it causes parse errors to also be logged to stderr as they’re encountered. Library consumers that don’t want stderr logging should pass false and inspect parse_errors themselves.

pub fn load_records_with_content( &self, folder: &Path, recursive: bool, verbose: bool, ) -> Result<LoadResult>

Load records with raw content preserved (for write operations and link extraction), collecting per-file parse diagnostics.

Files with no frontmatter are loaded as empty records with their raw content set. Files with invalid frontmatter are collected into LoadResult.parse_errors rather than dropped.

pub fn find_by_name(&self, folder: &str, name: &str) -> Result<Option<Record>>

Look up a single record by its filename (without the .md extension) inside the given folder.

Returns Ok(None) if no such file exists. Returns Ok(Some(record)) when the file exists and parses cleanly. Returns Err(VaultdbError::InvalidFrontmatter) if the file exists but its frontmatter is malformed — unlike load_records, single-record lookup surfaces parse errors as a hard error because the caller asked for one specific record.

pub fn link_graph(&self, scope: GraphScope) -> Result<LinkGraph>

Build a link graph over the given scope.

GraphScope::All walks the whole vault recursively. Folder(name) scopes to one folder. Where(expr) first walks the whole vault, builds a temporary graph for predicate evaluation (so link predicates work), filters records, and rebuilds the graph from the filtered subset.

Records are loaded with raw content so wikilinks can be extracted.

pub fn query(&self, q: &Query) -> Result<Vec<Record>>

Run a structured query against the vault. Returns the matching records, optionally projected, sorted, and limited per the Query’s fields.

The records returned have raw_content set to None (use load_records_with_content if you need the body text).

Eager: loads, filters, sorts, limits, and projects all in memory. Use Vault::query_iter for the streaming variant when memory pressure matters (large vaults; bounded top-K with sort+limit).

pub fn query_iter(&self, q: &Query) -> Result<QueryIter>

Streaming variant of Vault::query.

Returns an iterator yielding Result<Record>. The implementation chooses the most memory-efficient strategy compatible with the query:

• No sort, no graph predicate, no body-search: pure file-by- file streaming. Records are loaded one at a time and filtered inline; resident memory is O(1) regardless of vault size.
• Sort + limit: bounded top-K via a binary heap of size limit. Memory is O(limit), so “give me the most-recent 50 records out of 100K” is cheap.
• Sort, no limit; or graph/body predicates: materializes the working set in memory the same way Vault::query does, then streams from the buffer. Memory is O(N) — same as the eager call. (We can’t stream a sort without materializing, and graph predicates need the link graph built from all records.)

The iterator yields Err(...) on per-file IO failures rather than aborting the whole query; the caller decides whether to stop or continue.