Struct Lazy 

pub struct Lazy<T: Model> { /* private fields */ }

A lazily-loaded related object that requires explicit load() call.

Unlike Related<T> which is loaded during the query via JOIN, Lazy<T> defers loading until explicitly requested with a Session reference.

States

• Empty: No FK value (null relationship)
• Unloaded: Has FK but not fetched yet
• Loaded: Object fetched and cached

Example

// Field definition
struct Hero {
    team: Lazy<Team>,
}

// Loading (requires Session)
let team = hero.team.load(&mut session, &cx).await?;

// After loading, access is fast
if let Some(team) = hero.team.get() {
    println!("Team: {}", team.name);
}

N+1 Prevention

Use Session::load_many() to batch-load lazy relationships:

// Load all teams in one query
session.load_many(&mut heroes, |h| &mut h.team).await?;

Implementations

impl<T: Model> Lazy<T>

pub fn empty() -> Self

Create an empty lazy relationship (null FK).

pub fn from_fk(fk: impl Into<Value>) -> Self

Create from a foreign key value (not yet loaded).

pub fn loaded(obj: T) -> Self

Create with an already-loaded object.

pub async fn load<L>( &mut self, cx: &Cx, loader: &mut L, ) -> Outcome<Option<&T>, Error>

where L: LazyLoader<T> + ?Sized,

Load the related object via the provided loader (cached after first success).

• If the FK is NULL, this caches None and returns Ok(None).
• If the loader errors/cancels/panics, this does not mark the relationship as loaded, allowing retries.

pub fn get(&self) -> Option<&T>

Get the loaded object (None if not loaded or FK is null).

pub fn is_loaded(&self) -> bool

Check if load() has been called.

pub fn is_empty(&self) -> bool

Check if the relationship is empty (null FK).

pub fn fk(&self) -> Option<&Value>

Get the foreign key value.

pub fn set_loaded(&self, obj: Option<T>) -> Result<(), Option<T>>

Set the loaded object (internal use by Session::load_many).

Returns Ok(()) if successfully set, Err if already loaded.

pub fn reset(&mut self)

Reset the lazy relationship to unloaded state.

This is useful when refreshing an object after commit.

Trait Implementations

impl<T: Model + Clone> Clone for Lazy<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Model + Debug> Debug for Lazy<T>

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

Formats the value using the given formatter.

impl<T: Model> Default for Lazy<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, T> Deserialize<'de> for Lazy<T>

where T: Model + Deserialize<'de>,

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl<T> Serialize for Lazy<T>

where T: Model + Serialize,

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.