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
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
//! The MongoDB engine: the PACKAGE a query renders into, the DOCUMENT a write stores, what a stored
//! document answers a query with, and — where the driver is compiled in — the lane that runs either.
//!
//! # Two layers, and the lower one is a public escape hatch
//!
//! The lower layer is this module under the `mongo` feature: it builds a [`MongoPipeline`] — a
//! collection, the aggregation stages, and the collections those stages READ — and, through
//! [`MongoWrite`], the documents the four write commands take. It executes nothing. A caller holding
//! their own `mongodb::Database` can take either and run it however they like, which is what makes
//! the rendering usable without this crate owning the driver.
//!
//! The upper layer is [`lane`](self::lane) under the `mongodb` feature: it takes a database handle
//! once and runs the package, so the ordinary path writes no glue at all. The split is the same one
//! the SQL family makes between `comparison::sql` (render) and [`query::sql`](super::sql)
//! (execute) — except that there the driver arrives with the family root, and here it is a second
//! feature, because `mongodb` brings a whole tokio runtime with it and a build that only renders
//! must not pay for one. See the crate manifest's `mongodb` entry for the measurement.
//!
//! # The WRITE half is [`write`](self::write), and it answers the read half's four verbs
//!
//! `insert` / `upsert` / `delete` / `delete_where`, mirroring the SQL write lane's grammar seat for
//! seat — and shorter than it by three whole sections, because a record is ONE DOCUMENT here: no edge
//! statements, no provenance statements, no transaction bracket. That module's note carries the
//! argument, the embedded-array cascade among it.
//!
//! # The lane is ALWAYS an AGGREGATION, and `find` is not used at all
//!
//! Every lane renders a pipeline: a flat query is `[$match, $sort, $limit]` rather than a `find`
//! with a sort and a limit beside it. Two reasons, and the second is why it is a RULING rather than
//! a convenience:
//!
//! - **`$lookup` has no `find` spelling.** A relation predicate is a join, which MongoDB answers in
//! a pipeline and nowhere else — see
//! [`MongoRefComparison`](crate::comparison::mongo::MongoRefComparison), whose family answered a
//! blanket refusal until this lane gave the stage a position. A lane that spoke `find` for the flat
//! case and pipelines for the joined one would be two engines with two paging stories.
//! - **One shape means one place to be wrong.** The `$match` a flat query renders is the same
//! document the joined one renders, and the `$sort`/`$limit` after it are the same stages — so a
//! page's boundary behaviour is decided once whatever the filter turned out to be.
//!
//! What it costs is a `$sort` on a query that could have been a bare `find`, which the server plans
//! identically once the sort is index-covered — and the framework's page always writes an order
//! anyway, because a cursor is a position in one.
//!
//! # `id` on the wire, `_id` in the document
//!
//! A record's id is STORED as `_id`: it is the field MongoDB indexes uniquely without being asked,
//! and a document carrying both an `_id` the server minted and an `id` the declaration wrote would
//! be one row with two identities. The declaration and the wire face still say `id`, so the mapping
//! lives in exactly two places — the extraction, which reads `_id` into the row's id field, and the
//! FIELD-PATH renderer, which is where a filter, a sort and a keyset all reach a column name. See
//! [`write_field_path`](crate::comparison::mongo::write_field_path) for the renderer's half.
//!
//! # What is measured here, and what is not
//!
//! The tests beside this module assert on the PACKAGE, because building one is what this module
//! does: a pipeline is a `bson::Document` list, so a golden is an exact value rather than a string
//! comparison. Whether a page WALKS correctly is not visible in the pipeline — a keyset that skips
//! a row is a perfectly good aggregation that answers without an error — so that half is measured
//! against a real server and recorded where it was measured; see [`MongoKeyset`] for the walk this
//! lane inherits from the SQL family's, and [`lane`](self::lane) for the live posture.
// The DERIVED document's road through this module's two tables — public, because what names it is a
// `#[serde(with = "…")]` string an emitted row carries, and a path serde resolves in the DECLARER's
// crate has to be reachable from there.
//
// It rides `serde` on top of this module's own `mongo`, and the pair is the honest predicate: the
// functions read `MongoCarrier`/`MongoExtract`, which are bson's tier, and they are named by a
// derive, which is serde's. A build carrying one without the other has no emitted document that
// could name this module — the row derives serde's pair through the same shelf.
pub use ;
/// The BSON type-alias namer, crate-internal and reached by name rather than by widening the
/// private `extract` module it lives in — see [`alias`](extract::alias)'s own doc for the argument.
///
/// [`Count`](crate::Count) is not among the callers: its row lives IN `query::mongo::extract`
/// itself, beside `alias`, so its refusal already reaches the function through the module-private
/// `mismatch` helper and needs nothing re-exported.
///
/// # It carried `#[cfg(feature = "derive")]`, and the day that note predicted has ARRIVED
///
/// The gate followed the language family, which rides `derive` — *a build with `mongo` and no
/// `derive` has no builtin outside this module implementing [`MongoExtract`] at all* — and it said
/// what would move it: *a future non-derive builtin that joins the vocabulary from outside
/// `query::mongo` widens this gate to match*.
///
/// One landed and the gate did not move with it. `primitives::time_range`'s module is UNGATED and its
/// [`MongoExtract`] row is `#[cfg(feature = "mongo")]`, so a build carrying `mongo` and not `derive`
/// names a function that is configured out — `E0425`, in the crate's own source, which is exactly
/// what `ci/test-matrix.sh`'s `runtime,mongo` and `runtime,mongodb` lanes compile. So the gate is
/// `mongo`'s now, which is unconditional inside this module: the predicate is *does this build have
/// the backend*, and every party that can implement the vocabulary is under it.
pub use alias;
pub use ;
pub use MongoKeyset;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
pub use ;
use ;
use CrossingError;
use crate::;
/// One MongoDB document, as the engine queries the record it stores.
///
/// # The binding is on the ROW, exactly as [`SqlQuery`](super::sql::SqlQuery)'s is
///
/// A declaration storing a record in MongoDB and in SQLite emits two row types, and everything a
/// query needs that varies — the field names, the stored types, the collection — varies with
/// exactly that. So this is implemented on the emitted document and names the record it stores.
///
/// What it does NOT carry is a dialect parameter. There is one MongoDB, one wire format and one
/// query vocabulary, which is the same absence [`comparison::mongo`](crate::comparison::mongo)
/// records one layer down: where the SQL family has a table of (kind × dialect) this family has a
/// list of kinds, and where a SQL query binding is generic in `Db` this one is a plain impl.
/// A document that can be ORDERED, and therefore paged.
///
/// A second trait for [`SqlOrdering`](super::sql::SqlOrdering)'s reason, and it buys the same
/// thing: a record with no order-by type has nothing to write a term with, so `.order(…)` is a
/// method that does not resolve rather than a refusal at runtime.
///
/// # Four functions, and one list drives every reading of a page
///
/// [`complete`](Self::complete) turns a client's written terms into the total order the page runs
/// in; [`term`](Self::term) renders one of those into the [`OrderTerm`] this database spells;
/// [`subjects`](Self::subjects) says which of them read ANOTHER COLLECTION and how; and
/// [`value`](Self::value) reads the document at that same term. So the `$sort`, the keyset
/// `$match`, the stages that materialize a nested value and the cursor are four readings of ONE
/// list — [`SqlOrdering`](super::sql::SqlOrdering)'s own arrangement, and it keeps the same thing
/// from going wrong.
/// The `$eq`-shaped operand a keyset arm and an address predicate both bind — one function so that
/// a stored value reaches a filter document by exactly one route.
///
/// [`None`] is `null`, which is MongoDB's own conflation of *written as null* and *never written*:
/// `{f: {$eq: null}}` matches both. The framework does not narrow it, because the query language
/// offers nothing to narrow it WITH — `$type: "null"` would separate them and would then make a
/// keyset's equality leg disagree with its own `$sort`, which reads a missing field as `null`.
///
/// The encoding itself is [`MongoCarrier`]'s own row over [`Option`] rather than a match written
/// here, so the value a keyset compares against and the value a stored document holds cannot be two
/// answers. This function is what remains of the shape: an `Option<&V>` where the row takes
/// `&Option<V>`, which is the borrow a keyset already holds.