1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
//! The storage side of a query: the COMPARISON types, and the crossing a filter makes to reach one.
//!
//! ```text
//! row VideoTrack ⇄ VideoTrackPostgres ⇄ INSERT / SELECT
//! filter VideoTrackFilter → VideoTrackPostgresComparison → WHERE "bitrate" = ?
//! (domain values) (storage values)
//! ```
//!
//! A filter is the client's vocabulary — one per entity, holding DOMAIN values, rendered as a
//! GraphQL input object. A comparison is the storage's — one per (entity × backend), holding
//! STORAGE values, lowered by binding. The crossing between them is where a value enters the
//! database, and it happens exactly once.
//!
//! # Why the two vocabularies are not one
//!
//! A filter is backend-NEUTRAL: `ScalarFilter<i64>` is the same type whichever database answers it,
//! which is why [`GraphqlFilter::is_empty`](crate::GraphqlFilter) can be asked without naming a
//! dialect. A comparison is backend-SPECIFIC by construction: `SqlScalarComparison<V, Db>` carries
//! its `Db` in its own type. That difference is structural rather than stylistic, and it is the
//! reason there is no neutral `DatabaseComparison` trait beside
//! [`GraphqlFilter`](crate::GraphqlFilter) — a comparison has no ambiguity for one to resolve.
//!
//! # The neutral pieces, and the family beside them
//!
//! - [`Backend`] — the storage backend a comparison renders for, owning the builder every
//! comparison of that backend threads and the refusal they can return.
//! - [`ComplexComparison<B>`] — the lowering itself: the builder passes THROUGH a comparison rather
//! than being written into, which is what lets one name two or more columns and nest without
//! bound.
//! - [`At`] / [`RecordAddress`] — WHERE a comparison is being applied: the column, and the row it
//! constrains. A leaf reads the column and ignores the row; a correlated predicate needs both,
//! and neither is in a filter. Carrying it here rather than at the crossing is what keeps
//! [`TryFromFilter`] taking a filter and nothing else.
//! - [`Path`] / [`Frame`] — the SEGMENTS naming that column, and the link a layer pushes to extend
//! them. A comparison occupying several columns pushes one frame per part rather than being
//! handed a name per column — so there is no pair to hand over in the wrong order, and the TOP
//! level is the empty path rather than a name nobody can supply.
//! - [`CompositeComparison<B>`] — that a comparison occupies more than one column, which a scalar
//! does not claim. It is what refuses `flatten` on a field whose name IS its column, and
//! [`ToFlattenedComparison<V, Db>`] is the blanket-implemented form of that requirement an expansion
//! can spell.
//! - [`CollapsibleComparison<B>`] — that a comparison over a ROW can hand back its constraint on
//! that row's own id, and only when the id is all it constrains. A relation over a to-one
//! reference renders that constraint on the FOREIGN KEY and skips its subquery entirely.
//! - [`ReferentialComparison<B>`] — that a comparison can SAY whether its constraint is a plain
//! equality or membership. It is the half of the law above that a generic implementor cannot read
//! for itself, and its absence is what refuses a collapse rather than silently declining one.
//! - [`ToDatabaseComparison<V, Db>`] — the type-level map from a filter KIND to the comparison it
//! crosses into. Keyed on the filter rather than on the storage type, because the OPERATOR SET
//! must survive the crossing: `TextFilter<String>` and `ScalarFilter<String>` share a storage type
//! and are not the same question.
//! - [`ToRelatedComparison<C, Db>`] — the same map for a RELATION position, whose parameter is the
//! far side's PREDICATE rather than a storage type. It carries no item bound — see its note for
//! the mutual-relation cycle one closes — and [`ToLoweredRelatedComparison<C, Db>`] is the
//! refinement a record's own lowering states and spends, carrying the rendering as METHODS so no
//! projection has to be named at a generic dialect.
//! - [`FromFilter<F>`] / [`TryFromFilter<F>`] — the crossing itself, shaped like [`From`]/[`TryFrom`]
//! and related by the same blanket.
//! - `RelationWidthError` / `RelationDepthError` — the two causes a relation predicate refuses for
//! on EVERY backend: an address of more than one column, and a nesting past the aliases minted for
//! it. The enums holding them are per family and the facts are not, so the payloads are here and
//! each family re-exports them. Behind the two backend gates together, since a build with no
//! backend has nothing that renders a relation.
//! - [`TextMatch`] — WHICH substring form a text match asks for, which is the question and not the
//! rendering: the three members are the same three on every backend, and what a family builds from
//! one is its own. It is here rather than inside a family for the reason the storage forms are in
//! `storage` — a gate belonging to one of them was making the other declare a copy.
//! - `sql` — the first comparison family, behind the `sqlx` feature.
//! - `mongo` — the second, behind the `mongo` feature, entering through its own [`Backend`] row and
//! changing nothing above it. Where the fit is loose rather than clean is recorded in that
//! module's own note and at [`Backend`]'s two answers it measured.
//!
//! # A family is a MODULE, and its items keep its segment
//!
//! `sql`'s vocabulary is addressed through it — `sql::SqlScalarComparison`, not a name lifted to
//! sit beside the neutral pieces. What that separates is the two audiences: the traits above are
//! implemented and named by hand, while a comparison kind, a clause state and a rendering helper
//! are written by an expansion, and one namespace holding both makes `WhereClause` look like a name
//! this crate offers. The few family items a PERSON does write — the join surfaces — are
//! re-exported at the crate root, where a human is already looking.
//!
//! The storage types a declaration spells are re-exported there too and are NOT a family's: a
//! big-endian blob and a temporal wrapper name no database, and keeping them inside `sql` gated them
//! on `sqlx` — so a `u64` field was declarable on SQLite and undeclarable on MongoDB for a reason
//! belonging to neither. They live in the crate's `storage` module, and each family writes its own
//! carrier row for them.
//!
//! [`GraphqlFilter`]: crate::GraphqlFilter
pub use Backend;
pub use ;
pub use ;
pub use ;
pub use ;
pub use TemporalStorage;
pub use TextMatch;