Struct Reference 

#[non_exhaustive]
pub struct Reference {
    pub name: String,
    pub kind: ReferenceKind,
    pub target: String,
    pub keys: Vec<JoinKey>,
    pub host_column: Option<String>,
    pub build_script: Option<String>,
}

A relation a Vista exposes: a join to another table, or records contained in a column of this table’s rows. Traversed with Vista::get_ref.

A join (HasOne, HasMany) narrows the target table by its keys: each JoinKey reads the parent row’s from column and constrains the target’s to column to that value. A contained relation (ContainsOne, ContainsMany) reads the parent row’s host_column and has no keys.

Build one with the constructor of its kind, so the kind and its fields agree. Deserialising checks the same agreement: a contained kind needs a host_column and no keys, a join needs at least one key and no host_column, and only a join takes a build_script.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

name: String

kind: ReferenceKind

target: String

The target table; for a contained relation, the relation’s own name.

keys: Vec<JoinKey>

host_column: Option<String>

Contained kinds: the parent column holding the embedded object (one) or array of objects (many).

build_script: Option<String>

Rhai script that builds a join’s traversal target in place of the keys, evaluated with the parent row in scope (rhai feature). Lowered from the per-reference YAML extras slot by each backend factory.

Implementations

impl Reference

pub fn narrow(&self, target: Vista, row: &Record<CborValue>) -> Result<Vista>

Narrow this join’s bare target to the rows related to row.

Each key reads the parent’s from column and constrains the target’s target_column to that value through Vista::add_condition. The target’s query() therefore records the join, and the target must take the constrained column. A driver that compares ids by type converts the value in its own add_condition.

A contained relation, or a join whose public keys were emptied, has nothing to narrow by and is an IncorrectUsage error. Other errors carry relation and column context. A refusal (Unsupported or Unimplemented, such as a computed join column) stays a refusal; any other failure is a normal error.

impl Reference

pub fn has_one( name: impl Into<String>, target: impl Into<String>, key: JoinKey, ) -> Self

One target row, found through key on the parent row. A join on several keys is lowered from YAML by ReferenceSpec::to_reference.

pub fn has_many( name: impl Into<String>, target: impl Into<String>, key: JoinKey, ) -> Self

The target rows whose key matches the parent row. A join on several keys is lowered from YAML by ReferenceSpec::to_reference.

pub fn contains_one( name: impl Into<String>, host_column: impl Into<String>, ) -> Self

One record embedded as an object in the parent’s host_column.

pub fn contains_many( name: impl Into<String>, host_column: impl Into<String>, ) -> Self

Records embedded as an array in the parent’s host_column.

pub fn with_build_script(self, script: impl Into<String>) -> Result<Self>

Attach a Rhai build script; see build_script. A contained relation has no traversal target to build, so it is a plain error naming the relation.

Trait Implementations

impl Clone for Reference

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Reference

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Reference

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Reference

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Reference

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Reference