Enum Stat 

pub enum Stat<T> {
    Known {
        value: T,
        class: Class,
        provenance: Provenance,
    },
    Unknown,
}

One statistic, or the honest absence of one.

Known carries the value and how much to trust it. Unknown is what a question has no answer to, and the whole design rests on callers treating it as a case rather than as a zero.

Variants

Known

A value, what kind of knowledge it is, and where it came from.

Fields

value: T

The number, bound, flag or set the question asked for.

class: Class

How much of it is known rather than guessed.

provenance: Provenance

What produced it, which is what EXPLAIN prints next to the class.

Unknown

No answer. Not a zero, not a one and not a default.

Not written, not resident, or not applicable. This is the ordinary answer for a statistic whose load has just been scheduled, because spec/stats/04-in-memory.md says no query ever waits on one, and it is the honest one.

Implementations

impl<T> Stat<T>

pub const fn exact(value: T, provenance: Provenance) -> Self

A value that was counted, compared or maintained rather than guessed, and what produced it.

pub const fn certified( value: T, bound: f64, direction: Direction, provenance: Provenance, ) -> Self

A value wrong by no more than bound as a fraction of itself, on the side direction says.

pub const fn estimated(value: T, provenance: Provenance) -> Self

A guess, and where it came from.

pub const fn is_known(&self) -> bool

Whether there is an answer at all.

pub const fn is_unknown(&self) -> bool

Whether there is no answer.

pub const fn value(&self) -> Option<&T>

The value, whatever its class.

Present because plenty of code wants to print a number or compare two of them without making a claim about either. A caller that is about to act on it wants Self::decide, Self::answer or Self::enable instead, because those say which of the three uses is happening and this one does not.

pub const fn decide(&self) -> Option<&T>

The value for a decision that chooses between two plans producing the same rows.

Build side, grouping strategy, join order, reduction schedule, memory reservation, parallel degree. Entitled to any class, so this is Self::value under a name that says what is being done with it. None means the caller takes its documented default, and the worst case is a slow query with a printed reason.

pub const fn enable(&self) -> Option<&T>

The value for a rewrite that would be wrong if the value were wrong.

Join elimination, sort elimination, distinct elimination, group by elimination, partition pruning, an exact IN list filter, narrowing arithmetic, folding a predicate away. Exact and nothing else, because a bound is not an equality and these need an equality.

This is the strictest of the three and the one easiest to get wrong, because an enabling rewrite on a statistic that is merely close does not produce a slow query, it produces a wrong answer. See spec/stats/05-every-query.md sections 5.1.1 and 5.10.

pub const fn answer(&self) -> Option<&T>

The value for a statistic that is itself the result, where that value is exact.

COUNT(*) out of a row count, MIN out of a zone map whose bounds are values rather than widened bounds. A certified answer does not come back from here, because answering from a certificate needs the proof obligation discharged and this function has nothing to discharge it with. Use Self::answer_certified for that case and keep the fallback.

pub fn answer_certified( &self, discharge: impl FnOnce(f64, Direction) -> bool, ) -> Option<&T>

The value for a statistic that is itself the result, where a certificate is acceptable and the caller can discharge it.

discharge is handed the bound and its direction and says whether this particular query can live with them. A top-k group by out of a frequency synopsis is the case this exists for: the synopsis answers when the k-th count is above the certified maximum of everything it omitted, and does not otherwise. A caller that returns true unconditionally has written Self::decide with extra steps and should say so.

pub const fn exact_value(&self) -> Option<&T>

The value, but only when it is exact.

The older name for Self::enable, kept because the rule it enforces is stated under this name in spec/stats/05-every-query.md section 5.10 and because a door that changes an answer is worth being able to grep for two ways.

pub const fn class(&self) -> Option<Class>

How much of the answer is knowledge, or None when there is no answer.

pub const fn provenance(&self) -> Option<Provenance>

What produced the answer, or None when there is no answer.

pub const fn permits(&self, use_: Use) -> bool

Whether this answer is enough for that use, per the class rule.

pub fn unwrap_or(self, default: T) -> T

The value, or what the caller decided to do without one.

pub fn map<U>(self, f: impl FnOnce(T) -> U) -> Stat<U>

The same answer about a different quantity, with the class carried across unchanged.

For a transformation that cannot lose knowledge, such as reading a row count as a byte count through a fixed width. A transformation that does lose knowledge should build its answer with the class it deserves rather than mapping.

pub fn zip<U, V>(self, other: Stat<U>, f: impl FnOnce(T, U) -> V) -> Stat<V>

An answer computed from two, unknown when either is unknown, classed by Class::combine.

The provenance of the result is Provenance::Propagation unless both sides agree, because a number derived from a zone map and a row count came from neither of them on its own.

Trait Implementations

impl<T: Clone> Clone for Stat<T>

fn clone(&self) -> Stat<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Copy> Copy for Stat<T>

impl<T: Debug> Debug for Stat<T>

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

Formats the value using the given formatter.

impl<T> Default for Stat<T>

fn default() -> Self

Unknown, because a statistic nobody filled in is a statistic nobody knows.

impl<T: Display> Display for Stat<T>

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

Formats the value using the given formatter.

impl<T: PartialEq> PartialEq for Stat<T>

fn eq(&self, other: &Stat<T>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<T: PartialEq> StructuralPartialEq for Stat<T>