ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! [`Scored`] — what a searching store hands back: the thing it matched, and the score it matched
//! at.
//!
//! At the seam layer rather than inside a family, for the reason [`Connected`](super::Connected) is
//! one file over: it belongs to no single engine. `Connected` is the shape every op RECEIVES, and
//! this is the shape every SEARCH returns — [`VectorRead::knn`](super::VectorRead::knn) and
//! [`FulltextRead::search`](super::FulltextRead::search), because both answer with a KEY rather than
//! with the row it addresses. One type for both is what keeps them from being two that must agree
//! and are free to stop.

/// One search result: what matched, and the score it matched at.
///
/// A named type rather than a `(D, S)`, so a reader takes [`data_ref`](Self::data_ref) and
/// [`score_ref`](Self::score_ref) instead of remembering which half of a pair is which. The tuple
/// is still reachable, at the one point it costs nothing to be one:
/// [`into_components`](Self::into_components), where the hit is being taken apart anyway.
///
/// # The score's SHAPE is a parameter, and NOTHING defaults it
///
/// Every scoring node answers in its own currency: a cosine or L2 DISTANCE (lower is closer), an
/// inner product, a BM25 relevance (unbounded above), a fused rank. `S` has no default, so the
/// currency is SPELLED by whoever produces the hit — a seam names it as an associated type and a
/// backend fills that in with what its engine measures in.
///
/// The default that is not here would have been `f32`, and what it bought is the reason there is
/// none: a signature reading `Vec<Scored<R::Key>>` reads NEUTRAL over the whole family while
/// pinning one engine's arithmetic. `f32` is BM25's shape and the shape a cosine face reports in;
/// it is not the shape a quantised backend, a fused rank or a posterior arrives in, and the first
/// member to answer in another one would have had to move every signature that had been reading as
/// though it did not care. A parameter spelled at every site is the same fact with nowhere left for
/// it to hide.
///
/// Spelling `Scored<D, Score>` is the MARKED form. [`Score`](crate::Score) IS the closed unit
/// interval, so writing it is a claim that something normalised the value, made at the place the
/// normalising happened rather than assumed by a later reader of an `f32`.
///
/// The dividend lands at the layer above: two hit lists at different `S` do not merge, and making
/// them merge is a conversion somebody writes down. Normalisation stops being an undocumented
/// convention about what an `f32` means here and becomes an act with a type.
///
/// # `D` is what matched, which is not always a key
///
/// An index answers with ADDRESSES, which is why [`VectorRead::knn`](super::VectorRead::knn)
/// returns `Scored<Self::Address, Self::Score>` — identity and score, never the payload. A fusion
/// layer ranks
/// whatever it is holding, hydrated records included, so the field is the DATA and
/// `Scored<Record, S>` is spellable without a second type being born to say it.
///
/// # No bound on either parameter
///
/// Ordering is not a property of a hit. It is what a sort or a merge asks for, so the
/// `PartialOrd`-class bound belongs at that call site, spent by the body that needs it — and no
/// such site exists yet.
///
/// # The accessors are the emitted pair, under this type's own names
///
/// A generated column is handed out as `x_ref(&self) -> &T`, with `x(&self) -> T` beside it where
/// the column is `copy` — the borrow always, the copy in addition. Both halves here follow it:
/// [`data_ref`](Self::data_ref) and [`score_ref`](Self::score_ref) are always there, and
/// [`data`](Self::data) and [`score`](Self::score) sit beside them behind a `Copy` gate written on
/// the METHOD.
///
/// On the method rather than on the parameter, which is what keeps a shape that cannot be copied
/// from being locked out of the type: a `String` key or a composite fused score is stored, borrowed
/// and decomposed exactly as an `f32` is, and the only thing it refuses is being handed back by
/// value for free — `E0277` at that call and nowhere else. Binding `Copy` on `D` or `S` would have
/// made the whole type unavailable to them to spare two methods.
#[derive(Debug, Clone, PartialEq)]
pub struct Scored<D, S> {
  data: D,
  score: S,
}

/// A search's whole answer: its hits, ordered as the engine ranked them.
///
/// Named rather than spelled `Vec<Scored<D, S>>` at each seam that returns one, which
/// `clippy::type_complexity` refuses inside an RPITIT `Result`. It abbreviates nothing — both
/// parameters ride through it, so the score's currency is as visible at a seam as it is here.
pub type Hits<D, S> = Vec<Scored<D, S>>;

impl<D, S> Scored<D, S> {
  /// Pair what matched with the score the search gave it.
  #[inline]
  pub const fn new(data: D, score: S) -> Self {
    Self { data, score }
  }

  /// What matched, BORROWED.
  ///
  /// The half every shape can answer, which is why nothing is required of `D` for it.
  #[inline(always)]
  pub const fn data_ref(&self) -> &D {
    &self.data
  }

  /// What matched, BY VALUE, where it is `Copy` — a bare row id, a `u64` key.
  #[inline(always)]
  pub const fn data(&self) -> D
  where
    D: Copy,
  {
    *self.data_ref()
  }

  /// The score, BORROWED, in the scoring node's own currency and direction.
  ///
  /// The half every score shape can answer: a composite fused score that is no more `Copy` than a
  /// `String` is comes back through here.
  #[inline(always)]
  pub const fn score_ref(&self) -> &S {
    &self.score
  }

  /// The score, BY VALUE, where it is `Copy` — the raw `f32` and a [`Score`](crate::Score) both are.
  #[inline(always)]
  pub const fn score(&self) -> S
  where
    S: Copy,
  {
    *self.score_ref()
  }

  /// Take what matched, dropping the score — for a caller that has finished ranking and now
  /// hydrates.
  ///
  /// [`into_components`](Self::into_components)`.0` says the same thing; this is the name for the
  /// case that is only ever that, and it is the call the hydration sites already write.
  #[inline]
  pub fn into_data(self) -> D {
    self.data
  }

  /// Take both halves, neither cloned — for a caller that keeps the score as well: a merge writing
  /// a fused rank, a wire mapping rendering the pair, a normaliser building the marked hit its
  /// output declares.
  #[inline]
  pub fn into_components(self) -> (D, S) {
    (self.data, self.score)
  }
}

#[cfg(test)]
mod tests;