Struct OxideSession 

pub struct OxideSession { /* private fields */ }

An OxideLake session.

Implementations

impl OxideSession

pub fn local() -> Result<OxideSession, EngineError>

Creates an embedded session: Parquet pruning on, the local object store registered, the SQL UDFs, and the placement rule targeting the detected backend.

pub fn local_with_target( target: BackendKind, ) -> Result<OxideSession, EngineError>

An embedded session whose placement rule targets target instead of the detected backend. Placement is a planning decision: operators still select the real local backend at execute() time and fall back to the CPU reference, so planning for an absent GPU is safe — it is exactly what cluster executors do with the scheduler’s plans.

pub fn local_with_options( options: &SessionOptions, ) -> Result<OxideSession, EngineError>

An embedded session built with options.

pub async fn connect(scheduler_url: &str) -> Result<OxideSession, EngineError>

Connects to a Ballista scheduler (df://host:port). The session carries OxideLake’s plan codec so Gpu*Exec nodes survive the trip to executors, and the SQL UDFs so queries plan client-side; placement itself happens on the scheduler.

pub async fn connect_with_options( scheduler_url: &str, options: &SessionOptions, ) -> Result<OxideSession, EngineError>

Connects to a Ballista scheduler with options. target is ignored: on a cluster the scheduler’s OXIDE_CLUSTER_BACKEND decides placement, so a client-side target would be a knob that quietly does nothing.

pub fn mode(&self) -> &SessionMode

The execution mode.

pub fn ctx(&self) -> &SessionContext

The underlying DataFusion context.

pub fn telemetry(&self) -> &Arc<TelemetryHub>

The telemetry hub for this session.

Embedded sessions only. A cluster session’s operators run on executors, in other processes; this hub is created for the shape of the type and stays empty, so a snapshot of it is not “no work happened” but “the work happened somewhere else” (#33). Each worker reports into its own process-wide hub, which oxide-worker --metrics-port exposes as Prometheus text.

pub async fn sql(&self, query: &str) -> Result<DataFrame, EngineError>

Plans a SQL statement into a lazily executed DataFrame.

Nothing runs here, so nothing is logged here: see Self::collect for the one-line-per-query record.

pub async fn collect( &self, query: &str, ) -> Result<(Arc<Schema>, Vec<RecordBatch>), EngineError>

Runs query to completion and logs one INFO line describing it (#33): the backend it was planned for, the rows it produced, how long it took, and how many batches fell back to the CPU reference.

This is the line an operator reads to answer “is the GPU being used and how long did the query take” without attaching a dashboard. It is on collect rather than on Self::sql because a DataFrame has not run yet: a line logged at planning time could only report the plan, and the interesting half is what the plan then did. The schema comes back beside the batches because an empty result has no batch to take it from, and a caller rendering CSV still has to print the header.

pub async fn register_parquet( &self, name: &str, path: &str, ) -> Result<(), EngineError>

Registers a Parquet file or directory as name.

pub async fn explain(&self, query: &str) -> Result<String, EngineError>

The indented physical plan for query, with placement tags in embedded mode. In cluster mode this is the client-side plan (DistributedQueryExec); the scheduler’s plan is what carries the tags there.

Trait Implementations

impl Debug for OxideSession

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl OxideSessionExt for OxideSession

async fn read_parquet(&self, path: &str) -> Result<OxideFrame, EngineError>

Reads a Parquet file or directory as a frame.

async fn table(&self, name: &str) -> Result<OxideFrame, EngineError>

A frame over a registered table.

async fn sql_frame(&self, query: &str) -> Result<OxideFrame, EngineError>

Plans a SQL statement as a frame.