Struct StandardEngine 

pub struct StandardEngine(/* private fields */);

Implementations

impl StandardEngine

pub fn begin_command(&self, identity: IdentityId) -> Result<CommandTransaction>

pub fn begin_admin(&self, identity: IdentityId) -> Result<AdminTransaction>

pub fn begin_query(&self, identity: IdentityId) -> Result<QueryTransaction>

pub fn clock(&self) -> &Clock

Get the runtime clock for timestamp operations.

pub fn rng(&self) -> &Rng

pub fn admin_as( &self, identity: IdentityId, rql: &str, params: Params, ) -> ExecutionResult

pub fn command_as( &self, identity: IdentityId, rql: &str, params: Params, ) -> ExecutionResult

pub fn query_as( &self, identity: IdentityId, rql: &str, params: Params, ) -> ExecutionResult

pub fn subscribe_as( &self, identity: IdentityId, rql: &str, params: Params, ) -> ExecutionResult

pub fn procedure_as( &self, identity: IdentityId, name: &str, params: Params, ) -> ExecutionResult

Call a procedure by fully-qualified name.

pub fn register_virtual_table<T: UserVTable>( &self, namespace: &str, name: &str, table: T, ) -> Result<VTableId>

Register a user-defined virtual table.

The virtual table will be available for queries using the given namespace and name.

Arguments

• namespace - The namespace name (e.g., “default”, “my_namespace”)
• name - The table name
• table - The virtual table implementation

Returns

The assigned VTableId on success.

Example

use reifydb_engine::vtable::{UserVTable, UserVTableColumn};
use reifydb_type::value::r#type::Type;
use reifydb_core::value::Columns;

#[derive(Clone)]
struct MyTable;

impl UserVTable for MyTable {
    fn definition(&self) -> Vec<UserVTableColumn> {
        vec![UserVTableColumn::new("id", Type::Uint8)]
    }
    fn get(&self) -> Columns {
        // Return column-oriented data
        Columns::empty()
    }
}

let id = engine.register_virtual_table("default", "my_table", MyTable)?;

impl StandardEngine

pub fn new( multi: MultiTransaction, single: SingleTransaction, event_bus: EventBus, interceptors: InterceptorFactory, catalog: Catalog, config: EngineConfig, ) -> Self

pub fn create_interceptors(&self) -> Interceptors

Create a new set of interceptors from the factory.

pub fn add_interceptor_factory( &self, factory: Arc<dyn Fn(&mut Interceptors) + Send + Sync>, )

Register an additional interceptor factory function.

The function will be called on every create() to augment the base interceptors. This is thread-safe and can be called after the engine is constructed (e.g. by subsystems).

pub fn begin_query_at_version( &self, version: CommitVersion, identity: IdentityId, ) -> Result<QueryTransaction>

Begin a query transaction at a specific version.

This is used for parallel query execution where multiple tasks need to read from the same snapshot (same CommitVersion) for consistency.

pub fn multi(&self) -> &MultiTransaction

pub fn multi_owned(&self) -> MultiTransaction

pub fn actor_system(&self) -> ActorSystem

Get the actor system

pub fn single(&self) -> &SingleTransaction

pub fn single_owned(&self) -> SingleTransaction

pub fn emit<E: Event>(&self, event: E)

pub fn materialized_catalog(&self) -> &MaterializedCatalog

pub fn catalog(&self) -> Catalog

Returns a Catalog instance for catalog lookups. The Catalog provides three-tier lookup methods that check transactional changes, then MaterializedCatalog, then fall back to storage.

pub fn services(&self) -> Arc<Services>

Returns the shared Services instance used by this engine’s executor. External consumers that want to drive volcano operators directly (e.g. subsystems that build a QueryContext) read from the same Services the engine already initialised - avoids duplicating the Services::new wiring path.

pub fn flow_operator_store(&self) -> &SystemFlowOperatorStore

pub fn current_version(&self) -> Result<CommitVersion>

Get the current version from the transaction manager

pub fn done_until(&self) -> CommitVersion

Returns the highest version where ALL prior versions have completed. This is useful for CDC polling to know the safe upper bound for fetching CDC events - all events up to this version are guaranteed to be in storage.

pub fn wait_for_mark_timeout( &self, version: CommitVersion, timeout: Duration, ) -> bool

Wait for the watermark to reach the given version with a timeout. Returns true if the watermark reached the target, false if timeout occurred.

pub fn executor(&self) -> Executor

pub fn ioc(&self) -> &IocContainer

Borrow the IoC container backing this engine. Used by callers that need to resolve services registered during construction (e.g. observability providers).

pub fn cdc_store(&self) -> CdcStore

Get the CDC store from the IoC container.

Returns the CdcStore that was registered during engine construction. Panics if CdcStore was not registered.

pub fn actor<M: 'static>(&self) -> Option<ActorRef<M>>

where ActorRef<M>: Send + Sync,

Resolve an actor handle by message type.

Returns None if no actor for M was registered during engine construction (e.g. the CDC compact actor is only registered for persistent backends).

pub fn cdc_producer_watermark(&self) -> CommitVersion

Highest commit version processed by the CDC producer actor.

Once this returns >= V, every PostCommitEvent for versions <= V has been fully handled by the producer, so any CDC row it was going to write is in storage. Unlike cdc_store().max_version(), this advances even for commits whose deltas were entirely filtered out by should_exclude_from_cdc (e.g. ConfigStorage-only commits), so it is the correct frontier for “producer is caught up to the engine”.

pub fn set_read_only(&self)

Mark this engine as read-only (replica mode). Once set, all write-path methods will return ENG_007 immediately.

pub fn is_read_only(&self) -> bool

Whether this engine is in read-only (replica) mode.

pub fn shutdown(&self)

pub fn bulk_insert<'e>( &'e self, identity: IdentityId, ) -> BulkInsertBuilder<'e, Validated>

Start a bulk insert operation with full validation.

This provides a fluent API for fast bulk inserts that bypasses RQL parsing. All inserts within a single builder execute in one transaction.

Example

use reifydb_type::params;

engine.bulk_insert(&identity)
    .table("namespace.users")
        .row(params!{ id: 1, name: "Alice" })
        .row(params!{ id: 2, name: "Bob" })
        .done()
    .execute()?;

pub fn bulk_insert_unchecked<'e>( &'e self, identity: IdentityId, ) -> BulkInsertBuilder<'e, Unchecked>

Start a bulk insert that bypasses BOTH constraint validation AND the oracle’s per-key conflict-detection index (“unchecked” mode).

What this skips beyond bulk_insert

bulk_insert (the validated default) performs full type/constraint validation and registers the commit’s write set in the oracle’s conflict-detection time-windows so that any concurrent OCC transaction whose read set overlaps these writes will be aborted at its own commit time.

bulk_insert_unchecked skips both. The commit version still advances and the watermark still progresses, so any transaction that reads at version >= this commit will observe the new rows. But concurrent OCC transactions that already started reading at an older version will NOT detect that this commit happened underneath them.

Safety contract - when this is sound

Use this method ONLY when ALL of the following hold for the calling context:

1. Single writer. This commit is the only writer touching the rows it inserts. No other thread / process / connection is writing to the same keys concurrently. (For chain ingest: the block-stream consumer is the only writer, and blocks arrive in monotonic order.)

2. No concurrent OCC reader needs to be invalidated. Any OCC transaction reading at an older version will silently miss this commit’s writes when computing its own conflict set. If your workload has concurrent user transactions that read these rows, they will commit successfully despite a logical conflict, and they will see stale data on retry. For trusted ingest where “downstream” readers are streaming-view operators that consume each new commit on its own merits (not via OCC retry), this is fine.

3. Caller-side well-formedness. Validation is skipped, so primary key violations or constraint failures will surface as storage errors at insert time rather than as transaction-level conflicts. The caller must already ensure the data conforms to the table/ringbuffer shape.

4. No need to abort on overlap. OCC normally aborts a writer whose read set was modified by a more recent committer. Skipping the index means a concurrent OCC writer with an overlapping read set will commit through. For trusted ingest where there is no competing OCC writer, this is irrelevant.

In short: safe for sequential, single-writer, append-mostly trusted ingest where downstream readers don’t rely on OCC abort-on-overlap. Unsafe (silently incorrect) for any workload with concurrent OCC transactions that read these keys and rely on conflict detection for correctness.

Trait Implementations

impl AuthEngine for StandardEngine

fn begin_admin(&self) -> Result<AdminTransaction>

fn begin_query(&self) -> Result<QueryTransaction>

fn catalog(&self) -> Catalog

impl CdcHost for StandardEngine

fn begin_command(&self) -> Result<CommandTransaction>

Begin a new command transaction.

fn begin_query(&self) -> Result<QueryTransaction>

Begin a new read-only query transaction.

fn current_version(&self) -> Result<CommitVersion>

Get the current committed version.

fn done_until(&self) -> CommitVersion

Get the version up to which all transactions are complete.

fn wait_for_mark_timeout( &self, version: CommitVersion, timeout: Duration, ) -> bool

Wait for the watermark to reach the specified version. Returns true if the version was reached, false if timeout.

fn materialized_catalog(&self) -> &MaterializedCatalog

Get the materialized catalog for fingerprint-based shape lookup.

impl Clone for StandardEngine

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Deref for StandardEngine

type Target = Inner

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl WithEventBus for StandardEngine

fn event_bus(&self) -> &EventBus