Enum WhereOperator 

#[non_exhaustive]
pub enum WhereOperator {
    Eq(Field, Value),
    Neq(Field, Value),
    Gt(Field, Value),
    Gte(Field, Value),
    Lt(Field, Value),
    Lte(Field, Value),
    In(Field, Vec<Value>),
    Nin(Field, Vec<Value>),
    Contains(Field, String),
    ArrayContains(Field, Value),
    ArrayContainedBy(Field, Value),
    ArrayOverlaps(Field, Vec<Value>),
    LenEq(Field, usize),
    LenGt(Field, usize),
    LenGte(Field, usize),
    LenLt(Field, usize),
    LenLte(Field, usize),
    Icontains(Field, String),
    Startswith(Field, String),
    Istartswith(Field, String),
    Endswith(Field, String),
    Iendswith(Field, String),
    Like(Field, String),
    Ilike(Field, String),
    IsNull(Field, bool),
    L2Distance {
        field: Field,
        vector: Vec<f32>,
        threshold: f32,
    },
    CosineDistance {
        field: Field,
        vector: Vec<f32>,
        threshold: f32,
    },
    InnerProduct {
        field: Field,
        vector: Vec<f32>,
        threshold: f32,
    },
    L1Distance {
        field: Field,
        vector: Vec<f32>,
        threshold: f32,
    },
    HammingDistance {
        field: Field,
        vector: Vec<f32>,
        threshold: f32,
    },
    JaccardDistance {
        field: Field,
        set: Vec<String>,
        threshold: f32,
    },
    Matches {
        field: Field,
        query: String,
        language: Option<String>,
    },
    PlainQuery {
        field: Field,
        query: String,
    },
    PhraseQuery {
        field: Field,
        query: String,
        language: Option<String>,
    },
    WebsearchQuery {
        field: Field,
        query: String,
        language: Option<String>,
    },
    IsIPv4(Field),
    IsIPv6(Field),
    IsPrivate {
        field: Field,
        value: bool,
    },
    IsLoopback {
        field: Field,
        value: bool,
    },
    IsMulticast {
        field: Field,
        value: bool,
    },
    IsLinkLocal {
        field: Field,
        value: bool,
    },
    IsDocumentation {
        field: Field,
        value: bool,
    },
    IsCarrierGrade {
        field: Field,
        value: bool,
    },
    InSubnet {
        field: Field,
        subnet: String,
    },
    ContainsSubnet {
        field: Field,
        subnet: String,
    },
    ContainsIP {
        field: Field,
        ip: String,
    },
    IPRangeOverlap {
        field: Field,
        range: String,
    },
    StrictlyContains(Field, Value),
    AncestorOf {
        field: Field,
        path: String,
    },
    DescendantOf {
        field: Field,
        path: String,
    },
    MatchesLquery {
        field: Field,
        pattern: String,
    },
    MatchesLtxtquery {
        field: Field,
        query: String,
    },
    MatchesAnyLquery {
        field: Field,
        patterns: Vec<String>,
    },
    DepthEq {
        field: Field,
        depth: usize,
    },
    DepthNeq {
        field: Field,
        depth: usize,
    },
    DepthGt {
        field: Field,
        depth: usize,
    },
    DepthGte {
        field: Field,
        depth: usize,
    },
    DepthLt {
        field: Field,
        depth: usize,
    },
    DepthLte {
        field: Field,
        depth: usize,
    },
    Lca {
        field: Field,
        paths: Vec<String>,
    },
    DescendantOfId {
        field: Field,
        id: String,
    },
    AncestorOfId {
        field: Field,
        id: String,
    },
}

WHERE clause operators

Supports type-safe, audit-friendly WHERE clause construction without raw SQL strings.

Categories

• Comparison: Eq, Neq, Gt, Gte, Lt, Lte
• Array: In, Nin, Contains, ArrayContains, ArrayContainedBy, ArrayOverlaps
• Array Length: LenEq, LenGt, LenGte, LenLt, LenLte
• String: Icontains, Startswith, Istartswith, Endswith, Iendswith, Like, Ilike
• Null: IsNull
• Vector Distance: L2Distance, CosineDistance, InnerProduct, L1Distance, HammingDistance, JaccardDistance
• Full-Text Search: Matches, PlainQuery, PhraseQuery, WebsearchQuery
• Network: IsIPv4, IsIPv6, IsPrivate, IsLoopback, InSubnet, ContainsSubnet, ContainsIP, IPRangeOverlap
• JSONB: StrictlyContains
• LTree: AncestorOf, DescendantOf, MatchesLquery, MatchesLtxtquery, MatchesAnyLquery, DepthEq, DepthNeq, DepthGt, DepthGte, DepthLt, DepthLte, Lca

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Eq(Field, Value)

Equal: field = value

Neq(Field, Value)

Not equal: field != value or field <> value

Gt(Field, Value)

Greater than: field > value

Gte(Field, Value)

Greater than or equal: field >= value

Lt(Field, Value)

Less than: field < value

Lte(Field, Value)

Less than or equal: field <= value

In(Field, Vec<Value>)

Array contains value: field IN (...)

Nin(Field, Vec<Value>)

Array does not contain value: field NOT IN (...)

Contains(Field, String)

String contains substring: field LIKE '%substring%'

Warning — LIKE wildcard injection

The substring is embedded between % anchors. Characters % (any sequence) and _ (any single character) in the substring itself are also treated as LIKE wildcards, causing broader matches than intended. Escape user-supplied values (replace % → \% and _ → \_) before constructing this variant.

ArrayContains(Field, Value)

Array contains element: PostgreSQL array operator @> Generated SQL: field @> array[value]

ArrayContainedBy(Field, Value)

Array is contained by: PostgreSQL array operator <@ Generated SQL: field <@ array[value]

ArrayOverlaps(Field, Vec<Value>)

Arrays overlap: PostgreSQL array operator && Generated SQL: field && array[value]

LenEq(Field, usize)

Array length equals: array_length(field, 1) = value

LenGt(Field, usize)

Array length greater than: array_length(field, 1) > value

LenGte(Field, usize)

Array length greater than or equal: array_length(field, 1) >= value

LenLt(Field, usize)

Array length less than: array_length(field, 1) < value

LenLte(Field, usize)

Array length less than or equal: array_length(field, 1) <= value

Icontains(Field, String)

Case-insensitive contains: field ILIKE '%substring%'

Warning — LIKE wildcard injection

Same escaping requirements as WhereOperator::Contains. ILIKE applies the same wildcard semantics, so % and _ in the substring expand unexpectedly.

Startswith(Field, String)

Starts with: field LIKE 'prefix%'

Warning — LIKE wildcard injection

The prefix string is passed verbatim before the trailing %. Characters % and _ in the prefix are treated as wildcards; escape user-supplied values before use.

Istartswith(Field, String)

Starts with (case-insensitive): field ILIKE 'prefix%'

Warning — LIKE wildcard injection

Same escaping requirements as WhereOperator::Startswith.

Endswith(Field, String)

Ends with: field LIKE '%suffix'

Warning — LIKE wildcard injection

The suffix string is passed verbatim after the leading %. Characters % and _ in the suffix are treated as wildcards; escape user-supplied values before use.

Iendswith(Field, String)

Ends with (case-insensitive): field ILIKE '%suffix'

Warning — LIKE wildcard injection

Same escaping requirements as WhereOperator::Endswith.

Like(Field, String)

LIKE pattern matching: field LIKE pattern

Warning — LIKE wildcard injection

The pattern string is passed to the database as-is. Characters % (any sequence) and _ (any single character) are SQL LIKE wildcards. If the pattern originates from user input, callers must escape these characters (e.g. replace % → \% and _ → \_) before constructing this variant, and append the appropriate ESCAPE '\' clause.

Ilike(Field, String)

Case-insensitive LIKE: field ILIKE pattern

Warning — LIKE wildcard injection

Same escaping requirements as WhereOperator::Like. The % and _ wildcards apply to ILIKE patterns as well.

IsNull(Field, bool)

IS NULL: field IS NULL or field IS NOT NULL

When the boolean is true, generates IS NULL When false, generates IS NOT NULL

L2Distance

L2 (Euclidean) distance: l2_distance(field, vector) < threshold

Requires pgvector extension.

Fields

field: Field

The vector field to compare against

vector: Vec<f32>

The embedding vector for distance calculation

threshold: f32

Distance threshold for comparison

CosineDistance

Cosine distance: cosine_distance(field, vector) < threshold

Requires pgvector extension.

Fields

field: Field

The vector field to compare against

vector: Vec<f32>

The embedding vector for distance calculation

threshold: f32

Distance threshold for comparison

InnerProduct

Inner product: inner_product(field, vector) > threshold

Requires pgvector extension.

Fields

field: Field

The vector field to compare against

vector: Vec<f32>

The embedding vector for distance calculation

threshold: f32

Distance threshold for comparison

L1Distance

L1 (Manhattan) distance: l1_distance(field, vector) < threshold

Requires pgvector extension.

Fields

field: Field

The vector field to compare against

vector: Vec<f32>

The embedding vector for distance calculation

threshold: f32

Distance threshold for comparison

HammingDistance

Hamming distance: hamming_distance(field, vector) < threshold

Requires pgvector extension. Works with bit vectors.

Fields

field: Field

The vector field to compare against

vector: Vec<f32>

The embedding vector for distance calculation

threshold: f32

Distance threshold for comparison

JaccardDistance

Jaccard distance: jaccard_distance(field, set) < threshold

Works with text arrays, measures set overlap.

Fields

field: Field

The field to compare against

set: Vec<String>

The set of values for comparison

threshold: f32

Distance threshold for comparison

Matches

Full-text search with language: field @@ plainto_tsquery(language, query)

If language is None, defaults to ‘english’

Fields

field: Field

The text field to search

query: String

The search query

language: Option<String>

Optional language for text search (default: english)

PlainQuery

Plain text query: field @@ plainto_tsquery(query)

Uses no language specification

Fields

field: Field

The text field to search

query: String

The search query

PhraseQuery

Phrase query with language: field @@ phraseto_tsquery(language, query)

If language is None, defaults to ‘english’

Fields

field: Field

The text field to search

query: String

The search query

language: Option<String>

Optional language for text search (default: english)

WebsearchQuery

Web search query with language: field @@ websearch_to_tsquery(language, query)

If language is None, defaults to ‘english’

Fields

field: Field

The text field to search

query: String

The search query

language: Option<String>

Optional language for text search (default: english)

IsIPv4(Field)

Check if IP is IPv4: family(field) = 4

IsIPv6(Field)

Check if IP is IPv6: family(field) = 6

IsPrivate

Check if IP is private (RFC1918/ULA): matches private ranges.

When value is true, generates a positive containment check. When value is false, generates the negated check (equivalent to “is public”).

Fields

field: Field

The IP field to check

value: bool

true = is private, false = is public (NOT private)

IsLoopback

Check if IP is loopback: IPv4 127.0.0.0/8 or IPv6 ::1/128.

When value is false, generates the negated check.

Fields

field: Field

The IP field to check

value: bool

true = is loopback, false = is NOT loopback

IsMulticast

Check if IP is multicast: IPv4 224.0.0.0/4 or IPv6 ff00::/8 (RFC 3171, RFC 4291).

When value is false, generates the negated check.

Fields

field: Field

The IP field to check

value: bool

true = is multicast, false = is NOT multicast

IsLinkLocal

Check if IP is link-local: IPv4 169.254.0.0/16 or IPv6 fe80::/10 (RFC 3927, RFC 4291).

When value is false, generates the negated check.

Fields

field: Field

The IP field to check

value: bool

true = is link-local, false = is NOT link-local

IsDocumentation

Check if IP is in a documentation range (RFC 5737, RFC 3849): IPv4 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24; IPv6 2001:db8::/32.

When value is false, generates the negated check.

Fields

field: Field

The IP field to check

value: bool

true = is documentation, false = is NOT documentation

IsCarrierGrade

Check if IP is in carrier-grade NAT range (RFC 6598): 100.64.0.0/10 (IPv4 only).

When value is false, generates the negated check.

Fields

field: Field

The IP field to check

value: bool

true = is carrier-grade, false = is NOT carrier-grade

InSubnet

IP is in subnet: field << subnet

The subnet should be in CIDR notation (e.g., “192.168.0.0/24”)

Fields

field: Field

The IP field to check

subnet: String

The CIDR subnet (e.g., “192.168.0.0/24”)

ContainsSubnet

Network contains subnet: field >> subnet

The subnet should be in CIDR notation

Fields

field: Field

The network field to check

subnet: String

The CIDR subnet to check for containment

ContainsIP

Network/range contains IP: field >> ip

The IP should be a single address (e.g., “192.168.1.1”)

Fields

field: Field

The network field to check

ip: String

The IP address to check for containment

IPRangeOverlap

IP ranges overlap: field && range

The range should be in CIDR notation

Fields

field: Field

The IP range field to check

range: String

The IP range to check for overlap

StrictlyContains(Field, Value)

JSONB strictly contains: field @> value

Checks if the JSONB field strictly contains the given value

AncestorOf

Ancestor of: field @> path

Checks if the ltree field is an ancestor of the given path

Fields

field: Field

The ltree field to check

path: String

The path to check ancestry against

DescendantOf

Descendant of: field <@ path

Checks if the ltree field is a descendant of the given path

Fields

field: Field

The ltree field to check

path: String

The path to check descendancy against

MatchesLquery

Matches lquery: field ~ lquery

Checks if the ltree field matches the given lquery pattern

Fields

field: Field

The ltree field to check

pattern: String

The lquery pattern to match against

MatchesLtxtquery

Matches ltxtquery: field @ ltxtquery

Checks if the ltree field matches the given ltxtquery pattern (Boolean query syntax)

Fields

field: Field

The ltree field to check

query: String

The ltxtquery pattern to match against (e.g., “Science & !Deprecated”)

MatchesAnyLquery

Matches any lquery: field ? array[lqueries]

Checks if the ltree field matches any of the given lquery patterns

Fields

field: Field

The ltree field to check

patterns: Vec<String>

Array of lquery patterns to match against

DepthEq

LTree depth equals: nlevel(field) = depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

DepthNeq

LTree depth not equals: nlevel(field) != depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

DepthGt

LTree depth greater than: nlevel(field) > depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

DepthGte

LTree depth greater than or equal: nlevel(field) >= depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

DepthLt

LTree depth less than: nlevel(field) < depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

DepthLte

LTree depth less than or equal: nlevel(field) <= depth

Fields

field: Field

The ltree field to check

depth: usize

The depth value to compare

Lca

Lowest common ancestor: lca(field, paths)

Checks if the ltree field equals the lowest common ancestor of the given paths

Fields

field: Field

The ltree field to check

paths: Vec<String>

The paths to find LCA of

DescendantOfId

Descendant of entity by ID: path <@ (SELECT path FROM t WHERE id = $1)

Resolves the ltree path from the entity’s UUID before performing the descendant comparison. The UUID value is the entity ID to resolve.

Fields

field: Field

The ltree field (or relationship field) to filter

id: String

The UUID of the entity whose path to resolve

AncestorOfId

Ancestor of entity by ID: path @> (SELECT path FROM t WHERE id = $1)

Resolves the ltree path from the entity’s UUID before performing the ancestor comparison. The UUID value is the entity ID to resolve.

Fields

field: Field

The ltree field (or relationship field) to filter

id: String

The UUID of the entity whose path to resolve

Implementations

impl WhereOperator

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

Get a human-readable name for this operator

pub fn validate(&self) -> Result<(), String>

Validate operator for basic correctness

Errors

Returns an error string if the field name is invalid or, for vector distance operators, the threshold is not a finite number.

Trait Implementations

impl Clone for WhereOperator

fn clone(&self) -> WhereOperator

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for WhereOperator

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

Formats the value using the given formatter.