Struct Engine 

pub struct Engine { /* private fields */ }

Implementations

impl Engine

pub fn execute_plan( &mut self, plan: &PlanNode, ) -> Result<QueryResult, QueryError>

impl Engine

pub fn prepare(&mut self, query: &str) -> Result<PreparedQuery, QueryError>

pub fn execute_prepared( &mut self, prep: &PreparedQuery, literals: &[Literal], ) -> Result<QueryResult, QueryError>

Execute a PreparedQuery with the given literal values.

The literals are substituted into a clone of the template plan in the same deterministic walk order that crate::canonicalize produces (filter predicate first, then projection, then assignment RHS, and so on). Substitution errors here mean the caller passed the wrong number of literals for this query shape.

pub fn execute_prepared_take( &mut self, prep: &PreparedQuery, literals: &mut [Literal], ) -> Result<QueryResult, QueryError>

Mission C Phase 13: moving variant of Engine::execute_prepared for the insert fast path. Takes literals by mutable reference so that each Literal::String can be consumed via mem::take instead of cloned into a Value::Str. On insert_batch_1k that removes three per-row heap allocations (name, status, email), bringing the workload over the line vs SQLite’s amortized prepare+execute loop.

The caller’s Literal::String entries are replaced with empty strings on successful inserts — the literals slice is not left in a valid-for-reuse state except for Int/Float/Bool values. Non-insert templates fall through to the standard substitute-and-execute path.

impl Engine

pub fn new(data_dir: &Path) -> Result<Self>

Open or create a PowDB engine rooted at data_dir.

If the directory already contains a catalog, it is reopened. Otherwise a fresh empty database is created.

Examples

use powdb_query::executor::Engine;

let dir = tempfile::tempdir().unwrap();
let engine = Engine::new(dir.path()).unwrap();
// Engine is ready — the directory now contains a catalog.

pub fn with_memory_limit(data_dir: &Path, limit_bytes: usize) -> Result<Self>

Open or create an engine with an explicit per-query memory limit (bytes). Used by the server to apply POWDB_QUERY_MEMORY_LIMIT, and by tests that need a tiny limit to exercise the budget guard.

pub fn query_memory_limit(&self) -> usize

Current per-query memory limit in bytes.

pub fn set_query_memory_limit(&mut self, limit_bytes: usize)

Override the per-query memory limit in bytes (builder-style).

pub fn execute_with_dialect( &mut self, dialect: QueryDialect, input: &str, ) -> Result<QueryResult, QueryError>

Dispatch to the requested query frontend.

pub fn execute_readonly_with_dialect( &self, dialect: QueryDialect, input: &str, ) -> Result<QueryResult, QueryError>

Read-only variant of Engine::execute_with_dialect.

pub fn execute_powql(&mut self, input: &str) -> Result<QueryResult, QueryError>

Parse + plan + execute a PowQL query.

Examples

use powdb_query::executor::Engine;
use powdb_query::result::QueryResult;

let dir = tempfile::tempdir().unwrap();
let mut engine = Engine::new(dir.path()).unwrap();

// Create a table and insert a row.
engine.execute_powql("type User { required name: str, age: int }").unwrap();
engine.execute_powql(r#"insert User { name := "Alice", age := 30 }"#).unwrap();

// Query rows back.
let result = engine.execute_powql("User").unwrap();
assert_eq!(result.row_count(), 1);

Mission D6 — tracing collapse: the previous implementation ran 4 Instant::now() + 3 elapsed().as_micros() calls + formatted an info! span on every query, even when tracing was disabled. On a sub-microsecond point_lookup_indexed call that overhead was 100-200ns — 20%+ of the whole query. We now measure time only when INFO is actually enabled via tracing::enabled!, and we moved the noisy debug!(?plan) line behind the same gate so the Debug formatter can’t run unconditionally either.

Mission D9 — plan cache: on the hot path we canonicalise the query text (lex + FNV-1a hash with literal values stripped), check the cache, and on a hit substitute the new literals into a clone of the cached plan. This skips re-lexing, re-parsing, and re-planning — around 3μs per call on bench workloads. On a miss we plan as before and insert the plan under its canonical hash.

pub fn execute_sql(&mut self, input: &str) -> Result<QueryResult, QueryError>

Parse + plan + execute a SQL query through the SQL frontend.

SQL is lowered to the existing PowDB AST and to canonical PowQL text. The canonical PowQL text is used as the plan-cache key, so equivalent SQL and PowQL spellings share cached plans.

pub fn execute_sql_readonly( &self, input: &str, ) -> Result<QueryResult, QueryError>

Read-only variant of Engine::execute_sql.

pub fn execute_powql_with_params( &mut self, input: &str, params: &[ParamValue], ) -> Result<QueryResult, QueryError>

Execute PowQL with $N placeholders bound to positional params.

Task 4: parameters are substituted as literal tokens before parsing (see crate::parser::parse_with_params), so untrusted input can never change the query’s shape. This path deliberately bypasses the plan cache — template caching is a follow-up — and otherwise mirrors the non-cached tail of Engine::execute_powql.

pub fn execute_powql_readonly_with_params( &self, input: &str, params: &[ParamValue], ) -> Result<QueryResult, QueryError>

Read-only variant of Engine::execute_powql_with_params.

Mirrors Engine::execute_powql_readonly: parses with bound params, rejects any write statement with QueryError::ReadonlyNeedsWrite so the caller can escalate to the write lock, then executes under a shared borrow. No plan-cache interaction.

pub fn plan_cache_stats(&self) -> (u64, u64, usize)

Plan cache stats — useful for benches and debugging.

pub fn execute_powql_readonly( &self, input: &str, ) -> Result<QueryResult, QueryError>

Mission infra-1: read-only entry point.

Parses + plans + executes a PowQL query using only a shared borrow on the engine. Rejects any statement that would mutate state (Insert/Update/Delete/CreateTable/AlterTable/DropTable/CreateView/ RefreshView/DropView) by returning READONLY_NEEDS_WRITE so the caller can escalate to the write lock.

Also returns READONLY_NEEDS_WRITE if a materialized view in the query is dirty — refreshing one requires &mut self, so the caller must retake the write lock for the first refresh.

This method is the concurrent-read fast path behind Arc<RwLock<Engine>>: multiple threads can call it simultaneously under a shared .read() lock and each will scan independently.

pub fn catalog(&self) -> &Catalog

pub fn catalog_mut(&mut self) -> &mut Catalog