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
//! The WRITE half: the verbs a record is stored and REMOVED with on MongoDB, and the DOCUMENT each
//! of them is.
//!
//! ```text
//! insert insertOne(<the whole document>)
//!
//! upsert replaceOne({_id: …}, <the whole document>, {upsert: true})
//!
//! delete deleteOne({_id: {$eq: …}})
//!
//! delete_where deleteMany(<the lowered filter>)
//! ```
//!
//! # It is [`query::sql::write`](crate::query::sql)'s grammar, seat for seat
//!
//! Four verbs and the same four meanings: [`insert`](super::insert) is the plain store and a taken
//! address is the SERVER's own refusal; [`upsert`](super::upsert) is the keyed replace at that same
//! address; [`delete`](super::delete) is the removal at an ID and answers a yes-or-no;
//! [`delete_where`](super::delete_where) is the removal over a PREDICATE and answers a count. The
//! removal half mirrors the READ half rather than the store half, for the reason the SQL lane
//! records: a store verb is handed a record and needs no way to say which documents it is about, and
//! a removal does — so it borrows the two shapes a caller already knows one in, `get`'s id and
//! `find`'s filter.
//!
//! # THREE of that lane's paragraphs have nothing to answer here, and the reason is one fact
//!
//! A record is ONE DOCUMENT on this backend. `edge_collections` answers `false` for MongoDB and the
//! front end refuses the `edge` word in a `mongo(…)` block outright — *a document holds its own
//! array, and there is no second table* — so a collection column is a BSON array FIELD of the
//! document itself, in the same document as every scalar beside it. That deletes three whole
//! sections of the SQL register at once:
//!
//! - **No edge statements.** There is no `DELETE FROM <edge>` and no `INSERT INTO <edge>`, no
//! ordinal to compute and no bind ceiling to be refused past, because there are no element rows.
//! - **No provenance statements.** `SqlWrite::SIDES` has no counterpart: a split-layout ancestry is a
//! second TABLE, and a document that would hold one holds it inline like everything else.
//! - **No transaction bracket.** The SQL lane opens one because *the SHAPE decides the bracket* and
//! a record spanning several tables is several statements. Here every verb is ONE command against
//! ONE collection, and a single command is atomic by the server's own law — so a framework-begun
//! transaction would be a bracket with nothing to hold together. A caller who wants several
//! WRITES to see one state passes a `mongodb::ClientSession`, exactly as the read lane's `_in`
//! twins already take one, and this lane begins nothing and commits nothing.
//!
//! # …and it is what makes `upsert` the cascade
//!
//! The SQL lane's replace is a sequence: the keyed replace on the parent, then every collection's
//! rows removed and rewritten, then every provenance table cleared — several statements, one bracket,
//! and a whole note about what an edge set left un-deleted would silently hold. `replace_one` with
//! `upsert: true` replaces the WHOLE DOCUMENT, and a document's embedded arrays are part of it. So
//! the *collection that arrives shorter comes back shorter* rule is not enforced here; it is the
//! command's own semantics, and there is nothing between the two halves for a failure to land in.
//!
//! What that costs is stated rather than hidden: the replacement is total, so a field a WRITER did
//! not put in the document is a field the stored document no longer has. That is the same reading
//! `upsert` already has one backend over — *the value handed over is the whole of it* — and it is why
//! a PARTIAL document (a `mongo` block that narrows the record's columns) replaces at its own width
//! and never merges into what was stored.
//!
//! # …and what the cascade argument is NOT yet exercised on, which is a gap this half INHERITS
//!
//! A collection column has no storage form on this backend today, and the reason is a table row
//! rather than anything here: [`MongoExtract`](super::MongoExtract) has no `Vec<T>` row and
//! [`MongoCarrier`] has none either — only `Vec<u8>`, which is a `binData` BLOB rather than an array.
//! The comparison layer answers a collection perfectly well (that is
//! [`MongoListComparison`](crate::comparison::mongo::MongoListComparison)'s whole family, over a
//! native BSON array), and a stored one is a document field this write would send and that read would
//! not take back.
//!
//! So the sentence above is the COMMAND's semantics and the storage layout's, both of which hold
//! whatever a column may be: `replace_one` swaps the document, arrays included, and there is no second
//! table for a cascade to reach. What is not yet reachable is a declaration that HAS such a column,
//! and widening those two tables is the read half's change rather than this one's — the write half
//! stores exactly what the read half can give back, which is the gate
//! [`MongoWrite`]'s supertrait already states.
//!
//! # The two layers are the READ half's two layers
//!
//! Everything in this file is a VALUE and runs nothing: [`MongoWrite`] says how a record becomes the
//! document that stores it, and [`stored`], [`replacement`], [`removal`] and [`removal_where`] build
//! exactly the documents the four commands take. It compiles under `mongo` alone, so a caller holding
//! their own `mongodb::Collection` can take any of them and issue the command themselves. The lane
//! that issues it rides `mongodb` — see [`lane`](super::lane), and the module note above it for why
//! the driver is a second feature.
//!
//! # The DOCUMENT is built through the carrier vocabulary, and NOT through serde
//!
//! An emitted document derives `Serialize`, and building the stored document with it was measured and
//! refused — for [`from_document`](super::MongoQuery::from_document)'s reason read the other way.
//! serde and this crate's storage vocabulary DISAGREE about BSON: `Vec<u8>` serializes as an array of
//! integers where [`MongoCarrier`] writes a `binData`, which is exactly what
//! [`MongoExtract`](super::MongoExtract) reads back — so a serde-written document would not survive
//! its own extraction, and the failure would be a typed refusal on the READ of a document the WRITE
//! reported success for.
//!
//! [`MongoCarrier`] is [`MongoExtract`] read backwards, row for row, round-tripped by the tests
//! beside them. So the encode is the decode's twin under the same table, which is the whole of what
//! makes a stored document readable: `from_document` reads field by field under the names this
//! database spells, and [`MongoWrite::document`] writes field by field under those same names.
//!
//! # What is measured here, and what is not
//!
//! The same posture the read lane records, and for the same measured reason: `ci/test-matrix.sh`
//! provisions no service, and there is no mongod in it — so what is tested is the DOCUMENT each verb
//! would send, which is a value and is the whole of what this file decides. The tests beside it
//! implement [`MongoWrite`] by hand through nothing but its public items, which is the discipline the
//! SQL write lane's own fixture keeps: a member only an emitter could have supplied would not compile
//! there.
//!
//! What a live walk still owes is one row, and it is the server's rather than this lane's: that a
//! second `insert` at a stored `_id` is refused with duplicate-key `11000` and that `replace_one`
//! with `upsert: true` at the same address is not. Both are documented server behaviour rather than
//! anything this file chooses, and neither is reachable without a mongod.
use Document;
use ;
use crate::;
/// One MongoDB document, as the engine WRITES it.
///
/// # A second trait over [`MongoQuery`], which is the split [`SqlWrite`] already makes
///
/// Everything a write shares with a query — the collection, the address, the id's crossing, which
/// record this document stores — is stated once, on the trait that already holds them, so a lane
/// that stores a document and a lane that reads one cannot disagree about which collection or which
/// `_id`. What is here is the two things only a write needs: the crossing INTO the document, and the
/// document itself.
///
/// It is also the answer to a name that would otherwise be ambiguous. `ADDRESS` is a const, and a
/// document carrying two of them — one from a read binding and one from a write binding — makes
/// `Row::ADDRESS` `E0034` at every use site, in an expansion nobody can edit. The supertrait is what
/// makes there be one.
///
/// The supertrait also fixes what a write-only document would be, and the answer today is that there
/// is none: a document that cannot be raised back into its record has no [`MongoQuery`] impl, so it
/// has no write lane either. That is the read half's own gate read one layer down rather than a new
/// one.
///
/// # Every field goes through the DECLARED crossing
///
/// [`row`](Self::row) is the only way in and [`document`](Self::document) reads what it produced, so a
/// declaration's write legs are on the path of every value this lane sends. There is no ad-hoc
/// conversion beside them and nowhere to put one: the engine holds a document and cannot name a
/// record's field.
///
/// [`SqlWrite`]: crate::query::sql::SqlWrite
/// The document an [`insert`](super::insert) stores: the record, crossed.
///
/// # Errors
///
/// Whatever the declaration's own write conversions refuse with — see [`MongoWrite::row`].
/// The two documents an [`upsert`](super::upsert) sends: the address it replaces AT, and the whole
/// document it replaces it WITH.
///
/// The filter is the same `{_id: {$eq: …}}` a [`get`](super::get) and a [`delete`](super::delete)
/// name a document by — one spelling, minted by [`identity`] — so the three verbs cannot come to
/// disagree about what an address is. The id is read off the RECORD, which is where every other
/// address on this backend is read from and what [`MongoQuery::id`] takes.
///
/// # Errors
///
/// As [`stored`], plus an id that will not cross into this database's stored value.
/// The filter a [`delete`](super::delete) removes one document by.
///
/// [`identity`]'s spelling and nothing added: the `_id` is unique by the server's own construction, so
/// the predicate names at most one document by the storage engine's law and the verb answers a
/// yes-or-no rather than a count.
///
/// Bounded by [`MongoQuery`] where the store verbs take [`MongoWrite`], and the narrower bound is the
/// honest one: an address is a READ-side fact — the same one [`address`](super::address) is built
/// from — so nothing here needs a document to know how to be written. The LANE still asks for the
/// write binding, which is where *may this row be stored at all* belongs.
///
/// # Errors
///
/// Whatever the declaration's own id conversion refuses with — see [`MongoQuery::id`].
/// The filter a [`delete_where`](super::delete_where) removes documents by — lowered, and refused
/// where it names everything or reaches another collection.
///
/// # The unscoped refusal is TWO tiers, exactly as the SQL lane's is
///
/// The first asks about the VALUE: a comparison with no operator set anywhere answers
/// [`is_empty`](ComplexComparison::is_empty), and it is asked before anything lowers so that the
/// cheapest refusal is also the first — and so that the sentence is about the COLLECTION rather than
/// about whichever stage noticed.
///
/// The second asks about the RENDERING, and it is not the first one repeated. `is_empty` is a count
/// an implementor supplies and the filter document is text an implementor writes; a comparison whose
/// count OVER-reports passes the first tier and is caught only here. What it would otherwise produce
/// is `deleteMany({})` — which is every document in the collection, reported as success. So the second
/// tier is a check on the trait's own contract, and it is where the SQL lane's *rendered zero
/// conjuncts* check sits one backend over.
///
/// # The join refusal is this backend's third, and it is not optional
///
/// See [`MongoWriteError::Joined`]. A predicate that lowered to `$lookup` stages has said something a
/// delete command cannot carry, and sending the `$match` without them would remove a SUPERSET of what
/// the filter named.
///
/// # Errors
///
/// A lowering refusal carried verbatim, [`MongoWriteError::Joined`] for a filter that needs a join,
/// and [`MongoWriteError::Unscoped`] for one that names no document.