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
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
//! The nullable wrapper: [`MongoNullable`].
use Bson;
use ;
use crate::;
/// A NULLABLE column's comparison: `C`'s operators, plus the null test — which exists here and in no
/// other comparison type.
///
/// One wrapper rather than a nullable twin per kind, mirroring [`Nullable`] exactly, and it is that
/// mirroring that carries the guarantee across: a `NOT NULL` column's filter has no null test, so
/// its comparison has nowhere to put one, so asking a `NOT NULL` column whether it is null is a
/// query that does not typecheck rather than one that matches nothing.
///
/// # The null test is TWO states, and MongoDB's own convention is what makes it two
///
/// A BSON document is the set of fields that were written, so a field can be missing in a way a
/// table row's column cannot. That does not make the question three-valued, because the server
/// reads the two the same way: `{v: null}` matches the document holding an explicit null AND the
/// document with no `v` at all, and the query vocabulary follows that reading throughout. Missing
/// IS null here, by the store's own convention rather than by this crate's arrangement.
///
/// The SQL family conflates the same pair from the other side, which is why one filter means one
/// thing across both backends: `ALTER TABLE … ADD COLUMN` backfills NULL, so a row written before
/// the column existed is indistinguishable from a row that stored NULL into it. Neither family can
/// tell a caller which of the two happened, and neither is asked to.
///
/// What IS three-way is the input face — not asked, asked for null, asked for a value — and
/// [`Nullable`] already carries it as `Option<bool>`, where `None` is *not asked*. That is a fact
/// about the query rather than about the cell, and it is the layer above this one.
///
/// # What each state renders
///
/// | `null` | key | matches |
/// |---|---|---|
/// | `Some(true)` | `{$eq: null}` | the field is null, or there is no such field |
/// | `Some(false)` | `{$ne: null}` | the field is there and is not null |
/// | `None` | *(nothing)* | the question was not asked |
///
/// Both are the server's own spellings, and neither takes an `$exists` beside it. Measured on
/// MongoDB 8.2.12 over the nine-document corpus in this module's tests, `{v: {$ne: null}}` and
/// `{v: {$exists: true, $ne: null}}` return the same five documents — so the presence test is
/// redundant rather than load-bearing, and writing it would state a distinction the convention above
/// says this layer does not draw.
///
/// The two keys PARTITION the corpus: every one of the nine documents answers exactly one of them.
/// That is the property a two-state question is supposed to have, and it is what the tests check
/// rather than assume.
///
/// # An ARRAY holding a null MEMBER answers the null test
///
/// MongoDB applies a field operator to an array's members as well as to the array itself, so a cell
/// holding `[1, null, 3]` is returned by `{$eq: null}` and excluded by `{$ne: null}` — measured,
/// both of the corpus' arrays with a null member answer that way, where each cell plainly holds a
/// value.
///
/// That is the engine's reading of a stored array rather than anything this wrapper chooses, and
/// nothing this crate declares reaches it. A stored array is a COLLECTION column; a collection's
/// element type needs a [`DefaultVecMarker`](crate::DefaultVecMarker) row to be a `Vec`'s default
/// reading and `Option<T>` has none; and no shipped [`MongoCarrier`](super::MongoCarrier) row
/// produces `Bson::Null` or `Bson::Array` at all — the widest is `Vec<u8>`, which is `BinData`. A
/// downstream row that stored one would put its column's null test under this reading — the same
/// standing the array-of-arrays contamination [`MongoListComparison`](super::MongoListComparison)
/// records has, and the same standing the `$`-in-a-field-name hazard has: stated, and the row
/// author's.
/// Why a [`Nullable`] filter's operands did not become MongoDB values.
///
/// [`NullableCrossingError`](crate::comparison::sql::NullableCrossingError)'s twin, kept apart for
/// the reason every crossing error in this family is: which refusals a store can raise is that
/// store's answer, and one type spanning both would publish the union to callers of each.
///
/// `X` DEFAULTS to `E`, as the SQL twin's does.
/// The nullable filter crosses into the nullable comparison over whatever its inner kind crosses
/// into — one impl for every kind, present and future.
///
/// The `Option` lands HERE and nowhere below it, for the reason
/// [`SqlNullable`](crate::comparison::sql::SqlNullable)'s own row gives at length: the storage type
/// this impl is asked for is the COLUMN's, so a nullable column names `Option<V>` and `V` is what
/// the inner comparison is built over. Without it, `eq: Some(None)` and `null: Some(true)` would be
/// two spellings of one question — and here the first of them is the wrong one twice over, since
/// `{field: {$eq: null}}` is this wrapper's key rather than an operand's.
///
/// It does not overlap the SQL family's row for the same self type, for the coherence reason
/// [`MongoScalarComparison`](super::MongoScalarComparison)'s row records: that one is keyed on
/// `Db: sqlx::Database`, which is FOREIGN, and [`Mongo`] is local and has no such impl. This row
/// naming [`Mongo`] concretely is the whole of what keeps the two apart.
/// The empty comparison of an empty inner one — bounded on `C`, unlike the flat kinds' unbounded
/// [`Default`], because this wrapper OWNS an inner comparison and has no all-`None` state to build
/// without one. [`Nullable`] carries the same bound on the filter side for the same reason.
/// The crossing composes through `C`'s, and the error is `C`'s too — a null test never fails, so the
/// wrapper adds no way for the crossing to.
/// The inner comparison's keys, then the null test's — merged into the same field's operator
/// document, which is what keeps the wrapper from opening a second key for a field that already has
/// one.
///
/// # The two keys are SHARED with the kinds, and the fold is what keeps them apart
///
/// `$eq` and `$ne` are the two most-written keys in this family: the scalar kind spells its own `eq`
/// and `ne` with them, and a collection kind writes `$eq` for `has_element` and for a
/// whole-collection equality. A comparison asking one of those AND the null test is one key twice,
/// and [`MongoConjunction::merge`] folds the second into a top-level `$and` rather than over the
/// first.
///
/// The fold is an INTERSECTION rather than a last-writer-wins, and the corpus separates the three
/// possible readings: a nullable list asking `has_element: 1` with `null: true` renders
/// `{v: {$eq: 1}, $and: [{v: {$eq: null}}]}`, which returns ONE document — where keeping only the
/// first key returns two and keeping only the second returns four.
///
/// [`MongoConjunction::merge`]: super::MongoConjunction::merge
///
/// # The null test composes with non-emptiness rather than colliding with it
///
/// A collection's `any` slot with no operator set renders `{$elemMatch: {$exists: true}}` — *this
/// field is a non-empty array* — and the null test renders beside it under its own key. `$exists` is
/// written INSIDE the element scope and never at the field, so the two documents have nothing to
/// fold. Measured, the pair a nullable list renders for `null: false` returns exactly the one
/// non-empty array whose members are all values.
///
/// # The whole address passes DOWN untouched
///
/// No frame is pushed, because this wrapper is the same field of the same document as its inner —
/// the two conjuncts name one key and the merge is what renders it once.