1use 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
48pub use redis_tower::commands::VQuantization;
50
51#[derive(Debug, Clone)]
53pub struct SimilarityResult {
54 pub element: Bytes,
56 pub score: Option<f64>,
58}
59
60#[derive(Debug, Clone, Default)]
62pub struct VectorSetInfo {
63 pub quant_type: String,
65 pub vector_dim: i64,
67 pub size: i64,
69 pub max_node_uid: i64,
71 pub vset_uid: i64,
73}
74
75#[derive(Default)]
80pub struct VAddOptions {
81 pub reduce_dim: Option<u64>,
83 pub cas: bool,
85 pub m: Option<u64>,
87 pub ef: Option<u64>,
89 pub quant: Option<VQuantization>,
91}
92
93fn 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
102fn 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
135pub enum QueryTarget {
137 Element(CommandArg),
139 Values(Vec<f32>),
141}
142
143pub 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 pub fn by_element(element: impl Into<CommandArg>) -> Self {
161 Self::with_target(QueryTarget::Element(element.into()))
162 }
163
164 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 pub fn count(mut self, n: u64) -> Self {
184 self.count = Some(n);
185 self
186 }
187
188 pub fn ef(mut self, n: u64) -> Self {
190 self.ef = Some(n);
191 self
192 }
193
194 pub fn filter(mut self, expr: impl Into<String>) -> Self {
196 self.filter = Some(expr.into());
197 self
198 }
199
200 pub fn filter_ef(mut self, n: u64) -> Self {
202 self.filter_ef = Some(n);
203 self
204 }
205
206 pub fn withscores(mut self) -> Self {
208 self.withscores = true;
209 self
210 }
211
212 pub fn nothread(mut self) -> Self {
214 self.nothread = true;
215 self
216 }
217
218 pub fn truth(mut self) -> Self {
220 self.truth = true;
221 self
222 }
223}
224
225pub struct VectorSetClient<'a, C> {
231 key: CommandArg,
232 conn: &'a mut C,
233}
234
235impl<'a, C: RedisExecutor> VectorSetClient<'a, C> {
236 pub fn new(conn: &'a mut C, key: impl Into<CommandArg>) -> Self {
238 Self {
239 key: key.into(),
240 conn,
241 }
242 }
243
244 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 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 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 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 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 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 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 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 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 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 pub async fn cardinality(&mut self) -> Result<i64, RedisError> {
387 self.conn.execute(VCard::new(self.key.clone())).await
388 }
389
390 pub async fn dimensions(&mut self) -> Result<i64, RedisError> {
392 self.conn.execute(VDim::new(self.key.clone())).await
393 }
394
395 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 #[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 #[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
431fn to_results(raw: Vec<(Bytes, Option<f64>)>) -> Vec<SimilarityResult> {
433 raw.into_iter()
434 .map(|(element, score)| SimilarityResult { element, score })
435 .collect()
436}
437
438fn 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
481fn 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
490fn 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 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 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}