Existence & Flattening

if_exists, if_not_exists, and flatten_last cover common relationship shapes without forcing the model to materialize extra facts.

if_exists / if_not_exists

Use existence filters when the left row should survive only if a matching row exists, or only if no matching row exists, in another collection.

type Streams = ConstraintFactory<Schedule, HardSoftScore>;

Streams::new()
    .shifts()
    .if_exists((
        Streams::new().unavailability(),
        equal_bi(
            |shift: &Shift| shift.employee_idx,
            |u: &Unavailability| u.employee_idx,
        ),
    ))
    .penalize_hard()
    .named("Unavailable employee");

if_exists asks “does this item have at least one matching record over there?” if_not_exists asks the inverse. The public API stays simple while the runtime chooses faster internal bookkeeping for key shapes it can index directly.

Indexed usize Keys

Direct and flattened existence constraints with exact usize keys use dense indexed storage internally. Other key shapes, including Option<usize>, newtype keys, strings, and compound keys, keep hashed storage.

That storage decision does not change the stream API. Choose keys for modeling clarity first; the runtime uses the exact-key fast path when it is available.

flatten_last

Use flatten_last after a join when the last joined item owns a collection and the constraint needs to score individual child elements.

type Streams = ConstraintFactory<Schedule, HardSoftScore>;

Streams::new()
    .shifts()
    .join((
        Streams::new().employees(),
        equal_bi(
            |shift: &Shift| shift.employee_idx,
            |employee: &Employee| Some(employee.id),
        ),
    ))
    .flatten_last(
        |employee: &Employee| employee.available_days.as_slice(),
        |day| *day,
        |shift: &Shift| shift.date(),
    )

The three arguments are:

When To Use Which

See Also

• Joiners - equality, comparison, overlap, and filtering joiners
• Constraint Streams - the main stream pipeline