Redis
redis-vl-dotnet Documentation redis-vl-dotnet

redis-vl-dotnet

Getting Started

This section is the canonical entry point for installation, local Redis setup, connection environment variables, and the first end-to-end workflow.

Prerequisites

The current local development flow assumes:

  • .NET 9 SDK

  • Redis 8 or another Redis deployment with the Query Engine (RediSearch) enabled

  • JSON support for JSON-backed examples and document workflows

  • Docker Desktop or another Docker-compatible runtime when you want the repository-managed local Redis instance

  • A reachable Redis connection string such as localhost:6379

Default local setup

Start Redis locally from the repository root:

docker compose -f docker-compose.integration.yml up -d redis
export REDIS_VL_REDIS_URL=localhost:6379

Install and validate the docs plus example toolchain from the repository root:

dotnet --version
npm install
npm run docs:validate
npm run examples:build

Run the first end-to-end example:

dotnet run --project examples/JsonStorageExample/JsonStorageExample.csproj

Connection environment variables

The examples and tests use environment variables so the same commands work across local and cluster deployments.

Variable Required when Purpose

REDIS_VL_REDIS_URL

Direct connection flow

Standalone Redis endpoint. The examples fall back to localhost:6379 when this is unset.

REDIS_VL_REDIS_CLUSTER_NODES

Cluster flow

Comma-delimited Redis cluster seed nodes such as 127.0.0.1:7000,127.0.0.1:7001.

REDIS_VL_REDIS_USER

Authenticated cluster flow

Redis username forwarded through the connection factory helpers.

REDIS_VL_REDIS_PASSWORD

Authenticated cluster flow

Redis password forwarded through the connection factory helpers.

REDIS_VL_REDIS_SSL

TLS-enabled cluster flow

Set to true when the target deployment requires TLS.

Copy-paste connection setup

Use only one topology block at a time.

Direct local Redis

docker compose -f docker-compose.integration.yml up -d redis
export REDIS_VL_REDIS_URL=localhost:6379
dotnet run --project examples/JsonStorageExample/JsonStorageExample.csproj

Redis cluster

unset REDIS_VL_REDIS_URL
export REDIS_VL_REDIS_CLUSTER_NODES=127.0.0.1:7000,127.0.0.1:7001,127.0.0.1:7002
export REDIS_VL_REDIS_USER=default
export REDIS_VL_REDIS_PASSWORD=secret
export REDIS_VL_REDIS_SSL=false
dotnet run --project examples/JsonStorageExample/JsonStorageExample.csproj

First workflow

The minimal library flow is:

  1. Add the library to an app

  2. Connect to Redis

  3. Define a schema

  4. Create an index

  5. Load documents

  6. Fetch and query documents

  7. Clear or drop the index when finished

The current canonical walkthrough for that sequence still starts from the JSON example and the runnable examples catalog:

  • Examples maps the main feature areas to concrete sample projects

  • /examples/JsonStorageExample demonstrates schema creation, document loading, fetch, filter search, text search, aggregations, count, clear, and drop flows

Connection topologies

Use RedisConnectionFactory when you need StackExchange.Redis ConfigurationOptions helpers for more than a direct endpoint:

  • cluster discovery through ConnectClusterAsync(…​)

  • parsed option creation through CreateClusterOptions(…​)

These helpers normalize seed-node lists, reject unsupported configuration early, and keep the rest of the library on the same IDatabase-based APIs.

Provider environment variables

Provider-backed examples add service credentials on top of the Redis connection variables:

Variable Used by

OPENAI_API_KEY

/examples/OpenAiVectorizerExample

OPENAI_EMBEDDING_MODEL

Optional override for the OpenAI example embedding model. Defaults to text-embedding-3-small.

OPENAI_EMBEDDING_DIMENSIONS

Optional override for the OpenAI example embedding size. Defaults to 256.

HF_TOKEN

/examples/HuggingFaceVectorizerExample

COHERE_API_KEY

/examples/CohereRerankerExample

If those credentials are missing, the provider-backed examples and matching integration tests fail fast with an explicit environment-variable message instead of attempting a partially configured request.

Related sections

  • Core Features for schema, index, document, and query coverage

  • Examples for runnable sample projects

  • Testing for local validation commands and Redis-backed test setup