Skip to main content

graphrt_rag/
qdrant.rs

1//! Qdrant vector store over its REST API.
2//!
3//! All datasets share one collection; every point carries `dataset_id`,
4//! `document_id`, `title`, `text`, `content_hash` and `metadata` in its payload.
5//! Dataset scoping is pushed down as a Qdrant filter, and so are metadata
6//! equality conditions whose result cannot differ from the in-process filter
7//! (non-numeric, non-boolean string values). Every other condition is applied
8//! after the search by the pipeline, which over-fetches candidates when a filter
9//! is present. Point ids are UUIDs derived from SHA-256 of the chunk id, so ids
10//! chosen by one tenant cannot be made to collide with another tenant's chunks.
11
12use std::sync::Arc;
13
14use futures::future::BoxFuture;
15use serde::{Deserialize, Serialize};
16
17use crate::error::RagError;
18use crate::filter::{Logical, MetadataFilter};
19use crate::http::{HttpSettings, build_client};
20use crate::types::{Hit, Metadata, StoredChunk, VectorQuery, VectorStore};
21
22/// Qdrant connection settings.
23#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
24pub struct QdrantConfig {
25    /// e.g. `http://localhost:6333`.
26    pub url: String,
27    pub collection: String,
28    /// Create the collection (cosine distance) on first upsert when missing.
29    #[serde(default = "yes")]
30    pub create_collection: bool,
31    /// API key, sent as the `api-key` header.
32    #[serde(default, flatten)]
33    pub http: HttpSettings,
34}
35
36fn yes() -> bool {
37    true
38}
39
40/// [`VectorStore`] backed by Qdrant.
41#[derive(Clone, Debug)]
42pub struct QdrantStore {
43    config: Arc<QdrantConfig>,
44    client: reqwest::Client,
45}
46
47#[derive(Deserialize)]
48struct SearchResponse {
49    #[serde(default)]
50    result: Vec<ScoredPoint>,
51}
52
53#[derive(Deserialize)]
54struct ScoredPoint {
55    score: f32,
56    #[serde(default)]
57    payload: Payload,
58}
59
60#[derive(Default, Deserialize, Serialize)]
61struct Payload {
62    #[serde(default)]
63    chunk_id: String,
64    #[serde(default)]
65    dataset_id: String,
66    #[serde(default)]
67    document_id: String,
68    #[serde(default)]
69    title: String,
70    #[serde(default)]
71    text: String,
72    #[serde(default)]
73    content_hash: String,
74    #[serde(default)]
75    metadata: Metadata,
76}
77
78#[derive(Deserialize)]
79struct CountResponse {
80    result: CountResult,
81}
82
83#[derive(Deserialize)]
84struct CountResult {
85    count: usize,
86}
87
88#[derive(Deserialize)]
89struct ScrollResponse {
90    result: ScrollResult,
91}
92
93#[derive(Deserialize)]
94struct ScrollResult {
95    #[serde(default)]
96    points: Vec<ScrolledPoint>,
97    #[serde(default)]
98    next_page_offset: Option<serde_json::Value>,
99}
100
101#[derive(Deserialize)]
102struct ScrolledPoint {
103    #[serde(default)]
104    payload: Payload,
105    #[serde(default)]
106    vector: Option<serde_json::Value>,
107}
108
109impl QdrantStore {
110    pub fn new(mut config: QdrantConfig) -> Result<Self, RagError> {
111        if config.url.trim().is_empty() || config.collection.trim().is_empty() {
112            return Err(RagError::Config("qdrant needs `url` and `collection`".into()));
113        }
114        if config.http.api_key_header.is_none() {
115            config.http.api_key_header = Some("api-key".into());
116        }
117        let client = build_client(&config.http)?;
118        Ok(Self { config: Arc::new(config), client })
119    }
120
121    fn url(&self, path: &str) -> String {
122        format!("{}/collections/{}{path}", self.config.url.trim_end_matches('/'), self.config.collection)
123    }
124
125    async fn send(
126        &self,
127        method: reqwest::Method,
128        url: String,
129        body: Option<serde_json::Value>,
130    ) -> Result<(u16, Vec<u8>), RagError> {
131        let mut req = self.client.request(method, url);
132        if !self.config.http.api_key.is_empty() {
133            let header = self.config.http.api_key_header.as_deref().unwrap_or("api-key");
134            req = req.header(header, self.config.http.api_key.expose());
135        }
136        for (k, v) in &self.config.http.headers {
137            req = req.header(k.as_str(), v.as_str());
138        }
139        if let Some(body) = body {
140            req = req.json(&body);
141        }
142        let response = req.send().await.map_err(|e| RagError::Network(e.without_url().to_string()))?;
143        let status = response.status().as_u16();
144        let bytes = response.bytes().await.map_err(|e| RagError::Network(e.without_url().to_string()))?.to_vec();
145        Ok((status, bytes))
146    }
147
148    async fn call(
149        &self,
150        method: reqwest::Method,
151        path: &str,
152        body: Option<serde_json::Value>,
153    ) -> Result<Vec<u8>, RagError> {
154        let (status, bytes) = self.send(method, self.url(path), body).await?;
155        if (200..300).contains(&status) {
156            return Ok(bytes);
157        }
158        let message = String::from_utf8_lossy(bytes.get(..bytes.len().min(2048)).unwrap_or_default()).into_owned();
159        Err(match status {
160            401 | 403 => RagError::Auth(message),
161            404 => RagError::NotFound(format!("qdrant collection `{}`: {message}", self.config.collection)),
162            _ => RagError::Http { status, message },
163        })
164    }
165
166    async fn ensure_collection(&self, dims: usize) -> Result<(), RagError> {
167        let (status, _) = self.send(reqwest::Method::GET, self.url(""), None).await?;
168        if status == 200 {
169            return Ok(());
170        }
171        if status != 404 || !self.config.create_collection {
172            return Err(RagError::Store(format!(
173                "qdrant collection `{}` unavailable (HTTP {status})",
174                self.config.collection
175            )));
176        }
177        let body = serde_json::json!({ "vectors": { "size": dims, "distance": "Cosine" } });
178        self.call(reqwest::Method::PUT, "", Some(body)).await?;
179        // Index the fields every filter uses, so dataset/document lookups are not full scans.
180        for field in ["dataset_id", "document_id", "content_hash"] {
181            let index = serde_json::json!({ "field_name": field, "field_schema": "keyword" });
182            self.call(reqwest::Method::PUT, "/index?wait=true", Some(index)).await?;
183        }
184        Ok(())
185    }
186
187    async fn count(&self, filter: serde_json::Value) -> Result<usize, RagError> {
188        let bytes = self
189            .call(reqwest::Method::POST, "/points/count", Some(serde_json::json!({"filter": filter, "exact": true})))
190            .await?;
191        let parsed: CountResponse = serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))?;
192        Ok(parsed.result.count)
193    }
194
195    async fn delete_matching(&self, filter: serde_json::Value) -> Result<usize, RagError> {
196        let count = match self.count(filter.clone()).await {
197            Ok(n) => n,
198            Err(RagError::NotFound(_)) => return Ok(0),
199            Err(e) => return Err(e),
200        };
201        if count > 0 {
202            self.call(reqwest::Method::POST, "/points/delete?wait=true", Some(serde_json::json!({"filter": filter})))
203                .await?;
204        }
205        Ok(count)
206    }
207}
208
209/// Qdrant point ids must be unsigned integers or UUIDs; derive a stable UUID from
210/// SHA-256 of the chunk id (collision-resistant, unlike a 64-bit hash).
211fn point_id(chunk_id: &str) -> String {
212    use sha2::Digest;
213    let digest = sha2::Sha256::digest(chunk_id.as_bytes());
214    let hex: String = digest.iter().take(16).map(|b| format!("{b:02x}")).collect();
215    let part = |range: std::ops::Range<usize>| hex.get(range).unwrap_or_default().to_owned();
216    format!("{}-{}-{}-{}-{}", part(0..8), part(8..12), part(12..16), part(16..20), part(20..32))
217}
218
219fn key_match(key: &str, value: serde_json::Value) -> serde_json::Value {
220    serde_json::json!({ "key": key, "match": { "value": value } })
221}
222
223/// Build the Qdrant filter: dataset scope plus pushed-down equality conditions.
224fn qdrant_filter(datasets: &[String], filter: Option<&MetadataFilter>) -> serde_json::Value {
225    let mut must = vec![serde_json::json!({ "key": "dataset_id", "match": { "any": datasets } })];
226    if let Some(f) = filter {
227        // Only AND filters can be pushed down safely; OR filters are applied afterwards.
228        if f.logical_operator == Logical::And {
229            for c in &f.conditions {
230                let is_eq = matches!(c.comparison_operator.trim(), "is" | "=" | "==" | "eq");
231                if is_eq && pushdown_safe(&c.value) {
232                    must.push(key_match(&format!("metadata.{}", c.name), c.value.clone()));
233                }
234            }
235        }
236    }
237    serde_json::json!({ "must": must })
238}
239
240/// Whether Qdrant's type-exact `match` gives the same result as the in-process
241/// `equals`, which also treats `2024 == "2024"` and `true == "true"` as equal.
242/// That holds only for strings that are not numbers, booleans, null or JSON.
243fn pushdown_safe(value: &serde_json::Value) -> bool {
244    let serde_json::Value::String(s) = value else { return false };
245    let t = s.trim();
246    !(t.is_empty()
247        || t.parse::<f64>().is_ok()
248        || matches!(t, "true" | "false" | "null")
249        || t.starts_with(['{', '['])
250        || t.len() != s.len())
251}
252
253fn document_filter(dataset_id: &str, document_id: &str) -> serde_json::Value {
254    serde_json::json!({ "must": [
255        key_match("dataset_id", dataset_id.into()),
256        key_match("document_id", document_id.into()),
257    ]})
258}
259
260/// Decode a point vector (unnamed vectors only).
261fn parse_vector(raw: Option<serde_json::Value>) -> Result<Vec<f32>, RagError> {
262    match raw {
263        None | Some(serde_json::Value::Null) => Ok(Vec::new()),
264        Some(v) => serde_json::from_value(v).map_err(|e| {
265            RagError::Decode(format!("unexpected qdrant vector format (named vectors are not supported): {e}"))
266        }),
267    }
268}
269
270impl VectorStore for QdrantStore {
271    fn upsert(&self, chunks: Vec<StoredChunk>) -> BoxFuture<'_, Result<(), RagError>> {
272        Box::pin(async move {
273            let Some(dims) = chunks.first().map(|c| c.vector.len()) else {
274                return Ok(());
275            };
276            for chunk in &chunks {
277                crate::types::check_vector(&chunk.vector, &format!("chunk `{}`", chunk.id))?;
278                if chunk.vector.len() != dims {
279                    return Err(RagError::Input(format!(
280                        "chunks mix {dims}- and {}-dimensional vectors",
281                        chunk.vector.len()
282                    )));
283                }
284            }
285            self.ensure_collection(dims).await?;
286            let points: Vec<serde_json::Value> = chunks
287                .into_iter()
288                .map(|c| {
289                    let payload = Payload {
290                        chunk_id: c.id.clone(),
291                        dataset_id: c.dataset_id,
292                        document_id: c.document_id,
293                        title: c.title,
294                        text: c.text,
295                        content_hash: c.content_hash,
296                        metadata: c.metadata,
297                    };
298                    serde_json::json!({ "id": point_id(&c.id), "vector": c.vector, "payload": payload })
299                })
300                .collect();
301            for batch in points.chunks(256) {
302                self.call(reqwest::Method::PUT, "/points?wait=true", Some(serde_json::json!({ "points": batch })))
303                    .await?;
304            }
305            Ok(())
306        })
307    }
308
309    fn delete_document<'a>(
310        &'a self,
311        dataset_id: &'a str,
312        document_id: &'a str,
313    ) -> BoxFuture<'a, Result<usize, RagError>> {
314        Box::pin(async move {
315            let filter = serde_json::json!({ "must": [
316                key_match("dataset_id", dataset_id.into()),
317                key_match("document_id", document_id.into()),
318            ]});
319            self.delete_matching(filter).await
320        })
321    }
322
323    fn delete_dataset<'a>(&'a self, dataset_id: &'a str) -> BoxFuture<'a, Result<usize, RagError>> {
324        Box::pin(async move {
325            let filter = serde_json::json!({ "must": [key_match("dataset_id", dataset_id.into())] });
326            self.delete_matching(filter).await
327        })
328    }
329
330    fn document_chunks<'a>(
331        &'a self,
332        dataset_id: &'a str,
333        document_id: &'a str,
334    ) -> BoxFuture<'a, Result<Vec<StoredChunk>, RagError>> {
335        Box::pin(async move {
336            let mut chunks = Vec::new();
337            let mut offset: Option<serde_json::Value> = None;
338            loop {
339                let mut body = serde_json::json!({
340                    "filter": document_filter(dataset_id, document_id),
341                    "limit": 256,
342                    "with_payload": true,
343                    "with_vector": true,
344                });
345                if let (Some(o), Some(obj)) = (offset.take(), body.as_object_mut()) {
346                    obj.insert("offset".into(), o);
347                }
348                let bytes = match self.call(reqwest::Method::POST, "/points/scroll", Some(body)).await {
349                    Ok(b) => b,
350                    // No collection yet: nothing stored.
351                    Err(RagError::NotFound(_)) => return Ok(chunks),
352                    Err(e) => return Err(e),
353                };
354                let page: ScrollResponse =
355                    serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))?;
356                for point in page.result.points {
357                    let vector = parse_vector(point.vector)?;
358                    let p = point.payload;
359                    chunks.push(StoredChunk {
360                        id: p.chunk_id,
361                        dataset_id: p.dataset_id,
362                        document_id: p.document_id,
363                        title: p.title,
364                        text: p.text,
365                        metadata: p.metadata,
366                        content_hash: p.content_hash,
367                        vector,
368                    });
369                }
370                match page.result.next_page_offset {
371                    Some(next) if !next.is_null() => offset = Some(next),
372                    _ => return Ok(chunks),
373                }
374            }
375        })
376    }
377
378    fn delete_chunks<'a>(&'a self, dataset_id: &'a str, ids: &'a [String]) -> BoxFuture<'a, Result<usize, RagError>> {
379        Box::pin(async move {
380            let _ = dataset_id;
381            for batch in ids.chunks(256) {
382                let points: Vec<String> = batch.iter().map(|id| point_id(id)).collect();
383                self.call(
384                    reqwest::Method::POST,
385                    "/points/delete?wait=true",
386                    Some(serde_json::json!({ "points": points })),
387                )
388                .await?;
389            }
390            Ok(ids.len())
391        })
392    }
393
394    fn search<'a>(&'a self, query: VectorQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
395        Box::pin(async move {
396            let body = serde_json::json!({
397                "vector": query.vector,
398                "limit": query.top_k,
399                "with_payload": true,
400                "filter": qdrant_filter(query.datasets, query.filter),
401            });
402            let bytes = self.call(reqwest::Method::POST, "/points/search", Some(body)).await?;
403            let parsed: SearchResponse = serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))?;
404            Ok(parsed
405                .result
406                .into_iter()
407                .map(|p| Hit {
408                    id: p.payload.chunk_id,
409                    dataset_id: p.payload.dataset_id,
410                    document_id: p.payload.document_id,
411                    title: p.payload.title,
412                    content: p.payload.text,
413                    score: p.score,
414                    metadata: p.payload.metadata,
415                })
416                .collect())
417        })
418    }
419
420    fn contains_hash<'a>(
421        &'a self,
422        dataset_id: &'a str,
423        content_hash: &'a str,
424    ) -> BoxFuture<'a, Result<bool, RagError>> {
425        Box::pin(async move {
426            let filter = serde_json::json!({ "must": [
427                key_match("dataset_id", dataset_id.into()),
428                key_match("content_hash", content_hash.into()),
429            ]});
430            match self.count(filter).await {
431                Ok(n) => Ok(n > 0),
432                Err(RagError::NotFound(_)) => Ok(false),
433                Err(e) => Err(e),
434            }
435        })
436    }
437}
438
439#[cfg(test)]
440mod tests {
441    use super::*;
442    use crate::filter::MetadataCondition;
443
444    #[test]
445    fn filter_pushdown_only_equality_with_and() {
446        let f = MetadataFilter {
447            logical_operator: Logical::And,
448            conditions: vec![
449                MetadataCondition { name: "lang".into(), comparison_operator: "is".into(), value: "en".into() },
450                MetadataCondition { name: "year".into(), comparison_operator: ">".into(), value: 2000.into() },
451            ],
452        };
453        let q = qdrant_filter(&["d".to_owned()], Some(&f));
454        let must = q["must"].as_array().unwrap();
455        assert_eq!(must.len(), 2);
456        assert_eq!(must[1]["key"], "metadata.lang");
457        // Values whose local equality is type-lenient are never pushed down.
458        for value in
459            [serde_json::json!("2024"), serde_json::json!(2024), serde_json::json!(9.5), serde_json::json!("true")]
460        {
461            let cond = MetadataCondition { name: "x".into(), comparison_operator: "is".into(), value };
462            let f = MetadataFilter { logical_operator: Logical::And, conditions: vec![cond] };
463            assert_eq!(qdrant_filter(&["d".to_owned()], Some(&f))["must"].as_array().unwrap().len(), 1);
464        }
465        let or = MetadataFilter { logical_operator: Logical::Or, ..f };
466        assert_eq!(qdrant_filter(&["d".to_owned()], Some(&or))["must"].as_array().unwrap().len(), 1);
467    }
468
469    #[test]
470    fn point_ids_are_stable_uuids() {
471        assert_eq!(point_id("a:b:0"), point_id("a:b:0"));
472        assert_ne!(point_id("a:b:0"), point_id("a:b:1"));
473        let id = point_id("a:b:0");
474        assert_eq!(id.len(), 36);
475        assert_eq!(id.matches('-').count(), 4);
476    }
477}