Trait Relation

Source

pub trait Relation {
    // Required method
    fn next_row(&mut self) -> Result<Option<Value>, Error>;

    // Provided method
    fn size_hint(&self) -> Option<usize> { ... }
}

Expand description

A relation, delivered one row at a time.

§The smallest interface that permits early termination

The previous contract handed back an owned Vec<Value>, which forced the whole relation to exist before any work could start. That is fine until execution can stop early — and once LIMIT can stop a join, a contract that insists on materialising 8000 rows to return 20 becomes the bottleneck. It was measured as exactly that: after the filter fusion in #120, the hash path’s remaining time was dominated by cloning relations rather than probing them.

So this is deliberately two methods, not an async stream and not a borrowing iterator with a lifetime parameter threaded through the whole evaluator. Pull a row; stop whenever you like by dropping it.

size_hint exists only so the join planner can keep choosing a strategy from relation sizes. A source that genuinely does not know returns None, and the planner then decides from what it does know rather than pretending.