use redis_tower::RedisExecutor;
use redis_tower::commands::{
VAdd, VCard, VDelAttr, VDim, VEmb, VGetAttr, VInfo, VLinks, VRandMember, VRem, VSetAttr, VSim,
};
use redis_tower_core::{Frame, RedisError};
pub use redis_tower::commands::VQuantization;
#[derive(Debug, Clone)]
pub struct SimilarityResult {
pub element: String,
pub score: Option<f64>,
}
#[derive(Debug, Clone, Default)]
pub struct VectorSetInfo {
pub quant_type: String,
pub vector_dim: i64,
pub size: i64,
pub max_node_uid: i64,
pub vset_uid: i64,
}
#[derive(Default)]
pub struct VAddOptions {
pub reduce_dim: Option<u64>,
pub cas: bool,
pub m: Option<u64>,
pub ef: Option<u64>,
pub quant: Option<VQuantization>,
}
fn copy_quant(q: &VQuantization) -> VQuantization {
match q {
VQuantization::Q8 => VQuantization::Q8,
VQuantization::Bf16 => VQuantization::Bf16,
VQuantization::NoQuant => VQuantization::NoQuant,
}
}
fn quant_label(q: &VQuantization) -> &'static str {
match q {
VQuantization::Q8 => "Q8",
VQuantization::Bf16 => "Bf16",
VQuantization::NoQuant => "NoQuant",
}
}
impl Clone for VAddOptions {
fn clone(&self) -> Self {
Self {
reduce_dim: self.reduce_dim,
cas: self.cas,
m: self.m,
ef: self.ef,
quant: self.quant.as_ref().map(copy_quant),
}
}
}
impl std::fmt::Debug for VAddOptions {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("VAddOptions")
.field("reduce_dim", &self.reduce_dim)
.field("cas", &self.cas)
.field("m", &self.m)
.field("ef", &self.ef)
.field("quant", &self.quant.as_ref().map(quant_label))
.finish()
}
}
pub enum QueryTarget {
Element(String),
Values(Vec<f32>),
}
pub struct VectorQuery {
target: QueryTarget,
count: Option<u64>,
ef: Option<u64>,
filter: Option<String>,
filter_ef: Option<u64>,
withscores: bool,
nothread: bool,
truth: bool,
}
impl VectorQuery {
pub fn by_element(element: impl Into<String>) -> Self {
Self::with_target(QueryTarget::Element(element.into()))
}
pub fn by_vector(vector: Vec<f32>) -> Self {
Self::with_target(QueryTarget::Values(vector))
}
fn with_target(target: QueryTarget) -> Self {
Self {
target,
count: None,
ef: None,
filter: None,
filter_ef: None,
withscores: false,
nothread: false,
truth: false,
}
}
pub fn count(mut self, n: u64) -> Self {
self.count = Some(n);
self
}
pub fn ef(mut self, n: u64) -> Self {
self.ef = Some(n);
self
}
pub fn filter(mut self, expr: impl Into<String>) -> Self {
self.filter = Some(expr.into());
self
}
pub fn filter_ef(mut self, n: u64) -> Self {
self.filter_ef = Some(n);
self
}
pub fn withscores(mut self) -> Self {
self.withscores = true;
self
}
pub fn nothread(mut self) -> Self {
self.nothread = true;
self
}
pub fn truth(mut self) -> Self {
self.truth = true;
self
}
}
pub struct VectorSetClient<'a, C> {
key: String,
conn: &'a mut C,
}
impl<'a, C: RedisExecutor> VectorSetClient<'a, C> {
pub fn new(conn: &'a mut C, key: impl Into<String>) -> Self {
Self {
key: key.into(),
conn,
}
}
pub async fn add(
&mut self,
vector: Vec<f32>,
element: impl Into<String>,
) -> Result<bool, RedisError> {
self.conn
.execute(VAdd::new(self.key.clone(), vector, element.into()))
.await
}
pub async fn add_with_options(
&mut self,
vector: Vec<f32>,
element: impl Into<String>,
options: VAddOptions,
) -> Result<bool, RedisError> {
let mut cmd = VAdd::new(self.key.clone(), vector, element.into());
if let Some(dim) = options.reduce_dim {
cmd = cmd.reduce(dim);
}
if options.cas {
cmd = cmd.cas();
}
if let Some(m) = options.m {
cmd = cmd.m(m);
}
if let Some(ef) = options.ef {
cmd = cmd.ef(ef);
}
if let Some(quant) = options.quant {
cmd = cmd.quant(quant);
}
self.conn.execute(cmd).await
}
pub async fn remove(&mut self, element: &str) -> Result<bool, RedisError> {
self.conn
.execute(VRem::new(self.key.clone(), element))
.await
}
pub async fn search(
&mut self,
query: VectorQuery,
) -> Result<Vec<SimilarityResult>, RedisError> {
let mut cmd = match query.target {
QueryTarget::Element(element) => VSim::by_element(self.key.clone(), element),
QueryTarget::Values(vector) => VSim::by_values(self.key.clone(), vector),
};
if let Some(n) = query.count {
cmd = cmd.count(n);
}
if let Some(n) = query.ef {
cmd = cmd.ef(n);
}
if let Some(expr) = query.filter {
cmd = cmd.filter(expr);
}
if let Some(n) = query.filter_ef {
cmd = cmd.filter_ef(n);
}
if query.withscores {
cmd = cmd.withscores();
}
if query.nothread {
cmd = cmd.nothread();
}
if query.truth {
cmd = cmd.truth();
}
let raw = self.conn.execute(cmd).await?;
Ok(to_results(raw))
}
pub async fn embedding(&mut self, element: &str) -> Result<Vec<f64>, RedisError> {
self.conn
.execute(VEmb::new(self.key.clone(), element))
.await
}
pub async fn links(&mut self, element: &str) -> Result<Vec<SimilarityResult>, RedisError> {
let raw = self
.conn
.execute(VLinks::new(self.key.clone(), element).withscores())
.await?;
Ok(to_results(raw))
}
pub async fn random(&mut self, count: Option<i64>) -> Result<Vec<String>, RedisError> {
let mut cmd = VRandMember::new(self.key.clone());
if let Some(n) = count {
cmd = cmd.count(n);
}
let raw = self.conn.execute(cmd).await?;
Ok(raw
.into_iter()
.map(|b| String::from_utf8_lossy(&b).into_owned())
.collect())
}
pub async fn set_attr(&mut self, element: &str, json: &str) -> Result<bool, RedisError> {
self.conn
.execute(VSetAttr::new(self.key.clone(), element, json))
.await
}
pub async fn get_attr(&mut self, element: &str) -> Result<Option<String>, RedisError> {
self.conn
.execute(VGetAttr::new(self.key.clone(), element))
.await
}
pub async fn del_attr(&mut self, element: &str) -> Result<bool, RedisError> {
self.conn
.execute(VDelAttr::new(self.key.clone(), element))
.await
}
pub async fn cardinality(&mut self) -> Result<i64, RedisError> {
self.conn.execute(VCard::new(self.key.clone())).await
}
pub async fn dimensions(&mut self) -> Result<i64, RedisError> {
self.conn.execute(VDim::new(self.key.clone())).await
}
pub async fn info(&mut self) -> Result<VectorSetInfo, RedisError> {
let frames = self.conn.execute(VInfo::new(self.key.clone())).await?;
Ok(parse_info(frames))
}
#[cfg(feature = "serde")]
pub async fn set_attr_typed<T: serde::Serialize>(
&mut self,
element: &str,
attr: &T,
) -> Result<bool, RedisError> {
let json = serde_json::to_string(attr)
.map_err(|e| RedisError::Redis(format!("JSON serialization error: {e}")))?;
self.set_attr(element, &json).await
}
#[cfg(feature = "serde")]
pub async fn get_attr_typed<T: serde::de::DeserializeOwned>(
&mut self,
element: &str,
) -> Result<Option<T>, RedisError> {
match self.get_attr(element).await? {
None => Ok(None),
Some(json) => {
let value = serde_json::from_str(&json)
.map_err(|e| RedisError::Redis(format!("JSON deserialize error: {e}")))?;
Ok(Some(value))
}
}
}
}
fn to_results<B: AsRef<[u8]>>(raw: Vec<(B, Option<f64>)>) -> Vec<SimilarityResult> {
raw.into_iter()
.map(|(name, score)| SimilarityResult {
element: String::from_utf8_lossy(name.as_ref()).into_owned(),
score,
})
.collect()
}
fn parse_info(frames: Vec<Frame>) -> VectorSetInfo {
let mut info = VectorSetInfo::default();
let mut iter = frames.into_iter();
while let Some(key_frame) = iter.next() {
let Some(value_frame) = iter.next() else {
break;
};
let Some(key) = frame_to_string(&key_frame) else {
continue;
};
match key.as_str() {
"quant-type" | "quant_type" => {
if let Some(s) = frame_to_string(&value_frame) {
info.quant_type = s;
}
}
"vector-dim" | "vector_dim" => {
if let Some(n) = frame_to_i64(&value_frame) {
info.vector_dim = n;
}
}
"size" => {
if let Some(n) = frame_to_i64(&value_frame) {
info.size = n;
}
}
"max-node-uid" | "max_node_uid" => {
if let Some(n) = frame_to_i64(&value_frame) {
info.max_node_uid = n;
}
}
"vset-uid" | "vset_uid" => {
if let Some(n) = frame_to_i64(&value_frame) {
info.vset_uid = n;
}
}
_ => {}
}
}
info
}
fn frame_to_string(frame: &Frame) -> Option<String> {
match frame {
Frame::BulkString(Some(b)) => Some(String::from_utf8_lossy(b).into_owned()),
Frame::SimpleString(b) => Some(String::from_utf8_lossy(b).into_owned()),
_ => None,
}
}
fn frame_to_i64(frame: &Frame) -> Option<i64> {
match frame {
Frame::Integer(n) => Some(*n),
Frame::Double(d) => Some(*d as i64),
Frame::BulkString(Some(b)) => String::from_utf8_lossy(b).parse().ok(),
Frame::SimpleString(b) => String::from_utf8_lossy(b).parse().ok(),
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
use bytes::Bytes;
use redis_tower_core::Command;
use std::collections::VecDeque;
use std::future::Future;
struct MockRedis {
responses: VecDeque<Frame>,
}
impl MockRedis {
fn new(responses: Vec<Frame>) -> Self {
Self {
responses: VecDeque::from(responses),
}
}
}
impl RedisExecutor for MockRedis {
fn execute<Cmd: Command>(
&mut self,
cmd: Cmd,
) -> impl Future<Output = Result<Cmd::Response, RedisError>> + Send {
let frame = self.responses.pop_front().unwrap_or(Frame::Null);
async move { cmd.parse_response(frame) }
}
}
fn bulk(s: &str) -> Frame {
Frame::BulkString(Some(Bytes::from(s.to_string())))
}
#[tokio::test]
async fn add_returns_true_when_added() {
let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let added = vset.add(vec![1.0, 2.0, 3.0], "a").await.unwrap();
assert!(added);
}
#[tokio::test]
async fn add_returns_false_when_updated() {
let mut mock = MockRedis::new(vec![Frame::Integer(0)]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let added = vset.add(vec![1.0, 2.0, 3.0], "a").await.unwrap();
assert!(!added);
}
#[tokio::test]
async fn remove_returns_true_when_removed() {
let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
let mut vset = VectorSetClient::new(&mut mock, "k");
assert!(vset.remove("a").await.unwrap());
}
#[tokio::test]
async fn search_without_scores() {
let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![bulk("a"), bulk("b")]))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let results = vset
.search(VectorQuery::by_vector(vec![1.0, 0.0, 0.0]))
.await
.unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].element, "a");
assert_eq!(results[0].score, None);
assert_eq!(results[1].element, "b");
assert_eq!(results[1].score, None);
}
#[tokio::test]
async fn search_with_scores() {
let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
bulk("a"),
bulk("0.99"),
bulk("b"),
bulk("0.50"),
]))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let results = vset
.search(VectorQuery::by_vector(vec![1.0, 0.0, 0.0]).withscores())
.await
.unwrap();
assert_eq!(results.len(), 2);
assert_eq!(results[0].element, "a");
assert_eq!(results[0].score, Some(0.99));
assert_eq!(results[1].element, "b");
assert_eq!(results[1].score, Some(0.50));
}
#[tokio::test]
async fn embedding_returns_floats() {
let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
bulk("1.5"),
bulk("2.5"),
bulk("3.5"),
]))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let emb = vset.embedding("a").await.unwrap();
assert_eq!(emb, vec![1.5, 2.5, 3.5]);
}
#[tokio::test]
async fn cardinality_returns_count() {
let mut mock = MockRedis::new(vec![Frame::Integer(3)]);
let mut vset = VectorSetClient::new(&mut mock, "k");
assert_eq!(vset.cardinality().await.unwrap(), 3);
}
#[tokio::test]
async fn info_parses_flat_kv() {
let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![
bulk("quant-type"),
bulk("int8"),
bulk("vector-dim"),
Frame::Integer(3),
bulk("size"),
Frame::Integer(42),
bulk("max-node-uid"),
Frame::Integer(7),
bulk("vset-uid"),
Frame::Integer(9),
]))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let info = vset.info().await.unwrap();
assert_eq!(info.quant_type, "int8");
assert_eq!(info.vector_dim, 3);
assert_eq!(info.size, 42);
assert_eq!(info.max_node_uid, 7);
assert_eq!(info.vset_uid, 9);
}
#[tokio::test]
async fn random_returns_strings() {
let mut mock = MockRedis::new(vec![Frame::Array(Some(vec![bulk("a"), bulk("b")]))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
let members = vset.random(Some(2)).await.unwrap();
assert_eq!(members, vec!["a".to_string(), "b".to_string()]);
}
#[tokio::test]
async fn get_attr_returns_none_for_null() {
let mut mock = MockRedis::new(vec![Frame::Null]);
let mut vset = VectorSetClient::new(&mut mock, "k");
assert_eq!(vset.get_attr("a").await.unwrap(), None);
}
#[tokio::test]
async fn get_attr_returns_string() {
let mut mock = MockRedis::new(vec![Frame::BulkString(Some(Bytes::from("{\"x\":1}")))]);
let mut vset = VectorSetClient::new(&mut mock, "k");
assert_eq!(
vset.get_attr("a").await.unwrap(),
Some("{\"x\":1}".to_string())
);
}
#[tokio::test]
async fn del_attr_returns_true_on_success() {
let mut mock = MockRedis::new(vec![Frame::Integer(1)]);
let mut vset = VectorSetClient::new(&mut mock, "k");
assert!(vset.del_attr("a").await.unwrap());
}
}