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
//! The compound key's membership: [`SqlKeyIn`].
use ;
use ;
use crate::;
/// A set of COMPOUND KEYS a row's key must be one of, lowered as the row-value `IN` — one predicate
/// naming `N` columns at once.
///
/// ```text
/// ("media_id", "segment_id") IN ((?, ?), (?, ?))
/// ```
///
/// # Only `eq` decomposes into a conjunction
///
/// Every other kind in this family lowers into an AND accumulator and decomposes along its columns,
/// and for equality that is exact: `(a, b) = (1, 10)` IS `a = 1 AND b = 10`. Membership does not
/// decompose, and the spelling that looks as though it does asks a different question:
///
/// ```text
/// -- the key set {(1, 10), (2, 20)}
/// WHERE ("a", "b") IN ((?, ?), (?, ?)) the keys
/// WHERE "a" IN (?, ?) AND "b" IN (?, ?) the CARTESIAN PRODUCT — also (1, 20) and (2, 10)
/// ```
///
/// The second is well-formed SQL, binds the same four operands, and returns rows nobody asked for.
/// Nothing in the rendered text or the bind count separates the two, which is why this kind exists
/// as a type rather than as a rule someone follows.
///
/// The disjunctive spelling — `("a" = ? AND "b" = ?) OR (…)` — is not an escape. **Measured on
/// SQLite 3.51: it is refused from 999 keys**, because each `OR` is another level of a parse tree
/// whose depth ceiling is 1000. The row-value list is FLAT and parses at twenty thousand.
///
/// # It is CONSTRUCTED, not crossed
///
/// Every other kind in this family is the storage-side twin of a client's filter and arrives through
/// [`TryFromFilter`](crate::TryFromFilter). This one has no filter twin, because a key set is not
/// something a client writes: it is the product of a relation collapse, or the second leg of
/// `search → keys → hydrate`, where a fulltext or vector index returns keys and the `persist` store is
/// filtered by them. So the only way in is [`new`](Self::new), and there is no crossing to declare a
/// converter for.
///
/// # `N` is the key's width, and it is the type's
///
/// A key set is `k` keys of `N` columns, held as `[[V; N]]` — so a key of the wrong width is not a
/// value this type can hold, and there is no arity to check at render time. `N = 0` is refused
/// where it is written: a key names at least one column.
///
/// `N = 1` renders `("k") IN ((?), (?))`, which is the general spelling degenerating rather than a
/// case with its own branch: a one-element parenthesised list is the element in all three dialects,
/// measured, so it means exactly what a plain `IN` would.
///
/// The `N` PART NAMES arrive with the key set and the ADDRESS arrives at
/// [`apply`](ComplexComparison::apply), which is the composite convention exactly: one frame is
/// pushed per column. A key applied at `key` over `["media", "segment"]` addresses `key_media` and
/// `key_segment`, and nothing here invents either half.
///
/// At the TOP LEVEL nothing was pushed above them, so the parts are the whole names — which is what
/// the block above renders and what this kind is actually for: a key set collapsed out of a
/// relation names the ROW's own key columns, not columns beneath a field. Under a single-name
/// address that spelling was unreachable, since every application had to be handed a name and every
/// name prefixed all `N` of them.
///
/// # One `V`, and what that means for a key whose columns are stored differently
///
/// Every column of the key binds through the same [`Carrier`] row, as every other kind in this
/// family binds through one. A key whose columns have DIFFERENT storage types is therefore not
/// expressible here yet; it needs a carrier over a heterogeneous tuple, which is a seam rather than
/// a line — and nothing has asked for one.
///
/// # There is no negated twin
///
/// `NOT IN` over a row value is one expression and would render, but it is not what the collapse
/// this kind serves produces, and its three-valued behaviour over a key column that admits `NULL`
/// is a different question from the positive form's. It arrives when something asks, with its own
/// measurement.
/// ONE impl for every dialect, and the row-value `IN` is uniform in both of the ways a lowering can
/// differ — **measured**, on SQLite 3.51.0, PostgreSQL 16.14 and MySQL 8.4.10:
///
/// - **The SQL is identical.** `(a, b) IN ((?, ?), (?, ?))` parses and answers the same question in
/// all three, including with each engine's own placeholder syntax composed inside the nested tuple
/// list — `?` on SQLite and MySQL, `$1, $2, …` on Postgres. SQLite needs neither its `VALUES` form
/// nor a subquery for it.
/// - **The bounds are identical.** `V: Carrier<Db>` is the whole requirement, exactly as it is for
/// [`SqlScalarComparison`](super::SqlScalarComparison).
///
/// What is NOT uniform is the ceiling, and it rides as a bound stating a number rather than as three
/// concrete impls — the arrangement [`QuoteIdent`](super::QuoteIdent) already has one level down,
/// and for the same reason: the spelling is one everywhere and the constant is not.
///
/// # Why this kind has a ceiling where [`push_in`](super::push_in) deliberately has none
///
/// The multiplication. A single column's `IN` costs one bind per element, so the number a caller
/// passes IS the number that reaches the limit; a compound key's costs `k × N`, and `N` is a
/// property of the KEY rather than of the call. A caller under any single-column budget can be five
/// or forty times over this one without anything in its own arithmetic saying so.
///
/// And past the ceiling there is exactly one right answer, which is to SPLIT the key set into
/// batches whose union is the query. That is not something this layer can do quietly: it renders one
/// predicate into one accumulator, and a chunk is a different statement. So the refusal names the
/// three numbers a caller needs to batch by, and batching stays where the rest of the predicate is.
///
/// # What the ceiling is, per dialect
///
/// It is the BIND count, in all three, and it is checked before the conjunct opens so that a refusal
/// leaves the accumulator exactly as it was found.
///
/// | dialect | ceiling | why that one governs |
/// |---|---|---|
/// | SQLite | 32766 | `SQLITE_MAX_VARIABLE_NUMBER`, the default since 3.32 and the value the amalgamation sqlx bundles carries. The parse-depth ceiling of 1000 that stops the disjunctive spelling does NOT reach this one — the row-value list is flat, measured to twenty thousand keys |
/// | Postgres | 65535 | the whole range of the extended protocol's parameter count, which sqlx refuses past rather than truncating |
/// | MySQL | 65535 | the same range, refused by the server as *prepared statement contains too many placeholders* |
///
/// A softer limit sits under Postgres's and is deliberately not encoded here: its parser recurses
/// over the row-value list, so `max_stack_depth` — a server setting, 2MB by default — refuses a
/// two-column key set somewhere between seven and eight thousand keys. It is loud, it is
/// configuration, and a constant here would be this crate guessing at someone's `postgresql.conf`.