redis-vl

Rust implementation of the Redis Vector Library, providing vector search, semantic caching, message history, and routing on top of Redis.

Status: pre-release (0.1.2). The library is functional for core workflows but has not yet reached full parity with the Python redisvl package. See the Parity Matrix for current coverage.

Features

• Schema – define index schemas in YAML or JSON with typed field attributes (Tag, Text, Numeric, Geo, Timestamp, Vector), stopwords, multi-prefix support, and Hash/JSON storage selection.
• Search Index – sync and async index lifecycle: create, delete, load, fetch, search, query, batch operations, pagination, hybrid search, aggregate queries, multi-vector queries, and from_existing.
• Filters – composable filter DSL: Tag, Text, Num, Geo, GeoRadius, Timestamp with boolean composition (&, |, !).
• Queries – VectorQuery, VectorRangeQuery, TextQuery, FilterQuery, CountQuery, HybridQuery (Redis 8.4+ FT.HYBRID), AggregateHybridQuery (FT.AGGREGATE), and MultiVectorQuery.
• SQL Queries – SQLQuery behind the sql feature flag: translates SQL SELECT statements to Redis Search queries with WHERE, ORDER BY, LIMIT/OFFSET, field projection, aggregate functions (COUNT, SUM, AVG, GROUP BY), vector search functions (vector_distance(), cosine_distance()), and geo functions (geo_distance() in WHERE and SELECT clauses).
• Vectorizers – OpenAITextVectorizer, LiteLLMTextVectorizer, CustomTextVectorizer, AzureOpenAITextVectorizer, CohereTextVectorizer, VoyageAITextVectorizer, MistralAITextVectorizer, VertexAITextVectorizer, BedrockTextVectorizer, AnthropicTextVectorizer (Voyage AI-backed), and HuggingFaceTextVectorizer (local ONNX via fastembed).
• Rerankers – CohereReranker behind the rerankers feature flag with sync and async support.
• Extensions – EmbeddingsCache, SemanticCache, MessageHistory, SemanticMessageHistory, and SemanticRouter, all Redis-backed.
• CLI (rvl) – version, index create/delete/destroy/info/listall, and stats commands.
• Benchmarks – Criterion micro-benchmarks for schema parsing, filter rendering, query building, and Redis-backed index/search/cache operations.

Not yet implemented

• SQL date functions (YEAR()), IS NULL/IS NOT NULL, HAVING
• Richer CLI command/flag parity (load, query commands)

Quick start

Add redis-vl to your project:

cargo add redis-vl

To use only the core library without vectorizer dependencies:

cargo add redis-vl --no-default-features

Defining a schema (YAML)

index:
  name: my-index
  prefix: doc
  storage_type: hash
fields:
  - name: title
    type: tag
  - name: content
    type: text
  - name: score
    type: numeric
  - name: embedding
    type: vector
    attrs:
      algorithm: flat
      dims: 128
      distance_metric: cosine
      datatype: float32

Creating an index and loading data

use redis_vl::{IndexSchema, SearchIndex};
use serde_json::json;

let schema = IndexSchema::from_yaml_file("schema.yaml").unwrap();
let index = SearchIndex::new(schema, "redis://127.0.0.1:6379");
index.create().unwrap();

let docs = vec![
    json!({"id": "doc:1", "title": "first", "content": "hello world", "score": 42, "embedding": vec![0.1_f32; 128]}),
];
index.load(&docs, "id", None).unwrap();

Running a vector query

use redis_vl::{SearchIndex, IndexSchema, Vector, VectorQuery};

let schema = IndexSchema::from_yaml_file("schema.yaml").unwrap();
let index = SearchIndex::new(schema, "redis://127.0.0.1:6379");

let vector = Vector::new(&[0.1_f32; 128] as &[f32]);
let query = VectorQuery::new(vector, "embedding", 5)
    .with_return_fields(["title", "score"]);
let result = index.search(&query).unwrap();

println!("Found {} documents", result.total);
for doc in &result.docs {
    println!("  {} (score: {})", doc["title"], doc["vector_distance"]);
}

Composing filters

use redis_vl::filter::{Tag, Num, Text};

// Combine with & (AND), | (OR), and ! (NOT)
let filter = Tag::new("color").eq("red")
    & Num::new("price").between(10.0, 100.0, redis_vl::BetweenInclusivity::Both);

let text_filter = Text::new("description").eq("premium")
    | Text::new("description").eq("luxury");

Message history

use redis_vl::{MessageHistory, Message, MessageRole};

let history = MessageHistory::new("session-1", "redis://127.0.0.1:6379");
history.add_message(Message::new(MessageRole::User, "Hello!")).unwrap();
history.add_message(Message::new(MessageRole::Llm, "Hi there!")).unwrap();

let recent = history.get_recent(10, None).unwrap();
for msg in &recent {
    println!("[{:?}] {}", msg.role, msg.content);
}

Semantic router

use redis_vl::{SemanticRouter, Route, RoutingConfig};

let routes = vec![
    Route::new("greeting", vec!["hello".into(), "hi".into(), "hey".into()]),
    Route::new("farewell", vec!["goodbye".into(), "bye".into(), "see you".into()]),
];

// Create with a vectorizer:
// let router = SemanticRouter::new(vectorizer, routes, "my-router", "redis://...", RoutingConfig::default());
// let result = router.route(Some("howdy!"), None).unwrap();

Redis 8.4+ hybrid search

Redis 8.4 introduces FT.HYBRID for combined text + vector search:

use redis_vl::query::{HybridQuery, HybridCombinationMethod, Vector};

let query = HybridQuery::new(
    "medical professional", "description",
    Vector::new(vec![0.1, 0.1, 0.5]), "user_embedding",
)
.with_num_results(10)
.with_combination_method(HybridCombinationMethod::Rrf)
.with_return_fields(["user", "age", "job"]);

Note: Hybrid and multi-vector queries require Redis 8.4+. See the user guide for AggregateHybridQuery and MultiVectorQuery details.

CLI

Install the rvl binary:

cargo install --path crates/rvl

rvl version
rvl index create --schema schema.yaml
rvl index info --schema schema.yaml
rvl index listall --schema schema.yaml
rvl index delete --schema schema.yaml
rvl index destroy --schema schema.yaml   # alias for delete
rvl stats --schema schema.yaml

Set REDIS_URL or pass --redis-url to override the default redis://127.0.0.1:6379.

Feature flags

Examples

See the examples/ directory for runnable code samples:

cargo run -p redis-vl --example schema_basics
cargo run -p redis-vl --example vector_search        # requires Redis
cargo run -p redis-vl --features sql --example sql_query_basics

Benchmarks

Criterion micro-benchmarks cover schema parsing, filter rendering, query building, and Redis-backed operations (index lifecycle, search, cache, history).

cargo bench -p redis-vl                                # pure-Rust benchmarks
REDISVL_RUN_INTEGRATION=1 cargo bench -p redis-vl     # includes Redis-backed benchmarks

See benches/README.md for the full benchmark inventory.

Development

cargo fmt --all
cargo clippy --workspace --all-targets --all-features
cargo test --workspace --all-features

Integration tests require a running Redis instance with the Search module (Redis 8+ or Redis Stack):

REDISVL_RUN_INTEGRATION=1 cargo test --workspace

Redis 8.4+ hybrid/aggregate/multi-vector tests additionally require a Redis 8.4 server.

Release Flow

Normal pull requests and pushes run verification only. Publishing is triggered by pushing a version tag that matches Cargo.toml:

git tag v0.1.2
git push origin v0.1.2

The tag workflow publishes redis-vl, waits for crates.io indexing, publishes rvl, creates the GitHub Release, and then builds cross-platform rvl binaries for the release. See PUBLISHING.md for the maintainer runbook.

Documentation

• API Reference (docs.rs) – auto-generated Rustdoc
• User Guide (mdBook) – getting started, schema, queries, extensions, CLI
• Parity Matrix – feature-level tracking against Python RedisVL
• Publishing Guide – crates.io, docs, and release workflow notes

License

MIT - see the LICENSE file for details.