Struct FieldRef 

pub struct FieldRef<M, T> { /* private fields */ }

Implementations

impl<M, T> FieldRef<M, T>

pub const fn new(column: &'static str) -> Self

pub const fn column_name(self) -> &'static str

The underlying SQL column name. Exposed so AST-builder helpers like super::coalesce::coalesce can interop with the typed FieldRef API without giving up generic-column flexibility.

pub fn asc(self) -> OrderClause

pub fn desc(self) -> OrderClause

impl<M, T> FieldRef<M, T>

pub fn eq<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn ne<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn in_<I, V>(self, values: I) -> Filter

where I: IntoIterator<Item = V>, V: IntoSqlValue,

pub fn lt<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn lte<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn gt<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn gte<V>(self, value: V) -> Filter

where V: IntoSqlValue,

pub fn eq_or_null<V>(self, value: V) -> Filter

where V: IntoSqlValue,

Match rows where the column is null OR equals value. The canonical inline-SQL workaround for “filter only if the caller provided this value, otherwise let nulls through” — schemas with sparse, optional foreign-key-style columns hit this constantly. Renders as (col IS NULL OR col = $1).

Use Self::match_optional when the caller’s value is itself an Option — that variant skips the filter entirely on None instead of binding a null.

pub fn match_optional<V>(self, value: Option<V>) -> Option<Filter>

where V: IntoSqlValue,

Filter on equality when the caller has a value, skip the filter entirely when they don’t. Returns None for the no-op case so callers can plumb it through [crate::FilterExpr::any_of_optional]-style helpers, or feed it directly into a where_optional(...) builder method on the query builders.

The emitted filter is the same (col IS NULL OR col = $1) as Self::eq_or_null — when the caller did supply a value, we still let nulls through, matching the canonical “optional-equality with null-as-wildcard” semantics from the inline-SQL pattern.

impl<M> FieldRef<M, bool>

pub fn is_true(self) -> Filter

pub fn is_false(self) -> Filter

impl<M> FieldRef<M, String>

pub fn contains(self, value: impl Into<String>) -> Filter

pub fn starts_with(self, value: impl Into<String>) -> Filter

impl<M, T> FieldRef<M, Option<T>>

pub fn is_null(self) -> Filter

pub fn is_not_null(self) -> Filter

impl<M> FieldRef<M, Option<String>>

pub fn contains(self, value: impl Into<String>) -> Filter

pub fn starts_with(self, value: impl Into<String>) -> Filter

impl<M, T> FieldRef<M, T>

pub fn json_has_key(self, key: impl Into<String>) -> FilterExpr

PG: col ? 'key' — the JSON document contains key as a top-level field. SQLite (no native ? operator): lowers to json_extract(col, '$.key') IS NOT NULL.

Intended for jsonb / JSON columns. Using this on a non-JSON column compiles fine but errors at the engine layer when the SQL runs — Rust’s type system doesn’t gate this for you.

The key is taken as impl Into<String> so callers can pass either a &'static str literal or a runtime-owned String (e.g. user-driven analytics queries that pivot on a metric name from the request).

pub fn json_get_text(self, key: impl Into<String>) -> JsonTextPath

PG: col ->> 'key' <op> $1 — extract the value at key as text, then compare. SQLite: json_extract(col, '$.key') <op> $1. Returns a JsonTextPath that supports the standard comparison ops via chained methods. See Self::json_has_key for the key-ownership rationale.

impl<M> FieldRef<M, Vec<f32>>

pub fn distance_to( self, metric: VectorMetric, query_vector: Vec<f32>, ) -> VectorDistanceExpr

Left-hand operand of a Vector(n) distance comparison (see docs/design/extensions.md §6/§7, cratestack#163) — chain a comparator (.lt/.lte/.gt/.gte/.eq) for a threshold filter, or .asc/.desc to use it as an ORDER BY target. The metric is never inferred from an index (a similarity search must keep working with no vector index present, per AC #2 on cratestack#163) — pass it explicitly, or derive it from a known index opclass via VectorMetric::from_opclass.

PG-only (pgvector); the embedded rusqlite backend fails loud at render time if reached, mirroring [Self::covers_geography].

pub fn order_by_distance( self, metric: VectorMetric, query_vector: Vec<f32>, ) -> OrderClause

Shorthand for distance_to(metric, query_vector).asc() — order by distance, nearest first, the standard k-NN similarity-search shape.

impl<M> FieldRef<M, Option<Vec<f32>>>

pub fn distance_to( self, metric: VectorMetric, query_vector: Vec<f32>, ) -> VectorDistanceExpr

Same as FieldRef::<M, Vec<f32>>::distance_to for a nullable Vector(n) column. Rows with a NULL vector compare as NULL distance, which sorts last under the framework’s default NULLS LAST ordering (crate::NullOrder) and never matches a threshold filter.

pub fn order_by_distance( self, metric: VectorMetric, query_vector: Vec<f32>, ) -> OrderClause

Shorthand for distance_to(metric, query_vector).asc().

Trait Implementations

impl<M: Clone, T: Clone> Clone for FieldRef<M, T>

fn clone(&self) -> FieldRef<M, T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: Copy, T: Copy> Copy for FieldRef<M, T>

impl<M: Debug, T: Debug> Debug for FieldRef<M, T>

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

Formats the value using the given formatter.

impl<M, T> IntoColumnName for FieldRef<M, T>

fn into_column_name(self) -> &'static str