Struct RelationalDb 

pub struct RelationalDb<B>
where
    B: StorageBackend,
{ /* private fields */ }

Relational (row/column) facade layered on top of a raw StorageBackend, sharing the same backend instance a crate::graph::GraphDb can use — that shared Arc<B> is what makes the two layers “hybrid” rather than two unrelated databases.

Implementations

impl<B> RelationalDb<B>

where B: StorageBackend,

pub fn new(backend: B) -> RelationalDb<B>

pub fn from_arc(backend: Arc<B>) -> RelationalDb<B>

pub fn table(&self, schema: impl Into<TableSchema>) -> RelTable<'_, B>

A handle on the table described by schema (a &RelSchema static or a TableSchema); the table doesn’t have to be registered in the catalog.

Panics if the name collides with one of bkndb-core’s reserved internal table names (see crate::RESERVED_TABLE_NAMES) — a schema-authoring bug caught at first use, not a recoverable runtime condition. (A TableSchema built with its builder can never have a reserved name.)

pub fn table_named(&self, name: &str) -> Result<RelTable<'_, B>, BknError>

A handle on a table registered in the catalog, by name. The handle always uses the table’s current definition, so it stays valid across migrations.

pub fn create_table( &self, schema: impl Into<TableSchema>, ) -> Result<bool, BknError>

Registers a new table. Returns false if an identical definition was already registered; errors if a different one is (see RelationalDb::ensure_table for migrating).

pub fn ensure_table( &self, schema: impl Into<TableSchema>, ) -> Result<(), BknError>

Creates the table if needed, or migrates the registered one to match schema: added/removed columns (defaults are backfilled into existing rows), changed NOT NULL / UNIQUE constraints (validated against existing rows), and added/removed indexes (new ones are backfilled). The primary key and existing columns’ kinds can’t change. Atomic.

Also the way to adopt a table previously used only through a static RelSchema: its indexes are rebuilt from the existing rows.

pub fn drop_table(&self, name: &str) -> Result<bool, BknError>

Deletes a registered table with all its rows and indexes. Returns false if no such table is registered.

pub fn create_index(&self, table: &str, column: &str) -> Result<(), BknError>

Adds a (backfilled) secondary index to a registered table.

pub fn drop_index(&self, table: &str, column: &str) -> Result<(), BknError>

Removes a secondary index (and any UNIQUE constraint relying on it).

pub fn table_schema(&self, name: &str) -> Result<Option<TableSchema>, BknError>

pub fn sql( &self, sql: &str, params: impl Into<Params>, ) -> Result<QueryResult, BknError>

Runs one SQL statement (see crate::lang::sql for the supported subset): a query in a read snapshot, anything else in its own atomic write transaction.

db.sql("SELECT name FROM users WHERE age >= ? ORDER BY name", vec![18.into()])?;

pub fn list_tables(&self) -> Result<Vec<TableSchema>, BknError>

Every table registered in the catalog, sorted by name.

pub fn write_tx<F, R>(&self, f: F) -> Result<R, BknError>

where F: for<'w> FnOnce(&mut RelWriteBatch<<B as StorageBackend>::WriteTx<'w>>) -> Result<R, BknError>,

Runs f against one shared write transaction spanning however many tables it touches (via crate::relational::txn::RelWriteBatch::table), committing only if f returns Ok. An Err return leaves the write tx uncommitted and it is simply dropped — every StorageWriteTx backend buffers writes until commit(), so a dropped, uncommitted tx is already a no-op rollback with no extra bookkeeping needed here.

impl<B> RelationalDb<B>

where B: StorageBackend,

pub fn create_fulltext_index( &self, table: &str, column: &str, ) -> Result<bool, BknError>

Builds a full-text index over a Str column of a registered table (backfilling existing rows). Returns false if it already exists.

pub fn drop_fulltext_index( &self, table: &str, column: &str, ) -> Result<bool, BknError>

Removes a full-text index; false if there was none.

pub fn fulltext_indexes(&self, table: &str) -> Result<Vec<String>, BknError>

Columns of table with a full-text index.

pub fn search_text( &self, table: &str, column: &str, query: &str, limit: usize, match_all: bool, filter: Option<&Expr>, ) -> Result<Vec<ScoredRow>, BknError>

Up to limit rows whose column best matches query (BM25). See the module docs.

pub fn search_vector( &self, table: &str, column: &str, query: &[f32], limit: usize, metric: VectorMetric, filter: Option<&Expr>, ) -> Result<Vec<ScoredRow>, BknError>

The limit rows whose embedding in column is nearest to query, from the column’s vector index when it has one for metric (approximate), else by scanning (exact). See the module docs.

pub fn search_vector_with( &self, table: &str, column: &str, query: &[f32], limit: usize, metric: VectorMetric, filter: Option<&Expr>, options: VectorSearchOptions, ) -> Result<Vec<ScoredRow>, BknError>

Self::search_vector with per-query options: force an exact scan, or trade speed for recall with ef_search.

pub fn create_vector_index( &self, table: &str, column: &str, options: VectorIndexOptions, ) -> Result<bool, BknError>

Builds an approximate (HNSW) vector index over a List/Bytes embedding column for options.metric, backfilling existing rows. Returns false if the column already has one (drop it first to change the parameters). Once it exists, every indexed vector must have the same number of dimensions. See crate::relational::ann.

pub fn drop_vector_index( &self, table: &str, column: &str, ) -> Result<bool, BknError>

Removes a vector index; false if there was none.

pub fn vector_indexes( &self, table: &str, ) -> Result<Vec<VectorIndexInfo>, BknError>

The vector indexes of table.