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
use std::collections::HashMap;
use qql_core::ast::Stmt;
use qql_core::error::QqlError;
use qql_plan::{PlannedOperation, plan};
use crate::executor::response::{BackendResponse, ExecData, score_f64};
use crate::executor::{ExecResponse, Executor, OnError, SearchHit};
impl Executor {
/// Run `future` under the configured [`request_timeout`](Executor::request_timeout).
///
/// Every execution entry point funnels through this so the timeout cannot
/// be bypassed by one path (e.g. prepared statements or `upsert_many`).
pub(crate) async fn with_timeout<T>(
&self,
future: impl std::future::Future<Output = Result<T, QqlError>>,
) -> Result<T, QqlError> {
if let Some(secs) = self.request_timeout() {
match tokio::time::timeout(std::time::Duration::from_secs(secs), future).await {
Ok(res) => res,
Err(_) => Err(QqlError::transport(
"QQL-TIMEOUT",
format!("operation timed out after {secs}s"),
None,
)),
}
} else {
future.await
}
}
/// Execute one parsed statement under the configured timeout, returning a
/// single response.
pub async fn execute_node(&self, stmt: Stmt) -> Result<ExecResponse, QqlError> {
self.ensure_open()?;
self.with_timeout(self.execute_node_inner(stmt)).await
}
async fn execute_node_inner(&self, stmt: Stmt) -> Result<ExecResponse, QqlError> {
let prepared = self.prepare_statement(stmt).await?;
let planned = plan(&prepared)?;
self.dispatch_planned(&planned).await
}
/// Dispatch a planned operation — gRPC goes direct, REST goes through Route.
pub(crate) async fn dispatch_planned(
&self,
op: &PlannedOperation,
) -> Result<ExecResponse, QqlError> {
// Client-side pair scorer: never a single Qdrant route.
if let PlannedOperation::CrossRerank {
collection: _,
query,
model,
field,
limit,
offset,
candidates,
} = op
{
return self
.execute_cross_rerank(query, model, field, *limit, *offset, candidates)
.await;
}
// Explicit BATCH blocks run members as one forced group. The single
// response path summarizes; per-member responses belong to the script
// path (`execute_batch_nodes`).
if matches!(op, PlannedOperation::Batch { .. }) {
let mut results = Vec::new();
self.execute_batch_op(op, OnError::Stop, &mut results)
.await?;
let total = results.len();
let ok_count = results.iter().filter(|r| r.ok).count();
return Ok(ExecResponse {
ok: ok_count == total,
operation: "BATCH".to_string(),
message: format!("Batch: {ok_count}/{total} operations ok"),
data: None,
telemetry: None,
});
}
let result = self.dispatch_raw(op).await?;
Self::normalize_planned(op, result)
}
/// Raw backend round-trip for one planned operation plus post-write
/// schema-cache invalidation. The backend answers typed
/// ([`QdrantOps::execute_planned`](crate::client::QdrantOps::execute_planned));
/// normalization is the executor's separate, pure step.
pub(crate) async fn dispatch_raw(
&self,
op: &PlannedOperation,
) -> Result<BackendResponse, QqlError> {
let response = self.client.execute_planned(op).await?;
match op {
PlannedOperation::CreateCollection { collection, .. }
| PlannedOperation::UpdateCollection { collection, .. }
| PlannedOperation::DropCollection { collection }
| PlannedOperation::CreateIndex { collection, .. }
| PlannedOperation::DropIndex { collection, .. } => {
self.invalidate_collection_schema(collection).await;
}
_ => {}
}
Ok(response)
}
/// Decode + normalize a typed backend response into an `ExecResponse`.
/// Pure (no I/O): shared implementation lives in
/// [`super::normalize::normalize_planned`](crate::executor::normalize::normalize_planned);
/// this wrapper keeps existing call sites (`dispatch_planned`,
/// `explain_analyze`, batch retries, tests) compiling unchanged.
pub(crate) fn normalize_planned(
op: &PlannedOperation,
response: BackendResponse,
) -> Result<ExecResponse, QqlError> {
super::normalize::normalize_planned(op, response)
}
/// Run candidate ANN stages, score (query, doc_text) with a cross-encoder, reorder.
async fn execute_cross_rerank(
&self,
query: &str,
model: &str,
field: &str,
limit: u64,
offset: u64,
candidates: &[(String, qql_plan::QueryRequest)],
) -> Result<ExecResponse, QqlError> {
let embedder = self.embedder.as_ref().ok_or_else(|| {
QqlError::execution(
"QQL-RERANK-CROSS",
"CROSS RERANK requires a configured embedder with pair scoring \
(rerank_endpoint / edge reranker_model)",
None,
)
})?;
// Deduplicate candidates by (collection, id) without cloning
// collection names per hit: hits live in one Vec, `seen` maps to
// indices, and names resolve once at materialization.
let mut hits: Vec<SearchHit> = Vec::new();
let mut hit_coll: Vec<usize> = Vec::new();
let mut seen: HashMap<(usize, qql_plan::PlanPointId), usize> = HashMap::new();
for (ci, (collection, request)) in candidates.iter().enumerate() {
let op = PlannedOperation::Query {
collection: collection.clone(),
request: request.clone(),
};
let response = self.dispatch_raw(&op).await?;
let batch = match response.data {
ExecData::Hits(hits) => hits,
// Candidates are always planned queries, so any other shape
// is a backend contract break — fail closed instead of
// silently scoring zero documents.
_ => {
return Err(QqlError::backend(
"QQL-BACKEND-ENVELOPE",
format!(
"CROSS RERANK candidate query on '{collection}' returned a non-hits response"
),
None,
));
}
};
for hit in batch {
// `insert` needs an owned key: one id clone per hit (the
// per-hit collection clone is gone).
if seen.insert((ci, hit.id.clone()), hits.len()).is_none() {
hit_coll.push(ci);
hits.push(hit);
}
}
}
if hits.is_empty() {
return Ok(ExecResponse {
ok: true,
operation: "CROSS_RERANK".into(),
message: "Found 0 hits".into(),
data: Some(ExecData::Hits(Vec::new())),
// Client-side scoring over candidate envelopes: no single
// server timing to attribute.
telemetry: None,
});
}
// Deterministic pre-order (collection, id) over indices: ties in
// rerank scores keep this order through the stable index sort below.
let mut order: Vec<usize> = (0..hits.len()).collect();
order.sort_by(|&a, &b| {
candidates[hit_coll[a]]
.0
.cmp(&candidates[hit_coll[b]].0)
.then_with(|| hits[a].id.cmp(&hits[b].id))
});
// Borrow rerank texts out of the hits; only surviving documents pay
// for owned Strings at the `&[String]` trait boundary below.
let mut doc_idx: Vec<usize> = Vec::with_capacity(order.len());
let mut doc_refs: Vec<&str> = Vec::with_capacity(order.len());
for &i in &order {
// The rerank field always comes from the payload: hits no longer
// carry a denormalized `text` mirror.
let text = hits[i]
.payload
.as_ref()
.and_then(|p| p.get(field))
.and_then(|v| v.as_str())
.unwrap_or("");
if text.is_empty() {
continue;
}
doc_idx.push(i);
doc_refs.push(text);
}
if doc_refs.is_empty() {
return Err(QqlError::execution(
"QQL-RERANK-CROSS-FIELD",
format!(
"CROSS RERANK found candidates but none had non-empty payload field '{field}'. \
Ensure UPSERT stores text on that field and PREFETCH returns WITH PAYLOAD."
),
None,
));
}
let docs: Vec<String> = doc_refs.iter().map(|s| s.to_string()).collect();
let scores = embedder.rerank_pairs(query, &docs, model).await?;
if scores.len() != doc_refs.len() {
return Err(QqlError::execution(
"QQL-RERANK-CROSS",
format!(
"rerank_pairs returned {} scores for {} documents",
scores.len(),
doc_refs.len()
),
None,
));
}
// Rank on the stored rounded value: `ranked` holds the f64 that lands
// on the hit, so output order always matches the visible scores
// (sorting the raw f32 pairs could disagree with the rounded values
// on near-ties). Losers are never cloned — paginate the index run
// and materialize only the output slice below.
let mut ranked: Vec<(f64, usize)> = scores
.into_iter()
.enumerate()
.map(|(k, s)| (score_f64(s), k))
.collect();
// NaN sorts last, by explicit choice: cross-encoder scores should
// never be NaN, but `partial_cmp` leaves NaN unordered against
// everything, so the old `unwrap_or(Equal)` pinned each NaN at its
// arrival slot and could surface it mid-ranking. Sinking NaNs keeps
// the ranked prefix meaningful; the stable sort preserves arrival
// order among NaNs (and among ties).
ranked.sort_by(|a, b| match (a.0.is_nan(), b.0.is_nan()) {
(true, true) => std::cmp::Ordering::Equal,
(true, false) => std::cmp::Ordering::Greater,
(false, true) => std::cmp::Ordering::Less,
(false, false) => b.0.partial_cmp(&a.0).unwrap_or(std::cmp::Ordering::Equal),
});
// Pagination applies after empty-field filtering: candidates lacking
// the rerank field are dropped before OFFSET/LIMIT, so page boundaries
// shift with payload quality (documented contract, not wire parity).
let skip = usize::try_from(offset).map_err(|_| {
QqlError::validation(
"QQL-VALIDATION-LIMIT-OVERFLOW",
format!("CROSS RERANK OFFSET {offset} overflows pointer width; reduce OFFSET"),
None,
)
})?;
let take = usize::try_from(limit).map_err(|_| {
QqlError::validation(
"QQL-VALIDATION-LIMIT-OVERFLOW",
format!("CROSS RERANK LIMIT {limit} overflows pointer width; reduce LIMIT"),
None,
)
})?;
let out: Vec<SearchHit> = ranked
.into_iter()
.skip(skip)
.take(take)
.map(|(score, k)| {
let i = doc_idx[k];
let mut h = hits[i].clone();
// Already rounded at rank time: the sort key and the stored
// hit are the same value.
h.score = score;
h.collection = Some(candidates[hit_coll[i]].0.clone());
h
})
.collect();
let n = out.len();
Ok(ExecResponse {
ok: true,
operation: "CROSS_RERANK".into(),
message: format!("Found {n} hits (cross-encoder)"),
data: Some(ExecData::Hits(out)),
telemetry: None,
})
}
}