Skip to main content

redis_tower_modules/
vector.rs

1//! # Vector Set Client
2//!
3//! Ergonomic, typed client over Redis [Vector Sets]. Vectors are exchanged as
4//! `Vec<f32>` and binary-safe named elements, hiding the raw
5//! [`Frame`] reply structure. Similarity searches return
6//! typed [`SimilarityResult`] values and introspection returns a structured
7//! [`VectorSetInfo`].
8//!
9//! Vector Sets require Redis 8.0 or later.
10//!
11//! [Vector Sets]: https://redis.io/docs/latest/develop/data-types/vector-sets/
12//!
13//! # Example
14//!
15//! ```no_run
16//! use redis_tower::RedisConnection;
17//! use redis_tower_modules::vector::{VectorSetClient, VectorQuery};
18//!
19//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
20//! let mut conn = RedisConnection::connect("127.0.0.1:6379").await?;
21//! let mut vset = VectorSetClient::new(&mut conn, "points");
22//!
23//! // Add a few 3-dimensional vectors.
24//! vset.add(vec![1.0, 0.0, 0.0], "a").await?;
25//! vset.add(vec![0.9, 0.1, 0.0], "b").await?;
26//! vset.add(vec![0.0, 1.0, 0.0], "c").await?;
27//!
28//! // Find the elements most similar to a query vector, with scores.
29//! let query = VectorQuery::by_vector(vec![1.0, 0.0, 0.0])
30//!     .count(2)
31//!     .withscores();
32//! let hits = vset.search(query).await?;
33//! for hit in hits {
34//!     println!("{:?} -> {:?}", hit.element, hit.score);
35//! }
36//! # Ok(())
37//! # }
38//! ```
39
40use bytes::Bytes;
41use redis_tower::RedisExecutor;
42use redis_tower::commands::{
43    CommandArg, VAdd, VCard, VDelAttr, VDim, VEmb, VGetAttr, VInfo, VLinks, VRandMember, VRem,
44    VSetAttr, VSim,
45};
46use redis_tower_core::{Frame, RedisError};
47
48/// Quantization type for vector storage, re-exported from the command layer.
49pub use redis_tower::commands::VQuantization;
50
51/// A similarity search result: an element name and, optionally, its score.
52#[derive(Debug, Clone)]
53pub struct SimilarityResult {
54    /// The element name.
55    pub element: Bytes,
56    /// The similarity score, present only when the query requested scores.
57    pub score: Option<f64>,
58}
59
60/// Information about a vector set, returned by [`VectorSetClient::info`].
61#[derive(Debug, Clone, Default)]
62pub struct VectorSetInfo {
63    /// The quantization type in use (e.g. `"int8"`, `"f32"`, `"bin"`).
64    pub quant_type: String,
65    /// The dimensionality of the stored vectors.
66    pub vector_dim: i64,
67    /// The number of elements in the set.
68    pub size: i64,
69    /// The maximum node UID allocated in the underlying HNSW graph.
70    pub max_node_uid: i64,
71    /// The internal UID of the vector set.
72    pub vset_uid: i64,
73}
74
75/// Options for adding a vector element with [`VectorSetClient::add_with_options`].
76///
77/// `Debug` and `Clone` are implemented by hand because [`VQuantization`] (from
78/// the command layer) does not derive them.
79#[derive(Default)]
80pub struct VAddOptions {
81    /// Reduce the stored vector to this many dimensions (random projection).
82    pub reduce_dim: Option<u64>,
83    /// Use check-and-set semantics when inserting.
84    pub cas: bool,
85    /// Maximum number of links per HNSW node.
86    pub m: Option<u64>,
87    /// EF construction parameter for the HNSW graph.
88    pub ef: Option<u64>,
89    /// Quantization type for the stored vector.
90    pub quant: Option<VQuantization>,
91}
92
93/// Copy a [`VQuantization`] variant (it is a plain enum without `Clone`).
94fn copy_quant(q: &VQuantization) -> VQuantization {
95    match q {
96        VQuantization::Q8 => VQuantization::Q8,
97        VQuantization::Bf16 => VQuantization::Bf16,
98        VQuantization::NoQuant => VQuantization::NoQuant,
99    }
100}
101
102/// A short debug label for a [`VQuantization`] variant.
103fn quant_label(q: &VQuantization) -> &'static str {
104    match q {
105        VQuantization::Q8 => "Q8",
106        VQuantization::Bf16 => "Bf16",
107        VQuantization::NoQuant => "NoQuant",
108    }
109}
110
111impl Clone for VAddOptions {
112    fn clone(&self) -> Self {
113        Self {
114            reduce_dim: self.reduce_dim,
115            cas: self.cas,
116            m: self.m,
117            ef: self.ef,
118            quant: self.quant.as_ref().map(copy_quant),
119        }
120    }
121}
122
123impl std::fmt::Debug for VAddOptions {
124    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
125        f.debug_struct("VAddOptions")
126            .field("reduce_dim", &self.reduce_dim)
127            .field("cas", &self.cas)
128            .field("m", &self.m)
129            .field("ef", &self.ef)
130            .field("quant", &self.quant.as_ref().map(quant_label))
131            .finish()
132    }
133}
134
135/// Target for a similarity search query.
136pub enum QueryTarget {
137    /// Search by an existing element name already present in the set.
138    Element(CommandArg),
139    /// Search by a raw vector of values.
140    Values(Vec<f32>),
141}
142
143/// Builder for similarity search queries (`VSIM`).
144///
145/// Construct with [`VectorQuery::by_element`] or [`VectorQuery::by_vector`],
146/// then chain options before passing to [`VectorSetClient::search`].
147pub struct VectorQuery {
148    target: QueryTarget,
149    count: Option<u64>,
150    ef: Option<u64>,
151    filter: Option<String>,
152    filter_ef: Option<u64>,
153    withscores: bool,
154    nothread: bool,
155    truth: bool,
156}
157
158impl VectorQuery {
159    /// Search for elements similar to an existing element in the set.
160    pub fn by_element(element: impl Into<CommandArg>) -> Self {
161        Self::with_target(QueryTarget::Element(element.into()))
162    }
163
164    /// Search for elements similar to the given vector.
165    pub fn by_vector(vector: Vec<f32>) -> Self {
166        Self::with_target(QueryTarget::Values(vector))
167    }
168
169    fn with_target(target: QueryTarget) -> Self {
170        Self {
171            target,
172            count: None,
173            ef: None,
174            filter: None,
175            filter_ef: None,
176            withscores: false,
177            nothread: false,
178            truth: false,
179        }
180    }
181
182    /// Limit the number of results returned.
183    pub fn count(mut self, n: u64) -> Self {
184        self.count = Some(n);
185        self
186    }
187
188    /// Set the EF search parameter (search effort).
189    pub fn ef(mut self, n: u64) -> Self {
190        self.ef = Some(n);
191        self
192    }
193
194    /// Filter results by an attribute expression.
195    pub fn filter(mut self, expr: impl Into<String>) -> Self {
196        self.filter = Some(expr.into());
197        self
198    }
199
200    /// Set the EF parameter used while filtering.
201    pub fn filter_ef(mut self, n: u64) -> Self {
202        self.filter_ef = Some(n);
203        self
204    }
205
206    /// Include similarity scores in the results.
207    pub fn withscores(mut self) -> Self {
208        self.withscores = true;
209        self
210    }
211
212    /// Disable multi-threading for this query.
213    pub fn nothread(mut self) -> Self {
214        self.nothread = true;
215        self
216    }
217
218    /// Use brute-force (exact) search instead of approximate search.
219    pub fn truth(mut self) -> Self {
220        self.truth = true;
221        self
222    }
223}
224
225/// High-level client for Vector Set operations, bound to a single key.
226///
227/// Holds a mutable borrow of an underlying [`RedisExecutor`] and a vector set
228/// key, exposing typed add/query/introspection operations over the elements of
229/// that set.
230pub struct VectorSetClient<'a, C> {
231    key: CommandArg,
232    conn: &'a mut C,
233}
234
235impl<'a, C: RedisExecutor> VectorSetClient<'a, C> {
236    /// Create a new [`VectorSetClient`] for `key`, borrowing `conn`.
237    pub fn new(conn: &'a mut C, key: impl Into<CommandArg>) -> Self {
238        Self {
239            key: key.into(),
240            conn,
241        }
242    }
243
244    /// Add or update a vector element. Returns `true` if the element was newly
245    /// added, `false` if an existing element was updated.
246    pub async fn add(
247        &mut self,
248        vector: Vec<f32>,
249        element: impl Into<CommandArg>,
250    ) -> Result<bool, RedisError> {
251        self.conn
252            .execute(VAdd::new(self.key.clone(), vector, element.into()))
253            .await
254    }
255
256    /// Add or update a vector element with explicit [`VAddOptions`].
257    pub async fn add_with_options(
258        &mut self,
259        vector: Vec<f32>,
260        element: impl Into<CommandArg>,
261        options: VAddOptions,
262    ) -> Result<bool, RedisError> {
263        let mut cmd = VAdd::new(self.key.clone(), vector, element.into());
264        if let Some(dim) = options.reduce_dim {
265            cmd = cmd.reduce(dim);
266        }
267        if options.cas {
268            cmd = cmd.cas();
269        }
270        if let Some(m) = options.m {
271            cmd = cmd.m(m);
272        }
273        if let Some(ef) = options.ef {
274            cmd = cmd.ef(ef);
275        }
276        if let Some(quant) = options.quant {
277            cmd = cmd.quant(quant);
278        }
279        self.conn.execute(cmd).await
280    }
281
282    /// Remove an element. Returns `true` if it existed and was removed.
283    pub async fn remove(&mut self, element: impl Into<CommandArg>) -> Result<bool, RedisError> {
284        self.conn
285            .execute(VRem::new(self.key.clone(), element))
286            .await
287    }
288
289    /// Find the elements most similar to the query target.
290    pub async fn search(
291        &mut self,
292        query: VectorQuery,
293    ) -> Result<Vec<SimilarityResult>, RedisError> {
294        let mut cmd = match query.target {
295            QueryTarget::Element(element) => VSim::by_element(self.key.clone(), element),
296            QueryTarget::Values(vector) => VSim::by_values(self.key.clone(), vector),
297        };
298        if let Some(n) = query.count {
299            cmd = cmd.count(n);
300        }
301        if let Some(n) = query.ef {
302            cmd = cmd.ef(n);
303        }
304        if let Some(expr) = query.filter {
305            cmd = cmd.filter(expr);
306        }
307        if let Some(n) = query.filter_ef {
308            cmd = cmd.filter_ef(n);
309        }
310        if query.withscores {
311            cmd = cmd.withscores();
312        }
313        if query.nothread {
314            cmd = cmd.nothread();
315        }
316        if query.truth {
317            cmd = cmd.truth();
318        }
319        let raw = self.conn.execute(cmd).await?;
320        Ok(to_results(raw))
321    }
322
323    /// Retrieve the embedding (vector) for an element.
324    pub async fn embedding(
325        &mut self,
326        element: impl Into<CommandArg>,
327    ) -> Result<Vec<f64>, RedisError> {
328        self.conn
329            .execute(VEmb::new(self.key.clone(), element))
330            .await
331    }
332
333    /// Return the neighbour links of an element, with similarity scores.
334    pub async fn links(
335        &mut self,
336        element: impl Into<CommandArg>,
337    ) -> Result<Vec<SimilarityResult>, RedisError> {
338        let raw = self
339            .conn
340            .execute(VLinks::new(self.key.clone(), element).withscores())
341            .await?;
342        Ok(to_results(raw))
343    }
344
345    /// Return one or more random elements from the set. A negative `count`
346    /// allows duplicates.
347    pub async fn random(&mut self, count: Option<i64>) -> Result<Vec<Bytes>, RedisError> {
348        let mut cmd = VRandMember::new(self.key.clone());
349        if let Some(n) = count {
350            cmd = cmd.count(n);
351        }
352        self.conn.execute(cmd).await
353    }
354
355    /// Set a JSON attribute string on an element. Returns `true` on success.
356    pub async fn set_attr(
357        &mut self,
358        element: impl Into<CommandArg>,
359        json: &str,
360    ) -> Result<bool, RedisError> {
361        self.conn
362            .execute(VSetAttr::new(self.key.clone(), element, json))
363            .await
364    }
365
366    /// Get the JSON attribute string for an element, or `None` if unset.
367    pub async fn get_attr(
368        &mut self,
369        element: impl Into<CommandArg>,
370    ) -> Result<Option<String>, RedisError> {
371        self.conn
372            .execute(VGetAttr::new(self.key.clone(), element))
373            .await
374    }
375
376    /// Clear the attribute on an element. Redis has no `VDELATTR`, so this sets
377    /// the attribute to the empty string via `VSETATTR`. Returns `true` if the
378    /// element exists, `false` if it is not in the set.
379    pub async fn del_attr(&mut self, element: impl Into<CommandArg>) -> Result<bool, RedisError> {
380        self.conn
381            .execute(VDelAttr::new(self.key.clone(), element))
382            .await
383    }
384
385    /// Return the number of elements in the set.
386    pub async fn cardinality(&mut self) -> Result<i64, RedisError> {
387        self.conn.execute(VCard::new(self.key.clone())).await
388    }
389
390    /// Return the dimensionality of the vectors in the set.
391    pub async fn dimensions(&mut self) -> Result<i64, RedisError> {
392        self.conn.execute(VDim::new(self.key.clone())).await
393    }
394
395    /// Return structured information about the set.
396    pub async fn info(&mut self) -> Result<VectorSetInfo, RedisError> {
397        let frames = self.conn.execute(VInfo::new(self.key.clone())).await?;
398        Ok(parse_info(frames))
399    }
400
401    /// Set a typed attribute on an element, serializing with `serde_json`.
402    #[cfg(feature = "serde")]
403    pub async fn set_attr_typed<T: serde::Serialize>(
404        &mut self,
405        element: impl Into<CommandArg>,
406        attr: &T,
407    ) -> Result<bool, RedisError> {
408        let json = serde_json::to_string(attr)
409            .map_err(|e| RedisError::Redis(format!("JSON serialization error: {e}")))?;
410        self.set_attr(element, &json).await
411    }
412
413    /// Get a typed attribute from an element, deserializing with `serde_json`.
414    /// Returns `None` if no attribute is set.
415    #[cfg(feature = "serde")]
416    pub async fn get_attr_typed<T: serde::de::DeserializeOwned>(
417        &mut self,
418        element: impl Into<CommandArg>,
419    ) -> Result<Option<T>, RedisError> {
420        match self.get_attr(element).await? {
421            None => Ok(None),
422            Some(json) => {
423                let value = serde_json::from_str(&json)
424                    .map_err(|e| RedisError::Redis(format!("JSON deserialize error: {e}")))?;
425                Ok(Some(value))
426            }
427        }
428    }
429}
430
431/// Convert a raw `(bytes, score)` response into typed [`SimilarityResult`]s.
432fn to_results(raw: Vec<(Bytes, Option<f64>)>) -> Vec<SimilarityResult> {
433    raw.into_iter()
434        .map(|(element, score)| SimilarityResult { element, score })
435        .collect()
436}
437
438/// Parse a flat alternating key/value `VINFO` reply into [`VectorSetInfo`].
439fn parse_info(frames: Vec<Frame>) -> VectorSetInfo {
440    let mut info = VectorSetInfo::default();
441    let mut iter = frames.into_iter();
442    while let Some(key_frame) = iter.next() {
443        let Some(value_frame) = iter.next() else {
444            break;
445        };
446        let Some(key) = frame_to_string(&key_frame) else {
447            continue;
448        };
449        match key.as_str() {
450            "quant-type" | "quant_type" => {
451                if let Some(s) = frame_to_string(&value_frame) {
452                    info.quant_type = s;
453                }
454            }
455            "vector-dim" | "vector_dim" => {
456                if let Some(n) = frame_to_i64(&value_frame) {
457                    info.vector_dim = n;
458                }
459            }
460            "size" => {
461                if let Some(n) = frame_to_i64(&value_frame) {
462                    info.size = n;
463                }
464            }
465            "max-node-uid" | "max_node_uid" => {
466                if let Some(n) = frame_to_i64(&value_frame) {
467                    info.max_node_uid = n;
468                }
469            }
470            "vset-uid" | "vset_uid" => {
471                if let Some(n) = frame_to_i64(&value_frame) {
472                    info.vset_uid = n;
473                }
474            }
475            _ => {}
476        }
477    }
478    info
479}
480
481/// Extract a UTF-8 string from a string-like frame.
482fn frame_to_string(frame: &Frame) -> Option<String> {
483    match frame {
484        Frame::BulkString(Some(b)) => Some(String::from_utf8_lossy(b).into_owned()),
485        Frame::SimpleString(b) => Some(String::from_utf8_lossy(b).into_owned()),
486        _ => None,
487    }
488}
489
490/// Extract an integer from a numeric frame (integer, double, or numeric string).
491fn frame_to_i64(frame: &Frame) -> Option<i64> {
492    match frame {
493        Frame::Integer(n) => Some(*n),
494        Frame::Double(d) => Some(*d as i64),
495        Frame::BulkString(Some(b)) => String::from_utf8_lossy(b).parse().ok(),
496        Frame::SimpleString(b) => String::from_utf8_lossy(b).parse().ok(),
497        _ => None,
498    }
499}
500
501#[cfg(test)]
502mod tests {
503    use super::*;
504    use bytes::Bytes;
505    use redis_tower_core::Command;
506    use std::collections::VecDeque;
507    use std::future::Future;
508
509    /// A mock executor that returns pre-configured frames in order.
510    struct MockRedis {
511        responses: VecDeque<Frame>,
512    }
513
514    impl MockRedis {
515        fn new(responses: Vec<Frame>) -> Self {
516            Self {
517                responses: VecDeque::from(responses),
518            }
519        }
520    }
521
522    impl RedisExecutor for MockRedis {
523        fn execute<Cmd: Command>(
524            &mut self,
525            cmd: Cmd,
526        ) -> impl Future<Output = Result<Cmd::Response, RedisError>> + Send {
527            let frame = self.responses.pop_front().unwrap_or(Frame::Null);
528            async move { cmd.parse_response(frame) }
529        }
530    }
531
532    fn bulk(s: &str) -> Frame {
533        Frame::BulkString(Some(Bytes::from(s.to_string())))
534    }
535
536    #[tokio::test]
537    async fn add_returns_true_when_added() {
538        let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
539        let mut vset = VectorSetClient::new(&mut mock, "k");
540        let added = vset.add(vec![1.0, 2.0, 3.0], "a").await.unwrap();
541        assert!(added);
542    }
543
544    #[tokio::test]
545    async fn add_returns_false_when_updated() {
546        let mut mock = MockRedis::new(vec![Frame::Integer(0)]);
547        let mut vset = VectorSetClient::new(&mut mock, "k");
548        let added = vset.add(vec![1.0, 2.0, 3.0], "a").await.unwrap();
549        assert!(!added);
550    }
551
552    #[tokio::test]
553    async fn remove_returns_true_when_removed() {
554        let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
555        let mut vset = VectorSetClient::new(&mut mock, "k");
556        assert!(vset.remove("a").await.unwrap());
557    }
558
559    #[tokio::test]
560    async fn search_without_scores() {
561        let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![bulk("a"), bulk("b")]))]);
562        let mut vset = VectorSetClient::new(&mut mock, "k");
563        let results = vset
564            .search(VectorQuery::by_vector(vec![1.0, 0.0, 0.0]))
565            .await
566            .unwrap();
567        assert_eq!(results.len(), 2);
568        assert_eq!(results[0].element, "a");
569        assert_eq!(results[0].score, None);
570        assert_eq!(results[1].element, "b");
571        assert_eq!(results[1].score, None);
572    }
573
574    #[tokio::test]
575    async fn search_with_scores() {
576        let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
577            bulk("a"),
578            bulk("0.99"),
579            bulk("b"),
580            bulk("0.50"),
581        ]))]);
582        let mut vset = VectorSetClient::new(&mut mock, "k");
583        let results = vset
584            .search(VectorQuery::by_vector(vec![1.0, 0.0, 0.0]).withscores())
585            .await
586            .unwrap();
587        assert_eq!(results.len(), 2);
588        assert_eq!(results[0].element, "a");
589        assert_eq!(results[0].score, Some(0.99));
590        assert_eq!(results[1].element, "b");
591        assert_eq!(results[1].score, Some(0.50));
592    }
593
594    #[tokio::test]
595    async fn embedding_returns_floats() {
596        let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
597            bulk("1.5"),
598            bulk("2.5"),
599            bulk("3.5"),
600        ]))]);
601        let mut vset = VectorSetClient::new(&mut mock, "k");
602        let emb = vset.embedding("a").await.unwrap();
603        assert_eq!(emb, vec![1.5, 2.5, 3.5]);
604    }
605
606    #[tokio::test]
607    async fn cardinality_returns_count() {
608        let mut mock = MockRedis::new(vec![Frame::Integer(3)]);
609        let mut vset = VectorSetClient::new(&mut mock, "k");
610        assert_eq!(vset.cardinality().await.unwrap(), 3);
611    }
612
613    #[tokio::test]
614    async fn info_parses_flat_kv() {
615        let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
616            bulk("quant-type"),
617            bulk("int8"),
618            bulk("vector-dim"),
619            Frame::Integer(3),
620            bulk("size"),
621            Frame::Integer(42),
622            bulk("max-node-uid"),
623            Frame::Integer(7),
624            bulk("vset-uid"),
625            Frame::Integer(9),
626        ]))]);
627        let mut vset = VectorSetClient::new(&mut mock, "k");
628        let info = vset.info().await.unwrap();
629        assert_eq!(info.quant_type, "int8");
630        assert_eq!(info.vector_dim, 3);
631        assert_eq!(info.size, 42);
632        assert_eq!(info.max_node_uid, 7);
633        assert_eq!(info.vset_uid, 9);
634    }
635
636    #[tokio::test]
637    async fn random_returns_bytes() {
638        let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![bulk("a"), bulk("b")]))]);
639        let mut vset = VectorSetClient::new(&mut mock, "k");
640        let members = vset.random(Some(2)).await.unwrap();
641        assert_eq!(
642            members,
643            vec![Bytes::from_static(b"a"), Bytes::from_static(b"b")]
644        );
645    }
646
647    #[tokio::test]
648    async fn get_attr_returns_none_for_null() {
649        let mut mock = MockRedis::new(vec![Frame::Null]);
650        let mut vset = VectorSetClient::new(&mut mock, "k");
651        assert_eq!(vset.get_attr("a").await.unwrap(), None);
652    }
653
654    #[tokio::test]
655    async fn get_attr_returns_string() {
656        let mut mock = MockRedis::new(vec![Frame::BulkString(Some(Bytes::from("{\"x\":1}")))]);
657        let mut vset = VectorSetClient::new(&mut mock, "k");
658        assert_eq!(
659            vset.get_attr("a").await.unwrap(),
660            Some("{\"x\":1}".to_string())
661        );
662    }
663
664    #[tokio::test]
665    async fn del_attr_returns_true_on_success() {
666        // del_attr sends VSETATTR "" (no VDELATTR exists) and parses 1 as true.
667        let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
668        let mut vset = VectorSetClient::new(&mut mock, "k");
669        assert!(vset.del_attr("a").await.unwrap());
670    }
671}