Trait TableShell 

pub trait TableShell:
    CloneTableShell
    + Send
    + Sync
    + 'static {
    // Required methods
    fn metadata(&self) -> &VistaMetadata;
    fn capabilities(&self) -> &VistaCapabilities;
    fn driver_name(&self) -> &'static str;
    fn preview(&self) -> Preview;
    fn list<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<IndexMap<String, Record<Value>>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn get<'life0, 'life1, 'async_trait>(
        &'life0 self,
        id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<Option<Record<Value>>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn count<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn fetch_window<'life0, 'async_trait>(
        &'life0 self,
        offset: usize,
        limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<Page>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait;
    fn add_condition(&mut self, condition: &Condition) -> Result<()>;

    // Provided methods
    fn fetch_cursor<'life0, 'async_trait>(
        &'life0 self,
        _token: Option<CborValue>,
        _limit: usize,
    ) -> Pin<Box<dyn Future<Output = Result<(Page, Option<CborValue>)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn watch<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<VistaChangeStream>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn add_native_condition(
        &mut self,
        _condition: NativeCondition,
    ) -> Result<()> { ... }
    fn set_search(&mut self, _text: Option<&str>) -> Result<()> { ... }
    fn set_order(&mut self, _order: Option<(&str, SortDirection)>) -> Result<()> { ... }
    fn insert<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _id: Option<&'life1 str>,
        _record: &'life2 Record<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<(String, Record<Value>)>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn replace<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
        _record: &'life2 Record<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn upsert<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
        _record: &'life2 Record<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn patch<'life0, 'life1, 'life2, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
        _partial: &'life2 Record<Value>,
    ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait,
             'life2: 'async_trait { ... }
    fn delete<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _id: &'life1 str,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn delete_all<'life0, 'async_trait>(
        &'life0 self,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait { ... }
    fn import<'life0, 'life1, 'async_trait>(
        &'life0 self,
        _rows: &'life1 IndexMap<String, Record<Value>>,
    ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>
       where Self: 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn get_ref(
        &self,
        _relation: &str,
        _row: Option<&Record<Value>>,
    ) -> Result<Vista> { ... }
}

The driver side of a Vista: schema, reads, narrowing and writes over one table of one backend.

A shell owns its query state. Vista narrows an owned clone through the &mut self methods, so a shell’s Clone must carry its current narrowing and own it independently, while sharing the store or connection. Every read and write runs over the shell’s current narrowing.

A method with a default answers unsupported with the capability that names it; a shell that implements the method advertises that capability in capabilities. See Capability for the mapping.

Ids are strings at this boundary, and values are CBOR: every driver’s native id (Mongo ObjectId, Surreal Thing, …) stringifies here.

Required Methods

fn metadata(&self) -> &VistaMetadata

The set’s columns, references and id column. Vista reads its metadata vocabulary (columns, column, id_column, …) from here.

fn capabilities(&self) -> &VistaCapabilities

fn driver_name(&self) -> &'static str

Short label for the driver ("csv", "sqlite", "mongodb").

fn preview(&self) -> Preview

The query the next read would send, rendered without sending it. Synchronous and performs no I/O: a value known only at fetch time renders as a placeholder. Lossy is acceptable, wrong is not. See Preview for what query and note each hold.

fn list<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<IndexMap<String, Record<Value>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Every row of the set, keyed by id, in the set’s order.

fn get<'life0, 'life1, 'async_trait>( &'life0 self, id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<Option<Record<Value>>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Row id when it is in the set.

fn count<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<i64>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

fn fetch_window<'life0, 'async_trait>( &'life0 self, offset: usize, limit: usize, ) -> Pin<Box<dyn Future<Output = Result<Page>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Rows [offset, offset + limit) of the set, in its order.

The leading window (offset == 0) is required of every shell whose list works: it is how a capped read and get_some_value read. A shell that can’t push a window to its backend answers it with Page::from_listing over its listed rows. Window means any offset; Vista refuses offset > 0 without it before the shell is called.

fn add_condition(&mut self, condition: &Condition) -> Result<()>

Narrow the set by condition. Every shell takes equality; Vista refuses other operators unless the shell advertises FilterOps. An unknown column or a bad value is a normal error, not Unsupported.

A dotted column (root.leaf) names a field nested in a declared root’s value. The shell either evaluates it (narrowing to the rows whose root holds a matching leaf) or rejects it with a normal error. It never accepts the path and matches nothing.

Provided Methods

fn fetch_cursor<'life0, 'async_trait>( &'life0 self, _token: Option<CborValue>, _limit: usize, ) -> Pin<Box<dyn Future<Output = Result<(Page, Option<CborValue>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Up to limit rows after token (None starts at the beginning) and the token for the next call, None once the set is exhausted (Cursor). The token is driver-private; callers hand it back unchanged. Vista refuses the call without Cursor before the shell is called.

fn watch<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<VistaChangeStream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Subscribe to changes on the set (Subscribe).

Delivery is best-effort, and four promises hold for every driver:

1. the stream may be coarser than the set (table-wide is valid);
2. so a payload row may fall outside the set: either the driver reconciles (re-reads the id through the set, reporting Deleted) or the consumer must;
3. Invalidated means “re-read everything”;
4. the stream ending is normal; consumers resubscribe and reconcile.

Advertise Subscribe only when the driver pushes with no further setup, or the application declared the setup done: a stream that stays silent can’t be told apart from nothing happening. Vista refuses the call without Subscribe before the shell is called.

fn add_native_condition(&mut self, _condition: NativeCondition) -> Result<()>

Narrow the set by a condition in the driver’s own type (NativeConditions). A condition of a type the driver doesn’t take is an IncorrectUsage error.

fn set_search(&mut self, _text: Option<&str>) -> Result<()>

Replace the quicksearch text; None clears it (Search). Quicksearch reads the columns flagged Searchable, or every column when none is (VistaMetadata::search_columns); a shell may exclude columns it can’t filter on (dotted paths, imported columns). Text the backend can’t express is a normal error, not Unsupported.

fn set_order(&mut self, _order: Option<(&str, SortDirection)>) -> Result<()>

Replace the order; None clears it (Order). An unknown column is a normal error, not Unsupported.

fn insert<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _id: Option<&'life1 str>, _record: &'life2 Record<Value>, ) -> Pin<Box<dyn Future<Output = Result<(String, Record<Value>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Insert record as row id, or under an id the backend makes when id is None (not retry-safe). Returns the id and the stored row. An id already in the set returns the stored row untouched; an id held outside the set is Conflict; a new row is conformed to the set’s equality conditions.

fn replace<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _id: &'life1 str, _record: &'life2 Record<Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Replace row id, creating it when missing; an id held outside the set is Conflict.

fn upsert<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _id: &'life1 str, _record: &'life2 Record<Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Insert row id, or replace it when it exists, in one operation.

fn patch<'life0, 'life1, 'life2, 'async_trait>( &'life0 self, _id: &'life1 str, _partial: &'life2 Record<Value>, ) -> Pin<Box<dyn Future<Output = Result<Record<Value>>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait,

Merge partial into row id. A row outside the set or missing is NotFound; a result that leaves the set is Conflict.

fn delete<'life0, 'life1, 'async_trait>( &'life0 self, _id: &'life1 str, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Remove row id when it is in the set; Ok whether it was in the set, outside it, or missing.

fn delete_all<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Remove exactly the rows in the set.

fn import<'life0, 'life1, 'async_trait>( &'life0 self, _rows: &'life1 IndexMap<String, Record<Value>>, ) -> Pin<Box<dyn Future<Output = Result<usize>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Store rows in one all-or-nothing, driver-native operation and return how many were newly inserted; an id already held counts zero (Import). A driver that can’t make the batch atomic, or can’t tell new rows from existing ones, doesn’t advertise Import; callers then insert row by row.

fn get_ref( &self, _relation: &str, _row: Option<&Record<Value>>, ) -> Result<Vista>

The target of relation (Traverse): with a parent row (from this shell’s set), the related rows; with None, the bare target a new related row is inserted into. Contained relations route through here too: from a row, the records it embeds; with None, the contained schema with no records and no write capabilities, since there is no parent row to write into.

Narrow a target for a row through Vista::add_condition (or with_condition, with_native_condition), never through the target shell directly, so that the returned Vista’s query() records the join and is_narrowed() holds.

Trait Implementations

impl Clone for Box<dyn TableShell>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<T: ForwardShell + Clone> TableShell for T