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    // Disabled documents stay stored but are never returned.
238    let disabled = key_match(&format!("metadata.{}", crate::types::DISABLED_KEY), serde_json::Value::Bool(true));
239    serde_json::json!({ "must": must, "must_not": [disabled] })
240}
241
242/// Whether Qdrant's type-exact `match` gives the same result as the in-process
243/// `equals`, which also treats `2024 == "2024"` and `true == "true"` as equal.
244/// That holds only for strings that are not numbers, booleans, null or JSON.
245fn pushdown_safe(value: &serde_json::Value) -> bool {
246    let serde_json::Value::String(s) = value else { return false };
247    let t = s.trim();
248    !(t.is_empty()
249        || t.parse::<f64>().is_ok()
250        || matches!(t, "true" | "false" | "null")
251        || t.starts_with(['{', '['])
252        || t.len() != s.len())
253}
254
255fn document_filter(dataset_id: &str, document_id: &str) -> serde_json::Value {
256    serde_json::json!({ "must": [
257        key_match("dataset_id", dataset_id.into()),
258        key_match("document_id", document_id.into()),
259    ]})
260}
261
262/// Decode a point vector (unnamed vectors only).
263fn parse_vector(raw: Option<serde_json::Value>) -> Result<Vec<f32>, RagError> {
264    match raw {
265        None | Some(serde_json::Value::Null) => Ok(Vec::new()),
266        Some(v) => serde_json::from_value(v).map_err(|e| {
267            RagError::Decode(format!("unexpected qdrant vector format (named vectors are not supported): {e}"))
268        }),
269    }
270}
271
272impl VectorStore for QdrantStore {
273    fn upsert(&self, chunks: Vec<StoredChunk>) -> BoxFuture<'_, Result<(), RagError>> {
274        Box::pin(async move {
275            let Some(dims) = chunks.first().map(|c| c.vector.len()) else {
276                return Ok(());
277            };
278            for chunk in &chunks {
279                crate::types::check_vector(&chunk.vector, &format!("chunk `{}`", chunk.id))?;
280                if chunk.vector.len() != dims {
281                    return Err(RagError::Input(format!(
282                        "chunks mix {dims}- and {}-dimensional vectors",
283                        chunk.vector.len()
284                    )));
285                }
286            }
287            self.ensure_collection(dims).await?;
288            let points: Vec<serde_json::Value> = chunks
289                .into_iter()
290                .map(|c| {
291                    let payload = Payload {
292                        chunk_id: c.id.clone(),
293                        dataset_id: c.dataset_id,
294                        document_id: c.document_id,
295                        title: c.title,
296                        text: c.text,
297                        content_hash: c.content_hash,
298                        metadata: c.metadata,
299                    };
300                    serde_json::json!({ "id": point_id(&c.id), "vector": c.vector, "payload": payload })
301                })
302                .collect();
303            for batch in points.chunks(256) {
304                self.call(reqwest::Method::PUT, "/points?wait=true", Some(serde_json::json!({ "points": batch })))
305                    .await?;
306            }
307            Ok(())
308        })
309    }
310
311    fn delete_document<'a>(
312        &'a self,
313        dataset_id: &'a str,
314        document_id: &'a str,
315    ) -> BoxFuture<'a, Result<usize, RagError>> {
316        Box::pin(async move {
317            let filter = serde_json::json!({ "must": [
318                key_match("dataset_id", dataset_id.into()),
319                key_match("document_id", document_id.into()),
320            ]});
321            self.delete_matching(filter).await
322        })
323    }
324
325    fn delete_dataset<'a>(&'a self, dataset_id: &'a str) -> BoxFuture<'a, Result<usize, RagError>> {
326        Box::pin(async move {
327            let filter = serde_json::json!({ "must": [key_match("dataset_id", dataset_id.into())] });
328            self.delete_matching(filter).await
329        })
330    }
331
332    fn document_chunks<'a>(
333        &'a self,
334        dataset_id: &'a str,
335        document_id: &'a str,
336    ) -> BoxFuture<'a, Result<Vec<StoredChunk>, RagError>> {
337        Box::pin(async move {
338            let mut chunks = Vec::new();
339            let mut offset: Option<serde_json::Value> = None;
340            loop {
341                let mut body = serde_json::json!({
342                    "filter": document_filter(dataset_id, document_id),
343                    "limit": 256,
344                    "with_payload": true,
345                    "with_vector": true,
346                });
347                if let (Some(o), Some(obj)) = (offset.take(), body.as_object_mut()) {
348                    obj.insert("offset".into(), o);
349                }
350                let bytes = match self.call(reqwest::Method::POST, "/points/scroll", Some(body)).await {
351                    Ok(b) => b,
352                    // No collection yet: nothing stored.
353                    Err(RagError::NotFound(_)) => return Ok(chunks),
354                    Err(e) => return Err(e),
355                };
356                let page: ScrollResponse =
357                    serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))?;
358                for point in page.result.points {
359                    let vector = parse_vector(point.vector)?;
360                    let p = point.payload;
361                    chunks.push(StoredChunk {
362                        id: p.chunk_id,
363                        dataset_id: p.dataset_id,
364                        document_id: p.document_id,
365                        title: p.title,
366                        text: p.text,
367                        metadata: p.metadata,
368                        content_hash: p.content_hash,
369                        vector,
370                    });
371                }
372                match page.result.next_page_offset {
373                    Some(next) if !next.is_null() => offset = Some(next),
374                    _ => return Ok(chunks),
375                }
376            }
377        })
378    }
379
380    fn delete_chunks<'a>(&'a self, dataset_id: &'a str, ids: &'a [String]) -> BoxFuture<'a, Result<usize, RagError>> {
381        Box::pin(async move {
382            let _ = dataset_id;
383            for batch in ids.chunks(256) {
384                let points: Vec<String> = batch.iter().map(|id| point_id(id)).collect();
385                self.call(
386                    reqwest::Method::POST,
387                    "/points/delete?wait=true",
388                    Some(serde_json::json!({ "points": points })),
389                )
390                .await?;
391            }
392            Ok(ids.len())
393        })
394    }
395
396    fn search<'a>(&'a self, query: VectorQuery<'a>) -> BoxFuture<'a, Result<Vec<Hit>, RagError>> {
397        Box::pin(async move {
398            let body = serde_json::json!({
399                "vector": query.vector,
400                "limit": query.top_k,
401                "with_payload": true,
402                "filter": qdrant_filter(query.datasets, query.filter),
403            });
404            let bytes = self.call(reqwest::Method::POST, "/points/search", Some(body)).await?;
405            let parsed: SearchResponse = serde_json::from_slice(&bytes).map_err(|e| RagError::Decode(e.to_string()))?;
406            Ok(parsed
407                .result
408                .into_iter()
409                .map(|p| Hit {
410                    id: p.payload.chunk_id,
411                    dataset_id: p.payload.dataset_id,
412                    document_id: p.payload.document_id,
413                    title: p.payload.title,
414                    content: p.payload.text,
415                    score: p.score,
416                    metadata: p.payload.metadata,
417                })
418                .collect())
419        })
420    }
421
422    fn contains_hash<'a>(
423        &'a self,
424        dataset_id: &'a str,
425        content_hash: &'a str,
426    ) -> BoxFuture<'a, Result<bool, RagError>> {
427        Box::pin(async move {
428            let filter = serde_json::json!({ "must": [
429                key_match("dataset_id", dataset_id.into()),
430                key_match("content_hash", content_hash.into()),
431            ]});
432            match self.count(filter).await {
433                Ok(n) => Ok(n > 0),
434                Err(RagError::NotFound(_)) => Ok(false),
435                Err(e) => Err(e),
436            }
437        })
438    }
439}
440
441#[cfg(test)]
442mod tests {
443    use super::*;
444    use crate::filter::MetadataCondition;
445
446    #[test]
447    fn filter_pushdown_only_equality_with_and() {
448        let f = MetadataFilter {
449            logical_operator: Logical::And,
450            conditions: vec![
451                MetadataCondition { name: "lang".into(), comparison_operator: "is".into(), value: "en".into() },
452                MetadataCondition { name: "year".into(), comparison_operator: ">".into(), value: 2000.into() },
453            ],
454        };
455        let q = qdrant_filter(&["d".to_owned()], Some(&f));
456        let must = q["must"].as_array().unwrap();
457        assert_eq!(must.len(), 2);
458        assert_eq!(must[1]["key"], "metadata.lang");
459        // Values whose local equality is type-lenient are never pushed down.
460        for value in
461            [serde_json::json!("2024"), serde_json::json!(2024), serde_json::json!(9.5), serde_json::json!("true")]
462        {
463            let cond = MetadataCondition { name: "x".into(), comparison_operator: "is".into(), value };
464            let f = MetadataFilter { logical_operator: Logical::And, conditions: vec![cond] };
465            assert_eq!(qdrant_filter(&["d".to_owned()], Some(&f))["must"].as_array().unwrap().len(), 1);
466        }
467        let or = MetadataFilter { logical_operator: Logical::Or, ..f };
468        assert_eq!(qdrant_filter(&["d".to_owned()], Some(&or))["must"].as_array().unwrap().len(), 1);
469    }
470
471    #[test]
472    fn point_ids_are_stable_uuids() {
473        assert_eq!(point_id("a:b:0"), point_id("a:b:0"));
474        assert_ne!(point_id("a:b:0"), point_id("a:b:1"));
475        let id = point_id("a:b:0");
476        assert_eq!(id.len(), 36);
477        assert_eq!(id.matches('-').count(), 4);
478    }
479}