Semantic Router

Overview

Semantic Router

`class SemanticRouter(name, routes, vectorizer=None, routing_config=None, redis_client=None, redis_url='redis://localhost:6379', overwrite=False, connection_kwargs={})`

Semantic Router for managing and querying route vectors.

Initialize the SemanticRouter.

* **Parameters:**
  * **name** (*str*) – The name of the semantic router.
  * **routes** (*List* *[*[Route](#route) *]*) – List of Route objects.
  * **vectorizer** (*BaseVectorizer* *,* *optional*) – The vectorizer used to embed route references. Defaults to default HFTextVectorizer.
  * **routing_config** ([RoutingConfig](#routingconfig) *,* *optional*) – Configuration for routing behavior. Defaults to the default RoutingConfig.
  * **redis_client** (*Optional* *[* *SyncRedisClient* *]* *,* *optional*) – Redis client for connection. Defaults to None.
  * **redis_url** (*str* *,* *optional*) – The redis url. Defaults to redis://localhost:6379.
  * **overwrite** (*bool* *,* *optional*) – Whether to overwrite existing index. Defaults to False.
  * **connection_kwargs** (*Dict* *[* *str* *,* *Any* *]*) – The connection arguments
    for the redis client. Defaults to empty {}.

#### `add_route_references(route_name, references)`

Add a reference(s) to an existing route.

* **Parameters:**
  * **router_name** (*str*) – The name of the router.
  * **references** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The reference or list of references to add.
  * **route_name** (*str*)
* **Returns:**
  The list of added references keys.
* **Return type:**
  List[str]

#### `clear()`

Flush all routes from the semantic router index.

* **Return type:**
  None

#### `delete()`

Delete the semantic router index.

* **Return type:**
  None

#### `delete_route_references(route_name='', reference_ids=[], keys=[])`

Get references for an existing semantic router route.

* **Parameters:**
  * **Optional** (*keys*) – The name of the router.
  * **Optional** – The reference or list of references to delete.
  * **Optional** – List of fully qualified keys (prefix:router:reference_id) to delete.
  * **route_name** (*str*)
  * **reference_ids** (*List* *[* *str* *]*)
  * **keys** (*List* *[* *str* *]*)
* **Returns:**
  Number of objects deleted
* **Return type:**
  int

#### `classmethod from_dict(data, **kwargs)`

Create a SemanticRouter from a dictionary.

* **Parameters:**
  **data** (*Dict* *[* *str* *,* *Any* *]*) – The dictionary containing the semantic router data.
* **Returns:**
  The semantic router instance.
* **Return type:**
  [SemanticRouter](#semanticrouter)
* **Raises:**
  **ValueError** – If required data is missing or invalid.

[code example]

#### `classmethod from_existing(name, redis_client=None, redis_url='redis://localhost:6379', **kwargs)`

Return SemanticRouter instance from existing index.

* **Parameters:**
  * **name** (*str*)
  * **redis_client** (*Redis* *|* *RedisCluster* *|* *None*)
  * **redis_url** (*str*)
* **Return type:**
  [SemanticRouter](#semanticrouter)

#### `classmethod from_yaml(file_path, **kwargs)`

Create a SemanticRouter from a YAML file.

* **Parameters:**
  **file_path** (*str*) – The path to the YAML file.
* **Returns:**
  The semantic router instance.
* **Return type:**
  [SemanticRouter](#semanticrouter)
* **Raises:**
  * **ValueError** – If the file path is invalid.
  * **FileNotFoundError** – If the file does not exist.

[code example]

#### `get(route_name)`

Get a route by its name.

* **Parameters:**
  **route_name** (*str*) – Name of the route.
* **Returns:**
  The selected Route object or None if not found.
* **Return type:**
  Optional[[Route](#route)]

#### `get_route_references(route_name='', reference_ids=[], keys=[])`

Get references for an existing route route.

* **Parameters:**
  * **router_name** (*str*) – The name of the router.
  * **references** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The reference or list of references to add.
  * **route_name** (*str*)
  * **reference_ids** (*List* *[* *str* *]*)
  * **keys** (*List* *[* *str* *]*)
* **Returns:**
  Reference objects stored
* **Return type:**
  List[Dict[str, Any]]]

#### `model_post_init(context, /)`

This function is meant to behave like a BaseModel method to initialise private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

* **Parameters:**
  * **self** (*BaseModel*) – The BaseModel instance.
  * **context** (*Any*) – The context.
* **Return type:**
  None

#### `remove_route(route_name)`

Remove a route and all references from the semantic router.

* **Parameters:**
  **route_name** (*str*) – Name of the route to remove.
* **Return type:**
  None

#### `route_many(statement=None, vector=None, max_k=None, distance_threshold=None, aggregation_method=None)`

Query the semantic router with a given statement or vector for multiple matches.

* **Parameters:**
  * **statement** (*Optional* *[* *str* *]*) – The input statement to be queried.
  * **vector** (*Optional* *[* *List* *[* *float* *]* *]*) – The input vector to be queried.
  * **max_k** (*Optional* *[* *int* *]*) – The maximum number of top matches to return.
  * **distance_threshold** (*Optional* *[* *float* *]*) – The threshold for semantic distance.
  * **aggregation_method** (*Optional* *[*[DistanceAggregationMethod](#distanceaggregationmethod) *]*) – The aggregation method used for vector distances.
* **Returns:**
  The matching routes and their details.
* **Return type:**
  List[[RouteMatch](#routematch)]

#### `to_dict()`

Convert the SemanticRouter instance to a dictionary.

* **Returns:**
  The dictionary representation of the SemanticRouter.
* **Return type:**
  Dict[str, Any]

[code example]

#### `to_yaml(file_path, overwrite=True)`

Write the semantic router to a YAML file.

* **Parameters:**
  * **file_path** (*str*) – The path to the YAML file.
  * **overwrite** (*bool*) – Whether to overwrite the file if it already exists.
* **Raises:**
  **FileExistsError** – If the file already exists and overwrite is False.
* **Return type:**
  None

[code example]

#### `update_route_thresholds(route_thresholds)`

Update the distance thresholds for each route.

* **Parameters:**
  **route_thresholds** (*Dict* *[* *str* *,* *float* *]*) – Dictionary of route names and their distance thresholds.

#### `update_routing_config(routing_config)`

Update the routing configuration.

* **Parameters:**
  **routing_config** ([RoutingConfig](#routingconfig)) – The new routing configuration.

#### `model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `name: str`

The name of the semantic router.

#### `property route_names: List[str]`

Get the list of route names.

* **Returns:**
  List of route names.
* **Return type:**
  List[str]

#### `property route_thresholds: Dict[str, float | None]`

Get the distance thresholds for each route.

* **Returns:**
  Dictionary of route names and their distance thresholds.
* **Return type:**
  Dict[str, float]

#### `routes: `List[[Route](#route)]

List of Route objects.

#### `routing_config: `[RoutingConfig](#routingconfig)

Configuration for routing behavior.

#### `vectorizer: BaseVectorizer`

The vectorizer used to embed route references.

Routing Config

`class RoutingConfig(*, max_k=1, aggregation_method=DistanceAggregationMethod.avg)`

Configuration for routing behavior.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **max_k** (*Annotated* *[* *int* *,* *FieldInfo* *(* *annotation=NoneType* *,* *required=True* *,* *metadata=* *[* *Strict* *(* *strict=True* *)* *,* *Gt* *(* *gt=0* *)* *]* *)* *]*)
  * **aggregation_method** ([DistanceAggregationMethod](#distanceaggregationmethod))

#### `max_k: Annotated[int, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Gt(gt=0)])]`

Aggregation method to use to classify queries.

#### `model_config: ClassVar[ConfigDict] = {'extra': 'ignore'}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Route

`class Route(*, name, references, metadata={}, distance_threshold=0.5)`

Model representing a routing path with associated metadata and thresholds.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **references** (*List* *[* *str* *]*)
  * **metadata** (*Dict* *[* *str* *,* *Any* *]*)
  * **distance_threshold** (*Annotated* *[* *float* *,* *FieldInfo* *(* *annotation=NoneType* *,* *required=True* *,* *metadata=* *[* *Strict* *(* *strict=True* *)* *,* *Gt* *(* *gt=0* *)* *,* *Le* *(* *le=2* *)* *]* *)* *]*)

#### `distance_threshold: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Strict(strict=True), Gt(gt=0), Le(le=2)])]`

Distance threshold for matching the route.

#### `metadata: Dict[str, Any]`

Metadata associated with the route.

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `name: str`

The name of the route.

#### `references: List[str]`

List of reference phrases for the route.

Route Match

`class RouteMatch(*, name=None, distance=None)`

Model representing a matched route with distance information.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str* *|* *None*)
  * **distance** (*float* *|* *None*)

#### `distance: float | None`

The vector distance between the statement and the matched route.

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `name: str | None`

The matched route name.

Distance Aggregation Method

`class DistanceAggregationMethod(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)`

Enumeration for distance aggregation methods.

#### `avg = 'avg'`

Compute the average of the vector distances.

#### `min = 'min'`

Compute the minimum of the vector distances.

#### `sum = 'sum'`

Compute the sum of the vector distances.

from redisvl.extensions.router import SemanticRouter
router_data = {
    "name": "example_router",
    "routes": [{"name": "route1", "references": ["ref1"], "distance_threshold": 0.5}],
    "vectorizer": {"type": "openai", "model": "text-embedding-ada-002"},
}
router = SemanticRouter.from_dict(router_data)

from redisvl.extensions.router import SemanticRouter
router = SemanticRouter.from_yaml("router.yaml", redis_url="redis://localhost:6379")

from redisvl.extensions.router import SemanticRouter
router = SemanticRouter(name="example_router", routes=[], redis_url="redis://localhost:6379")
router_dict = router.to_dict()

from redisvl.extensions.router import SemanticRouter
router = SemanticRouter(
    name="example_router",
    routes=[],
    redis_url="redis://localhost:6379"
)
router.to_yaml("router.yaml")


Schema

Overview

Schema in RedisVL provides a structured format to define index settings and
field configurations using the following three components:

| Component   | Description                                                                        |
|-------------|------------------------------------------------------------------------------------|
| version     | The version of the schema spec. Current supported version is 0.1.0.                |
| index       | Index specific settings like name, key prefix, key separator, and storage type.    |
| fields      | Subset of fields within your data to include in the index and any custom settings. |

IndexSchema

`class IndexSchema(*, index, fields=<factory>, version='0.1.0')`

A schema definition for a search index in Redis, used in RedisVL for
configuring index settings and organizing vector and metadata fields.

The class offers methods to create an index schema from a YAML file or a
Python dictionary, supporting flexible schema definitions and easy
integration into various workflows.

An example schema.yaml file might look like this:

[code example]

Loading the schema for RedisVL from yaml is as simple as:

[code example]

Loading the schema for RedisVL from dict is as simple as:

[code example]

#### `NOTE`
The fields attribute in the schema must contain unique field names to ensure
correct and unambiguous field references.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **index** (*IndexInfo*)
  * **fields** (*Dict* *[* *str* *,* *BaseField* *]*)
  * **version** (*Literal* *[* *'0.1.0'* *]*)

#### `add_field(field_inputs)`

Adds a single field to the index schema based on the specified field
type and attributes.

This method allows for the addition of individual fields to the schema,
providing flexibility in defining the structure of the index.

* **Parameters:**
  **field_inputs** (*Dict* *[* *str* *,* *Any* *]*) – A field to add.
* **Raises:**
  **ValueError** – If the field name or type are not provided or if the name
      already exists within the schema.

[code example]

#### `add_fields(fields)`

Extends the schema with additional fields.

This method allows dynamically adding new fields to the index schema. It
processes a list of field definitions.

* **Parameters:**
  **fields** (*List* *[* *Dict* *[* *str* *,* *Any* *]* *]*) – A list of fields to add.
* **Raises:**
  **ValueError** – If a field with the same name already exists in the
      schema.

[code example]

#### `classmethod from_dict(data)`

Create an IndexSchema from a dictionary.

* **Parameters:**
  **data** (*Dict* *[* *str* *,* *Any* *]*) – The index schema data.
* **Returns:**
  The index schema.
* **Return type:**
  [IndexSchema](#indexschema)

[code example]

#### `classmethod from_yaml(file_path)`

Create an IndexSchema from a YAML file.

* **Parameters:**
  **file_path** (*str*) – The path to the YAML file.
* **Returns:**
  The index schema.
* **Return type:**
  [IndexSchema](#indexschema)

[code example]

#### `remove_field(field_name)`

Removes a field from the schema based on the specified name.

This method is useful for dynamically altering the schema by removing
existing fields.

* **Parameters:**
  **field_name** (*str*) – The name of the field to be removed.

#### `to_dict()`

Serialize the index schema model to a dictionary, handling Enums
and other special cases properly.

* **Returns:**
  The index schema as a dictionary.
* **Return type:**
  Dict[str, Any]

#### `to_yaml(file_path, overwrite=True)`

Write the index schema to a YAML file.

* **Parameters:**
  * **file_path** (*str*) – The path to the YAML file.
  * **overwrite** (*bool*) – Whether to overwrite the file if it already exists.
* **Raises:**
  **FileExistsError** – If the file already exists and overwrite is False.
* **Return type:**
  None

#### `property field_names: List[str]`

A list of field names associated with the index schema.

* **Returns:**
  A list of field names from the schema.
* **Return type:**
  List[str]

#### `fields: Dict[str, BaseField]`

Fields associated with the search index and their properties.

Note: When creating from dict/YAML, provide fields as a list of field definitions.
The validator will convert them to a Dict[str, BaseField] internally.

#### `index: IndexInfo`

Details of the basic index configurations.

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `version: Literal['0.1.0']`

Version of the underlying index schema.

Index-Level Stopwords Configuration

The `IndexInfo` class supports index-level stopwords configuration through
the `stopwords` field. This controls which words are filtered during indexing
(server-side), as opposed to query-time filtering (client-side).

**Configuration Options:**

- `None` (default): Use Redis default stopwords (~300 common words)
- `[]` (empty list): Disable stopwords completely (`STOPWORDS 0`)
- Custom list: Specify your own stopwords (e.g., `["the", "a", "an"]`)

**Example:**

[code example]

**Important Notes:**

- Index-level stopwords affect what gets indexed (server-side)
- Query-time stopwords (in `TextQuery` and `AggregateHybridQuery`) affect what gets searched (client-side)
- Using query-time stopwords with index-level `STOPWORDS 0` is counterproductive

For detailed information about stopwords configuration and best practices, see the
Advanced Queries user guide (`docs/user_guide/11_advanced_queries.ipynb`).

Defining Fields

Fields in the schema can be defined in YAML format or as a Python dictionary, specifying a name, type, an optional path, and attributes for customization.

**YAML Example**:

[code example]

**Python Dictionary Example**:

[code example]

Basic Field Types

RedisVL supports several basic field types for indexing different kinds of data. Each field type has specific attributes that customize its indexing and search behavior.

`Text Fields`

Text fields support full-text search with stemming, phonetic matching, and other text analysis features.

`class TextField(*, name, type=FieldTypes.TEXT, path=None, attrs=<factory>)`

Bases: `BaseField`

Text field supporting a full text search index

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.TEXT* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([TextFieldAttributes](#textfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[TextFieldAttributes](#textfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.TEXT]`

Field type

`class TextFieldAttributes(*, sortable=False, index_missing=False, no_index=False, weight=1, no_stem=False, withsuffixtrie=False, phonetic_matcher=None, index_empty=False, unf=False)`

Full text field attributes

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **sortable** (*bool*)
  * **index_missing** (*bool*)
  * **no_index** (*bool*)
  * **weight** (*float*)
  * **no_stem** (*bool*)
  * **withsuffixtrie** (*bool*)
  * **phonetic_matcher** (*str* *|* *None*)
  * **index_empty** (*bool*)
  * **unf** (*bool*)

#### `index_empty: bool`

Allow indexing and searching for empty strings

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `no_stem: bool`

Disable stemming on the text field during indexing

#### `phonetic_matcher: str | None`

Used to perform phonetic matching during search

#### `unf: bool`

Un-normalized form - disable normalization on sortable fields (only applies when sortable=True)

#### `weight: float`

Declares the importance of this field when calculating results

#### `withsuffixtrie: bool`

Keep a suffix trie with all terms which match the suffix to optimize certain queries

`Tag Fields`

Tag fields are optimized for exact-match filtering and faceted search on categorical data.

`class TagField(*, name, type=FieldTypes.TAG, path=None, attrs=<factory>)`

Bases: `BaseField`

Tag field for simple boolean-style filtering

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.TAG* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([TagFieldAttributes](#tagfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[TagFieldAttributes](#tagfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.TAG]`

Field type

`class TagFieldAttributes(*, sortable=False, index_missing=False, no_index=False, separator=',', case_sensitive=False, withsuffixtrie=False, index_empty=False)`

Tag field attributes

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **sortable** (*bool*)
  * **index_missing** (*bool*)
  * **no_index** (*bool*)
  * **separator** (*str*)
  * **case_sensitive** (*bool*)
  * **withsuffixtrie** (*bool*)
  * **index_empty** (*bool*)

#### `case_sensitive: bool`

Treat text as case sensitive or not. By default, tag characters are converted to lowercase

#### `index_empty: bool`

Allow indexing and searching for empty strings

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `separator: str`

Indicates how the text in the original attribute is split into individual tags

#### `withsuffixtrie: bool`

Keep a suffix trie with all terms which match the suffix to optimize certain queries

`Numeric Fields`

Numeric fields support range queries and sorting on numeric data.

`class NumericField(*, name, type=FieldTypes.NUMERIC, path=None, attrs=<factory>)`

Bases: `BaseField`

Numeric field for numeric range filtering

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.NUMERIC* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([NumericFieldAttributes](#numericfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[NumericFieldAttributes](#numericfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.NUMERIC]`

Field type

`class NumericFieldAttributes(*, sortable=False, index_missing=False, no_index=False, unf=False)`

Numeric field attributes

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **sortable** (*bool*)
  * **index_missing** (*bool*)
  * **no_index** (*bool*)
  * **unf** (*bool*)

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `unf: bool`

Un-normalized form - disable normalization on sortable fields (only applies when sortable=True)

`Geo Fields`

Geo fields enable location-based search with geographic coordinates.

`class GeoField(*, name, type=FieldTypes.GEO, path=None, attrs=<factory>)`

Bases: `BaseField`

Geo field with a geo-spatial index for location based search

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.GEO* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([GeoFieldAttributes](#geofieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[GeoFieldAttributes](#geofieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.GEO]`

Field type

`class GeoFieldAttributes(*, sortable=False, index_missing=False, no_index=False)`

Numeric field attributes

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **sortable** (*bool*)
  * **index_missing** (*bool*)
  * **no_index** (*bool*)

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Vector Field Types

Vector fields enable semantic similarity search using various algorithms. All vector fields share common attributes but have algorithm-specific configurations.

`Common Vector Attributes`

All vector field types share these base attributes:

`class BaseVectorFieldAttributes(*, dims, algorithm, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False)`

Base vector field attributes shared by FLAT, HNSW, and SVS-VAMANA fields

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **dims** (*int*)
  * **algorithm** (*VectorIndexAlgorithm*)
  * **datatype** (*VectorDataType*)
  * **distance_metric** (*VectorDistanceMetric*)
  * **initial_cap** (*int* *|* *None*)
  * **index_missing** (*bool*)

#### `classmethod uppercase_strings(v)`

Validate that provided values are cast to uppercase

#### `algorithm: VectorIndexAlgorithm`

FLAT, HNSW, or SVS-VAMANA

* **Type:**
  The indexing algorithm for the field

#### `datatype: VectorDataType`

The float datatype for the vector embeddings

#### `dims: int`

Dimensionality of the vector embeddings field

#### `distance_metric: VectorDistanceMetric`

The distance metric used to measure query relevance

#### `property field_data: Dict[str, Any]`

Select attributes required by the Redis API

#### `index_missing: bool`

Allow indexing and searching for missing values (documents without the field)

#### `initial_cap: int | None`

Initial vector capacity in the index affecting memory allocation size of the index

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

**Key Attributes:**

- dims: Dimensionality of the vector (e.g., 768, 1536).
- algorithm: Indexing algorithm for vector search:
  - flat: Brute-force exact search. 100% recall, slower for large datasets. Best for <10K vectors.
  - hnsw: Graph-based approximate search. Fast with high recall (95-99%). Best for general use.
  - svs-vamana: SVS-VAMANA (Scalable Vector Search with VAMANA graph algorithm) provides fast approximate nearest neighbor search with optional compression support. This algorithm is optimized for Intel hardware and offers reduced memory usage through vector compression.

  #### NOTE
  For detailed algorithm comparison and selection guidance, see [Vector Algorithm Comparison](#vector-algorithm-comparison).
- datatype: Float precision (bfloat16, float16, float32, float64). Note: SVS-VAMANA only supports float16 and float32.
- distance_metric: Similarity metric (COSINE, L2, IP).
- initial_cap: Initial capacity hint for memory allocation (optional).
- index_missing: When True, allows searching for documents missing this field (optional).

`HNSW Vector Fields`

HNSW (Hierarchical Navigable Small World) - Graph-based approximate search with excellent recall. **Best for general-purpose vector search (10K-1M+ vectors).**

`When to use HNSW & Performance Details`

**Use HNSW when:**

- Medium to large datasets (100K-1M+ vectors) requiring high recall rates
- Search accuracy is more important than memory usage
- Need general-purpose vector search with balanced performance
- Cross-platform deployments where hardware-specific optimizations aren’t available

**Performance characteristics:**

- **Search speed**: Very fast approximate search with tunable accuracy (via `ef_runtime` at query time)
- **Memory usage**: Higher than compressed SVS-VAMANA but reasonable for most applications
- **Recall quality**: Excellent recall rates (95-99%), tunable via `ef_runtime` parameter
- **Build time**: Moderate construction time, faster than SVS-VAMANA for smaller datasets

**Runtime parameters** (adjustable at query time without rebuilding index):

- `ef_runtime`: Controls search accuracy (higher = better recall, slower search). Default: 10
- `epsilon`: Range search approximation factor for VectorRangeQuery. Default: 0.01

`class HNSWVectorField(*, name, type='vector', path=None, attrs)`

Bases: `BaseField`

Vector field with HNSW (Hierarchical Navigable Small World) indexing for approximate nearest neighbor search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *'vector'* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([HNSWVectorFieldAttributes](#hnswvectorfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[HNSWVectorFieldAttributes](#hnswvectorfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal['vector']`

Field type

`class HNSWVectorFieldAttributes(*, dims, algorithm=VectorIndexAlgorithm.HNSW, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False, m=16, ef_construction=200, ef_runtime=10, epsilon=0.01)`

HNSW vector field attributes for approximate nearest neighbor search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **dims** (*int*)
  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.HNSW* *]*)
  * **datatype** (*VectorDataType*)
  * **distance_metric** (*VectorDistanceMetric*)
  * **initial_cap** (*int* *|* *None*)
  * **index_missing** (*bool*)
  * **m** (*int*)
  * **ef_construction** (*int*)
  * **ef_runtime** (*int*)
  * **epsilon** (*float*)

#### `algorithm: Literal[VectorIndexAlgorithm.HNSW]`

The indexing algorithm (fixed as ‘hnsw’)

#### `ef_construction: int`

100-800)

* **Type:**
  Max edge candidates during build time (default
* **Type:**
  200, range

#### `ef_runtime: int`

1. - primary tuning parameter

* **Type:**
  Max top candidates during search (default

#### `epsilon: float`

0.01)

* **Type:**
  Range search boundary factor (default

#### `m: int`

8-64)

* **Type:**
  Max outgoing edges per node in each layer (default
* **Type:**
  16, range

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

**HNSW Examples:**

**Balanced configuration (recommended starting point):**

[code example]

**High-recall configuration:**

[code example]

`SVS-VAMANA Vector Fields`

SVS-VAMANA (Scalable Vector Search with VAMANA graph algorithm) provides fast approximate nearest neighbor search with optional compression support. This algorithm is optimized for Intel hardware and offers reduced memory usage through vector compression. **Best for large datasets (>100K vectors) on Intel hardware with memory constraints.**

`When to use SVS-VAMANA & Detailed Guide`

**Requirements:**
: - Redis >= 8.2.0 with RediSearch >= 2.8.10
  - datatype must be ‘float16’ or ‘float32’ (float64/bfloat16 not supported)

**Use SVS-VAMANA when:**
: - Large datasets where memory is expensive
  - Cloud deployments with memory-based pricing
  - When 90-95% recall is acceptable
  - High-dimensional vectors (>1024 dims) with LeanVec compression

**Performance vs other algorithms:**
: - **vs FLAT**: Much faster search, significantly lower memory usage with compression, but approximate results
  - **vs HNSW**: Better memory efficiency with compression, similar or better recall, Intel-optimized

**Runtime parameters** (adjustable at query time without rebuilding index):

- `epsilon`: Range search approximation factor. Default: 0.01
- `search_window_size`: Size of search window for KNN searches. Higher = better recall, slower search
- `use_search_history`: Whether to use search buffer (OFF/ON/AUTO). Default: AUTO
- `search_buffer_capacity`: Tuning parameter for 2-level compression. Default: search_window_size

**Compression selection guide:**

- **No compression**: Best performance, standard memory usage
- **LVQ4/LVQ8**: Good balance of compression (2x-4x) and performance
- **LeanVec4x8/LeanVec8x8**: Maximum compression (up to 8x) with dimensionality reduction

**Memory Savings Examples (1M vectors, 768 dims):**
: - No compression (float32): 3.1 GB
  - LVQ4x4 compression: 1.6 GB (~48% savings)
  - LeanVec4x8 + reduce to 384: 580 MB (~81% savings)

`class SVSVectorField(*, name, type=FieldTypes.VECTOR, path=None, attrs)`

Bases: `BaseField`

Vector field with SVS-VAMANA indexing and compression for memory-efficient approximate nearest neighbor search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.VECTOR* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([SVSVectorFieldAttributes](#svsvectorfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[SVSVectorFieldAttributes](#svsvectorfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.VECTOR]`

Field type

`class SVSVectorFieldAttributes(*, dims, algorithm=VectorIndexAlgorithm.SVS_VAMANA, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False, graph_max_degree=40, construction_window_size=250, search_window_size=20, epsilon=0.01, compression=None, reduce=None, training_threshold=None)`

SVS-VAMANA vector field attributes with compression support.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **dims** (*int*)
  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.SVS_VAMANA* *]*)
  * **datatype** (*VectorDataType*)
  * **distance_metric** (*VectorDistanceMetric*)
  * **initial_cap** (*int* *|* *None*)
  * **index_missing** (*bool*)
  * **graph_max_degree** (*int*)
  * **construction_window_size** (*int*)
  * **search_window_size** (*int*)
  * **epsilon** (*float*)
  * **compression** (*CompressionType* *|* *None*)
  * **reduce** (*int* *|* *None*)
  * **training_threshold** (*int* *|* *None*)

#### `validate_svs_params()`

Validate SVS-VAMANA specific constraints

#### `algorithm: Literal[VectorIndexAlgorithm.SVS_VAMANA]`

The indexing algorithm for the vector field

#### `compression: CompressionType | None`

LVQ4, LVQ8, LeanVec4x8, LeanVec8x8

* **Type:**
  Vector compression

#### `construction_window_size: int`

1. - affects quality vs build time

* **Type:**
  Build-time candidates (default

#### `epsilon: float`

0.01)

* **Type:**
  Range query boundary factor (default

#### `graph_max_degree: int`

1. - affects recall vs memory

* **Type:**
  Max edges per node (default

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `reduce: int | None`

Dimensionality reduction for LeanVec types (must be < dims)

#### `search_window_size: int`

1. - primary tuning parameter

* **Type:**
  Search candidates (default

#### `training_threshold: int | None`

10,240)

* **Type:**
  Min vectors before compression training (default

**SVS-VAMANA Examples:**

**Basic configuration (no compression):**

[code example]

**High-performance configuration with compression:**

[code example]

**Important Notes:**

- **Requirements**: SVS-VAMANA requires Redis >= 8.2 with RediSearch >= 2.8.10.
- **Datatype limitations**: SVS-VAMANA only supports float16 and float32 datatypes (not bfloat16 or float64).
- **Compression compatibility**: The reduce parameter is only valid with LeanVec compression types (LeanVec4x8 or LeanVec8x8).
- **Platform considerations**: Intel’s proprietary LVQ and LeanVec optimizations are not available in Redis Open Source. On non-Intel platforms and Redis Open Source, SVS-VAMANA with compression falls back to basic 8-bit scalar quantization.
- **Performance tip**: Runtime parameters like `search_window_size`, `epsilon`, and `use_search_history` can be adjusted at query time without rebuilding the index. Start with defaults and tune `search_window_size` first for your speed vs accuracy requirements.

`FLAT Vector Fields`

FLAT - Brute-force exact search. **Best for small datasets (<10K vectors) requiring 100% accuracy.**

`When to use FLAT & Performance Details`

**Use FLAT when:**
: - Small datasets (<100K vectors) where exact results are required
  - Search accuracy is critical and approximate results are not acceptable
  - Baseline comparisons when evaluating approximate algorithms
  - Simple use cases where setup simplicity is more important than performance

**Performance characteristics:**
: - **Search accuracy**: 100% exact results (no approximation)
  - **Search speed**: Linear time O(n) - slower as dataset grows
  - **Memory usage**: Minimal overhead, stores vectors as-is
  - **Build time**: Fastest index construction (no preprocessing)

**Trade-offs vs other algorithms:**
: - **vs HNSW**: Much slower search but exact results, faster index building
  - **vs SVS-VAMANA**: Slower search and higher memory usage, but exact results

`class FlatVectorField(*, name, type=FieldTypes.VECTOR, path=None, attrs)`

Bases: `BaseField`

Vector field with FLAT (exact search) indexing for exact nearest neighbor search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **name** (*str*)
  * **type** (*Literal* *[* *FieldTypes.VECTOR* *]*)
  * **path** (*str* *|* *None*)
  * **attrs** ([FlatVectorFieldAttributes](#flatvectorfieldattributes))

#### `as_redis_field()`

Convert schema field to Redis Field object

* **Return type:**
  *Field*

#### `attrs: `[FlatVectorFieldAttributes](#flatvectorfieldattributes)

Specified field attributes

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

#### `type: Literal[FieldTypes.VECTOR]`

Field type

`class FlatVectorFieldAttributes(*, dims, algorithm=VectorIndexAlgorithm.FLAT, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False, block_size=None)`

FLAT vector field attributes for exact nearest neighbor search.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **dims** (*int*)
  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.FLAT* *]*)
  * **datatype** (*VectorDataType*)
  * **distance_metric** (*VectorDistanceMetric*)
  * **initial_cap** (*int* *|* *None*)
  * **index_missing** (*bool*)
  * **block_size** (*int* *|* *None*)

#### `algorithm: Literal[VectorIndexAlgorithm.FLAT]`

The indexing algorithm (fixed as ‘flat’)

#### `block_size: int | None`

Block size for processing (optional) - improves batch operation throughput

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

**FLAT Example:**

[code example]

**Note**: FLAT is recommended for small datasets or when exact results are mandatory. For larger datasets, consider HNSW or SVS-VAMANA for better performance.

SVS-VAMANA Configuration Utilities

For SVS-VAMANA indices, RedisVL provides utilities to help configure compression settings and estimate memory savings.

`CompressionAdvisor`

`class CompressionAdvisor`

Bases: `object`

Helper to recommend compression settings based on vector characteristics.

This class provides utilities to:
- Recommend optimal SVS-VAMANA configurations based on vector dimensions and priorities
- Estimate memory savings from compression and dimensionality reduction

`Examples`

[code example]

[code example]

#### `static estimate_memory_savings(compression, dims, reduce=None)`

Estimate memory savings percentage from compression.

Calculates the percentage of memory saved compared to uncompressed float32 vectors.

* **Parameters:**
  * **compression** (*str*) – Compression type (e.g., "LVQ4", "LeanVec4x8")
  * **dims** (*int*) – Original vector dimensionality
  * **reduce** (*int* *|* *None*) – Reduced dimensionality (for LeanVec compression)
* **Returns:**
  Memory savings percentage (0-100)
* **Return type:**
  float

`Examples`

[code example]

[code example]

#### `static recommend(dims, priority='balanced', datatype=None)`

Recommend compression settings based on dimensions and priorities.

* **Parameters:**
  * **dims** (*int*) – Vector dimensionality (must be > 0)
  * **priority** (*Literal* *[* *'speed'* *,*  *'memory'* *,*  *'balanced'* *]*) – Optimization priority:
    - "memory": Maximize memory savings
    - "speed": Optimize for query speed
    - "balanced": Balance between memory and speed
  * **datatype** (*str* *|* *None*) – Override datatype (default: float16 for high-dim, float32 for low-dim)
* **Returns:**
  Complete SVS-VAMANA configuration including:
  : - algorithm: "svs-vamana"
    - datatype: Recommended datatype
    - compression: Compression type
    - reduce: Dimensionality reduction (for LeanVec only)
    - graph_max_degree: Graph connectivity
    - construction_window_size: Build-time candidates
    - search_window_size: Query-time candidates
* **Return type:**
  dict
* **Raises:**
  **ValueError** – If dims <= 0

`Examples`

[code example]

[code example]

`SVSConfig`

`class SVSConfig(*, algorithm='svs-vamana', datatype=None, compression=None, reduce=None, graph_max_degree=None, construction_window_size=None, search_window_size=None)`

Bases: `BaseModel`

SVS-VAMANA configuration model.

* **Parameters:**
  * **algorithm** (*Literal* *[* *'svs-vamana'* *]*)
  * **datatype** (*str* *|* *None*)
  * **compression** (*str* *|* *None*)
  * **reduce** (*int* *|* *None*)
  * **graph_max_degree** (*int* *|* *None*)
  * **construction_window_size** (*int* *|* *None*)
  * **search_window_size** (*int* *|* *None*)

#### `algorithm`

Always "svs-vamana"

* **Type:**
  Literal[‘svs-vamana’]

#### `datatype`

Vector datatype (float16, float32)

* **Type:**
  str | None

#### `compression`

Compression type (LVQ4, LeanVec4x8, etc.)

* **Type:**
  str | None

#### `reduce`

Reduced dimensionality (only for LeanVec)

* **Type:**
  int | None

#### `graph_max_degree`

Max edges per node

* **Type:**
  int | None

#### `construction_window_size`

Build-time candidates

* **Type:**
  int | None

#### `search_window_size`

Query-time candidates

* **Type:**
  int | None

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Vector Algorithm Comparison

This section provides detailed guidance for choosing between vector search algorithms.

`Algorithm Selection Guide`

#### `Vector Algorithm Comparison`

| Algorithm      | Best For                               | Performance                    | Memory Usage              | Trade-offs                            |
|----------------|----------------------------------------|--------------------------------|---------------------------|---------------------------------------|
| **FLAT**       | Small datasets (<100K vectors)         | 100% recall, O(n) search       | Minimal overhead          | Exact but slow for large data         |
| **HNSW**       | General purpose (100K-1M+ vectors)     | 95-99% recall, O(log n) search | Moderate (graph overhead) | Fast approximate search               |
| **SVS-VAMANA** | Large datasets with memory constraints | 90-95% recall, O(log n) search | Low (with compression)    | Intel-optimized, requires newer Redis |

`When to Use Each Algorithm`

**Choose FLAT when:**
: - Dataset size < 100,000 vectors
  - Exact results are mandatory
  - Simple setup is preferred
  - Query latency is not critical

**Choose HNSW when:**
: - Dataset size 100K - 1M+ vectors
  - Need balanced speed and accuracy
  - Cross-platform compatibility required
  - Most common choice for production

**Choose SVS-VAMANA when:**
: - Dataset size > 100K vectors
  - Memory usage is a primary concern
  - Running on Intel hardware
  - Can accept 90-95% recall for memory savings

`Performance Characteristics`

**Search Speed:**
: - FLAT: Linear time O(n) - gets slower as data grows
  - HNSW: Logarithmic time O(log n) - scales well
  - SVS-VAMANA: Logarithmic time O(log n) - scales well

**Memory Usage (1M vectors, 768 dims, float32):**
: - FLAT: ~3.1 GB (baseline)
  - HNSW: ~3.7 GB (20% overhead for graph)
  - SVS-VAMANA: 1.6-3.1 GB (depends on compression)

**Recall Quality:**
: - FLAT: 100% (exact search)
  - HNSW: 95-99% (tunable via `ef_runtime` at query time)
  - SVS-VAMANA: 90-95% (tunable via `search_window_size` at query time, also depends on compression)

`Migration Considerations`

**From FLAT to HNSW:**
: - Straightforward migration
  - Expect slight recall reduction but major speed improvement
  - Tune `ef_runtime` at query time to balance speed vs accuracy (no index rebuild needed)

**From HNSW to SVS-VAMANA:**
: - Requires Redis >= 8.2 with RediSearch >= 2.8.10
  - Change datatype to float16 or float32 if using others
  - Consider compression options for memory savings

**From SVS-VAMANA to others:**
: - May need to change datatype back if using float64/bfloat16
  - HNSW provides similar performance with broader compatibility

For complete Redis field documentation, see: [https://redis.io/commands/ft.create/](https://redis.io/commands/ft.create/)

version: '0.1.0'

index:
    name: user-index
    prefix: user
    key_separator: ":"
    storage_type: json

fields:
    - name: user
      type: tag
    - name: credit_score
      type: tag
    - name: embedding
      type: vector
      attrs:
        algorithm: flat
        dims: 3
        distance_metric: cosine
        datatype: float32

from redisvl.schema import IndexSchema

schema = IndexSchema.from_yaml("schema.yaml")

from redisvl.schema import IndexSchema

schema = IndexSchema.from_dict({
    "index": {
        "name": "user-index",
        "prefix": "user",
        "key_separator": ":",
        "storage_type": "json",
    },
    "fields": [
        {"name": "user", "type": "tag"},
        {"name": "credit_score", "type": "tag"},
        {
            "name": "embedding",
            "type": "vector",
            "attrs": {
                "algorithm": "flat",
                "dims": 3,
                "distance_metric": "cosine",
                "datatype": "float32"
            }
        }
    ]
})

# Add a tag field
schema.add_field({"name": "user", "type": "tag})

# Add a vector field
schema.add_field({
    "name": "user-embedding",
    "type": "vector",
    "attrs": {
        "dims": 1024,
        "algorithm": "flat",
        "datatype": "float32"
    }
})

schema.add_fields([
    {"name": "user", "type": "tag"},
    {"name": "bio", "type": "text"},
    {
        "name": "user-embedding",
        "type": "vector",
        "attrs": {
            "dims": 1024,
            "algorithm": "flat",
            "datatype": "float32"
        }
    }
])

from redisvl.schema import IndexSchema

schema = IndexSchema.from_dict({
    "index": {
        "name": "docs-index",
        "prefix": "docs",
        "storage_type": "hash",
    },
    "fields": [
        {
            "name": "doc-id",
            "type": "tag"
        },
        {
            "name": "doc-embedding",
            "type": "vector",
            "attrs": {
                "algorithm": "flat",
                "dims": 1536
            }
        }
    ]
})

from redisvl.schema import IndexSchema
schema = IndexSchema.from_yaml("schema.yaml")

from redisvl.schema import IndexSchema

# Disable stopwords to search for phrases like "Bank of Glasberliner"
schema = IndexSchema.from_dict({
    "index": {
        "name": "company-idx",
        "prefix": "company",
        "stopwords": []  # STOPWORDS 0
    },
    "fields": [
        {"name": "name", "type": "text"}
    ]
})

- name: title
  type: text
  path: $.document.title
  attrs:
    weight: 1.0
    no_stem: false
    withsuffixtrie: true

- name: embedding
  type: vector
  attrs:
    algorithm: hnsw
    dims: 768
    distance_metric: cosine
    datatype: float32
    # Index-time parameters (set during index creation)
    m: 16                    # Graph connectivity
    ef_construction: 200     # Build-time accuracy
    # Note: ef_runtime can be set at query time via VectorQuery

- name: embedding
  type: vector
  attrs:
    algorithm: hnsw
    dims: 768
    distance_metric: cosine
    datatype: float32
    # Index-time parameters tuned for maximum accuracy
    m: 32
    ef_construction: 400
    # Note: ef_runtime=50 can be set at query time for higher recall

- name: embedding
  type: vector
  attrs:
    algorithm: svs-vamana
    dims: 768
    distance_metric: cosine
    datatype: float32
    # Index-time parameters (set during index creation)
    graph_max_degree: 40
    construction_window_size: 250
    # Note: search_window_size and other runtime params can be set at query time

- name: embedding
  type: vector
  attrs:
    algorithm: svs-vamana
    dims: 768
    distance_metric: cosine
    datatype: float32
    # Index-time parameters tuned for better recall
    graph_max_degree: 64
    construction_window_size: 500
    # Maximum compression with dimensionality reduction
    compression: LeanVec4x8
    reduce: 384  # 50% dimensionality reduction
    training_threshold: 1000
    # Note: search_window_size=40 can be set at query time for higher recall

- name: embedding
  type: vector
  attrs:
    algorithm: flat
    dims: 768
    distance_metric: cosine
    datatype: float32
    # Optional: tune for batch processing
    block_size: 1024

>> # Get recommendations for high-dimensional vectors
>> config = CompressionAdvisor.recommend(dims=1536, priority="balanced")
>> config.compression
'LeanVec4x8'
>> config.reduce
768

>> # Estimate memory savings
>> savings = CompressionAdvisor.estimate_memory_savings(
...     compression="LeanVec4x8",
...     dims=1536,
...     reduce=768
... )
>> savings
81.2

>> # LeanVec with dimensionality reduction
>> CompressionAdvisor.estimate_memory_savings(
...     compression="LeanVec4x8",
...     dims=1536,
...     reduce=768
... )
81.2

>> # LVQ without dimensionality reduction
>> CompressionAdvisor.estimate_memory_savings(
...     compression="LVQ4",
...     dims=384
... )
87.5

>> # High-dimensional embeddings (e.g., OpenAI ada-002)
>> config = CompressionAdvisor.recommend(dims=1536, priority="memory")
>> config.compression
'LeanVec4x8'
>> config.reduce
768

>> # Lower-dimensional embeddings
>> config = CompressionAdvisor.recommend(dims=384, priority="speed")
>> config.compression
'LVQ4x8'


Search Index Classes

Overview

| Class                                     | Description                                                                                |
|-------------------------------------------|----------------------------------------------------------------------------------------------|
| [SearchIndex](#searchindex-api)           | Primary class to write, read, and search across data structures in Redis.                    |
| [AsyncSearchIndex](#asyncsearchindex-api) | Async version of the SearchIndex to write, read, and search across data structures in Redis. |

SearchIndex

`class SearchIndex(schema, redis_client=None, redis_url=None, connection_kwargs=None, validate_on_load=False, **kwargs)`

A search index class for interacting with Redis as a vector database.

The SearchIndex is instantiated with a reference to a Redis database and an
IndexSchema (YAML path or dictionary object) that describes the various
settings and field configurations.

[code example]

Initialize the RedisVL search index with a schema, Redis client
(or URL string with other connection args), connection_args, and other
kwargs.

* **Parameters:**
  * **schema** ([*IndexSchema*]()) – Index schema object.
  * **redis_client** (*Optional* *[* *Redis* *]*) – An
    instantiated redis client.
  * **redis_url** (*Optional* *[* *str* *]*) – The URL of the Redis server to
    connect to.
  * **connection_kwargs** (*Dict* *[* *str* *,* *Any* *]* *,* *optional*) – Redis client connection
    args.
  * **validate_on_load** (*bool* *,* *optional*) – Whether to validate data against schema
    when loading. Defaults to False.

#### `aggregate(*args, **kwargs)`

Perform an aggregation operation against the index.

Wrapper around the aggregation API that adds the index name
to the query and passes along the rest of the arguments
to the redis-py ft().aggregate() method.

* **Returns:**
  Raw Redis aggregation results.
* **Return type:**
  Result

#### `batch_query(queries, batch_size=10)`

Execute a batch of queries and process results.

* **Parameters:**
  * **queries** (*Sequence* *[* *BaseQuery* *]*)
  * **batch_size** (*int*)
* **Return type:**
  *List*[*List*[*Dict*[str, *Any*]]]

#### `batch_search(queries, batch_size=10)`

Perform a search against the index for multiple queries.

This method takes a list of queries and optionally query params and
returns a list of Result objects for each query. Results are
returned in the same order as the queries.

NOTE: Cluster users may need to incorporate hash tags into their query
to avoid cross-slot operations.

* **Parameters:**
  * **queries** (*List* *[* *SearchParams* *]*) – The queries to search for.
  * **batch_size** (*int* *,* *optional*) – The number of queries to search for at a time.
    Defaults to 10.
* **Returns:**
  The search results for each query.
* **Return type:**
  List[Result]

#### `clear()`

Clear all keys in Redis associated with the index, leaving the index
available and in-place for future insertions or updates.

NOTE: This method requires custom behavior for Redis Cluster because
here, we can’t easily give control of the keys we’re clearing to the
user so they can separate them based on hash tag.

* **Returns:**
  Count of records deleted from Redis.
* **Return type:**
  int

#### `connect(redis_url=None, **kwargs)`

Connect to a Redis instance using the provided redis_url, falling
back to the REDIS_URL environment variable (if available).

Note: Additional keyword arguments (\*\*kwargs) can be used to provide
extra options specific to the Redis connection.

* **Parameters:**
  **redis_url** (*Optional* *[* *str* *]* *,* *optional*) – The URL of the Redis server to
  connect to.
* **Raises:**
  * **redis.exceptions.ConnectionError** – If the connection to the Redis
        server fails.
  * **ValueError** – If the Redis URL is not provided nor accessible
        through the REDIS_URL environment variable.
  * **ModuleNotFoundError** – If required Redis modules are not installed.

#### `create(overwrite=False, drop=False)`

Create an index in Redis with the current schema and properties.

* **Parameters:**
  * **overwrite** (*bool* *,* *optional*) – Whether to overwrite the index if it
    already exists. Defaults to False.
  * **drop** (*bool* *,* *optional*) – Whether to drop all keys associated with the
    index in the case of overwriting. Defaults to False.
* **Raises:**
  * **RuntimeError** – If the index already exists and ‘overwrite’ is False.
  * **ValueError** – If no fields are defined for the index.
* **Return type:**
  None

[code example]

#### `delete(drop=True)`

Delete the search index while optionally dropping all keys associated
with the index.

* **Parameters:**
  **drop** (*bool* *,* *optional*) – Delete the key / documents pairs in the
  index. Defaults to True.
* **Raises:**
  **redis.exceptions.ResponseError** – If the index does not exist.

#### `disconnect()`

Disconnect from the Redis database.

#### `drop_documents(ids)`

Remove documents from the index by their document IDs.

This method converts document IDs to Redis keys automatically by applying
the index’s key prefix and separator configuration.

NOTE: Cluster users will need to incorporate hash tags into their
document IDs and only call this method with documents from a single hash
tag at a time.

* **Parameters:**
  **ids** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The document ID or IDs to remove from the index.
* **Returns:**
  Count of documents deleted from Redis.
* **Return type:**
  int

#### `drop_keys(keys)`

Remove a specific entry or entries from the index by it’s key ID.

* **Parameters:**
  **keys** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The document ID or IDs to remove from the index.
* **Returns:**
  Count of records deleted from Redis.
* **Return type:**
  int

#### `exists()`

Check if the index exists in Redis.

* **Returns:**
  True if the index exists, False otherwise.
* **Return type:**
  bool

#### `expire_keys(keys, ttl)`

Set the expiration time for a specific entry or entries in Redis.

* **Parameters:**
  * **keys** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The entry ID or IDs to set the expiration for.
  * **ttl** (*int*) – The time-to-live in seconds.
* **Return type:**
  int | *List*[int]

#### `fetch(id)`

Fetch an object from Redis by id.

The id is typically either a unique identifier,
or derived from some domain-specific metadata combination
(like a document id or chunk id).

* **Parameters:**
  **id** (*str*) – The specified unique identifier for a particular
  document indexed in Redis.
* **Returns:**
  The fetched object.
* **Return type:**
  Dict[str, Any]

#### `classmethod from_dict(schema_dict, **kwargs)`

Create a SearchIndex from a dictionary.

* **Parameters:**
  **schema_dict** (*Dict* *[* *str* *,* *Any* *]*) – A dictionary containing the schema.
* **Returns:**
  A RedisVL SearchIndex object.
* **Return type:**
  [SearchIndex](#searchindex)

[code example]

#### `classmethod from_existing(name, redis_client=None, redis_url=None, **kwargs)`

Initialize from an existing search index in Redis by index name.

* **Parameters:**
  * **name** (*str*) – Name of the search index in Redis.
  * **redis_client** (*Optional* *[* *Redis* *]*) – An
    instantiated redis client.
  * **redis_url** (*Optional* *[* *str* *]*) – The URL of the Redis server to
    connect to.
* **Raises:**
  **ValueError** – If redis_url or redis_client is not provided.

#### `classmethod from_yaml(schema_path, **kwargs)`

Create a SearchIndex from a YAML schema file.

* **Parameters:**
  **schema_path** (*str*) – Path to the YAML schema file.
* **Returns:**
  A RedisVL SearchIndex object.
* **Return type:**
  [SearchIndex](#searchindex)

[code example]

#### `info(name=None)`

Get information about the index.

* **Parameters:**
  **name** (*str* *,* *optional*) – Index name to fetch info about.
  Defaults to None.
* **Returns:**
  A dictionary containing the information about the index.
* **Return type:**
  dict

#### `key(id)`

Construct a redis key as a combination of an index key prefix (optional)
and specified id.

The id is typically either a unique identifier, or
derived from some domain-specific metadata combination (like a document
id or chunk id).

* **Parameters:**
  **id** (*str*) – The specified unique identifier for a particular
  document indexed in Redis.
* **Returns:**
  The full Redis key including key prefix and value as a string.
* **Return type:**
  str

#### `listall()`

List all search indices in Redis database.

* **Returns:**
  The list of indices in the database.
* **Return type:**
  List[str]

#### `load(data, id_field=None, keys=None, ttl=None, preprocess=None, batch_size=None)`

Load objects to the Redis database. Returns the list of keys loaded
to Redis.

RedisVL automatically handles constructing the object keys, batching,
optional preprocessing steps, and setting optional expiration
(TTL policies) on keys.

* **Parameters:**
  * **data** (*Iterable* *[* *Any* *]*) – An iterable of objects to store.
  * **id_field** (*Optional* *[* *str* *]* *,* *optional*) – Specified field used as the id
    portion of the redis key (after the prefix) for each
    object. Defaults to None.
  * **keys** (*Optional* *[* *Iterable* *[* *str* *]* *]* *,* *optional*) – Optional iterable of keys.
    Must match the length of objects if provided. Defaults to None.
  * **ttl** (*Optional* *[* *int* *]* *,* *optional*) – Time-to-live in seconds for each key.
    Defaults to None.
  * **preprocess** (*Optional* *[* *Callable* *]* *,* *optional*) – A function to preprocess
    objects before storage. Defaults to None.
  * **batch_size** (*Optional* *[* *int* *]* *,* *optional*) – Number of objects to write in
    a single Redis pipeline execution. Defaults to class’s
    default batch size.
* **Returns:**
  List of keys loaded to Redis.
* **Return type:**
  List[str]
* **Raises:**
  * **SchemaValidationError** – If validation fails when validate_on_load is enabled.
  * **RedisVLError** – If there’s an error loading data to Redis.

#### `paginate(query, page_size=30)`

Execute a given query against the index and return results in
paginated batches.

This method accepts a RedisVL query instance, enabling pagination of
results which allows for subsequent processing over each batch with a
generator.

* **Parameters:**
  * **query** (*BaseQuery*) – The search query to be executed.
  * **page_size** (*int* *,* *optional*) – The number of results to return in each
    batch. Defaults to 30.
* **Yields:**
  A generator yielding batches of search results.
* **Raises:**
  * **TypeError** – If the page_size argument is not of type int.
  * **ValueError** – If the page_size argument is less than or equal to zero.
* **Return type:**
  *Generator*

[code example]

#### `NOTE`
The page_size parameter controls the number of items each result
batch contains. Adjust this value based on performance
considerations and the expected volume of search results.

#### `query(query)`

Execute a query on the index.

This method takes a BaseQuery or AggregationQuery object directly, and
handles post-processing of the search.

* **Parameters:**
  **query** (*Union* *[* *BaseQuery* *,* *AggregateQuery* *]*) – The query to run.
* **Returns:**
  A list of search results.
* **Return type:**
  List[Result]

[code example]

#### `search(*args, **kwargs)`

Perform a search against the index.

Wrapper around the search API that adds the index name
to the query and passes along the rest of the arguments
to the redis-py ft().search() method.

* **Returns:**
  Raw Redis search results.
* **Return type:**
  Result

#### `set_client(redis_client, **kwargs)`

Manually set the Redis client to use with the search index.

This method configures the search index to use a specific Redis or
Async Redis client. It is useful for cases where an external,
custom-configured client is preferred instead of creating a new one.

* **Parameters:**
  **redis_client** (*Redis*) – A Redis or Async Redis
  client instance to be used for the connection.
* **Raises:**
  **TypeError** – If the provided client is not valid.

#### `property client: Redis | RedisCluster | None`

The underlying redis-py client object.

#### `property key_separator: str`

The optional separator between a defined prefix and key value in
forming a Redis key.

#### `property name: str`

The name of the Redis search index.

#### `property prefix: str`

The optional key prefix that comes before a unique key value in
forming a Redis key. If multiple prefixes are configured, returns the
first one.

#### `property storage_type: StorageType`

The underlying storage type for the search index; either
hash or json.

AsyncSearchIndex

`class AsyncSearchIndex(schema, *, redis_url=None, redis_client=None, connection_kwargs=None, validate_on_load=False, **kwargs)`

A search index class for interacting with Redis as a vector database in
async-mode.

The AsyncSearchIndex is instantiated with a reference to a Redis database
and an IndexSchema (YAML path or dictionary object) that describes the
various settings and field configurations.

[code example]

Initialize the RedisVL async search index with a schema.

* **Parameters:**
  * **schema** ([*IndexSchema*]()) – Index schema object.
  * **redis_url** (*Optional* *[* *str* *]* *,* *optional*) – The URL of the Redis server to
    connect to.
  * **redis_client** (*Optional* *[* *AsyncRedis* *]*) – An
    instantiated redis client.
  * **connection_kwargs** (*Optional* *[* *Dict* *[* *str* *,* *Any* *]* *]*) – Redis client connection
    args.
  * **validate_on_load** (*bool* *,* *optional*) – Whether to validate data against schema
    when loading. Defaults to False.

#### `async aggregate(*args, **kwargs)`

Perform an aggregation operation against the index.

Wrapper around the aggregation API that adds the index name
to the query and passes along the rest of the arguments
to the redis-py ft().aggregate() method.

* **Returns:**
  Raw Redis aggregation results.
* **Return type:**
  Result

#### `async batch_query(queries, batch_size=10)`

Asynchronously execute a batch of queries and process results.

* **Parameters:**
  * **queries** (*List* *[* *BaseQuery* *]*)
  * **batch_size** (*int*)
* **Return type:**
  *List*[*List*[*Dict*[str, *Any*]]]

#### `async batch_search(queries, batch_size=10)`

Asynchronously execute a batch of search queries.

This method takes a list of search queries and executes them in batches
to improve performance when dealing with multiple queries.

NOTE: Cluster users may need to incorporate hash tags into their query
to avoid cross-slot operations.

* **Parameters:**
  * **queries** (*List* *[* *SearchParams* *]*) – A list of search queries to execute.
    Each query can be either a string or a tuple of (query, params).
  * **batch_size** (*int* *,* *optional*) – The number of queries to execute in each
    batch. Defaults to 10.
* **Returns:**
  A list of search results corresponding to each query.
* **Return type:**
  List[Result]

[code example]

#### `async clear()`

Clear all keys in Redis associated with the index, leaving the index
available and in-place for future insertions or updates.

NOTE: This method requires custom behavior for Redis Cluster because here,
we can’t easily give control of the keys we’re clearing to the user so they
can separate them based on hash tag.

* **Returns:**
  Count of records deleted from Redis.
* **Return type:**
  int

#### `connect(redis_url=None, **kwargs)`

[DEPRECATED] Connect to a Redis instance. Use connection parameters in \_\_init_\_.

* **Parameters:**
  **redis_url** (*str* *|* *None*)

#### `async create(overwrite=False, drop=False)`

Asynchronously create an index in Redis with the current schema
: and properties.

* **Parameters:**
  * **overwrite** (*bool* *,* *optional*) – Whether to overwrite the index if it
    already exists. Defaults to False.
  * **drop** (*bool* *,* *optional*) – Whether to drop all keys associated with the
    index in the case of overwriting. Defaults to False.
* **Raises:**
  * **RuntimeError** – If the index already exists and ‘overwrite’ is False.
  * **ValueError** – If no fields are defined for the index.
* **Return type:**
  None

[code example]

#### `async delete(drop=True)`

Delete the search index.

* **Parameters:**
  **drop** (*bool* *,* *optional*) – Delete the documents in the index.
  Defaults to True.
* **Raises:**
  **redis.exceptions.ResponseError** – If the index does not exist.

#### `async disconnect()`

Disconnect from the Redis database.

#### `async drop_documents(ids)`

Remove documents from the index by their document IDs.

This method converts document IDs to Redis keys automatically by applying
the index’s key prefix and separator configuration.

NOTE: Cluster users will need to incorporate hash tags into their
document IDs and only call this method with documents from a single hash
tag at a time.

* **Parameters:**
  **ids** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The document ID or IDs to remove from the index.
* **Returns:**
  Count of documents deleted from Redis.
* **Return type:**
  int

#### `async drop_keys(keys)`

Remove a specific entry or entries from the index by it’s key ID.

* **Parameters:**
  **keys** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The document ID or IDs to remove from the index.
* **Returns:**
  Count of records deleted from Redis.
* **Return type:**
  int

#### `async exists()`

Check if the index exists in Redis.

* **Returns:**
  True if the index exists, False otherwise.
* **Return type:**
  bool

#### `async expire_keys(keys, ttl)`

Set the expiration time for a specific entry or entries in Redis.

* **Parameters:**
  * **keys** (*Union* *[* *str* *,* *List* *[* *str* *]* *]*) – The entry ID or IDs to set the expiration for.
  * **ttl** (*int*) – The time-to-live in seconds.
* **Return type:**
  int | *List*[int]

#### `async fetch(id)`

Asynchronously etch an object from Redis by id. The id is typically
either a unique identifier, or derived from some domain-specific
metadata combination (like a document id or chunk id).

* **Parameters:**
  **id** (*str*) – The specified unique identifier for a particular
  document indexed in Redis.
* **Returns:**
  The fetched object.
* **Return type:**
  Dict[str, Any]

#### `classmethod from_dict(schema_dict, **kwargs)`

Create a SearchIndex from a dictionary.

* **Parameters:**
  **schema_dict** (*Dict* *[* *str* *,* *Any* *]*) – A dictionary containing the schema.
* **Returns:**
  A RedisVL SearchIndex object.
* **Return type:**
  [SearchIndex](#searchindex)

[code example]

#### `async classmethod* from_existing(name, redis_client=None, redis_url=None, **kwargs)`

Initialize from an existing search index in Redis by index name.

* **Parameters:**
  * **name** (*str*) – Name of the search index in Redis.
  * **redis_client** (*Optional* *[* *Redis* *]*) – An
    instantiated redis client.
  * **redis_url** (*Optional* *[* *str* *]*) – The URL of the Redis server to
    connect to.

#### `classmethod from_yaml(schema_path, **kwargs)`

Create a SearchIndex from a YAML schema file.

* **Parameters:**
  **schema_path** (*str*) – Path to the YAML schema file.
* **Returns:**
  A RedisVL SearchIndex object.
* **Return type:**
  [SearchIndex](#searchindex)

[code example]

#### `async info(name=None)`

Get information about the index.

* **Parameters:**
  **name** (*str* *,* *optional*) – Index name to fetch info about.
  Defaults to None.
* **Returns:**
  A dictionary containing the information about the index.
* **Return type:**
  dict

#### `key(id)`

Construct a redis key as a combination of an index key prefix (optional)
and specified id.

The id is typically either a unique identifier, or
derived from some domain-specific metadata combination (like a document
id or chunk id).

* **Parameters:**
  **id** (*str*) – The specified unique identifier for a particular
  document indexed in Redis.
* **Returns:**
  The full Redis key including key prefix and value as a string.
* **Return type:**
  str

#### `async listall()`

List all search indices in Redis database.

* **Returns:**
  The list of indices in the database.
* **Return type:**
  List[str]

#### `load(data, id_field=None, keys=None, ttl=None, preprocess=None, concurrency=None, batch_size=None)`

Asynchronously load objects to Redis. Returns the list of keys loaded
to Redis.

RedisVL automatically handles constructing the object keys, batching,
optional preprocessing steps, and setting optional expiration
(TTL policies) on keys.

* **Parameters:**
  * **data** (*Iterable* *[* *Any* *]*) – An iterable of objects to store.
  * **id_field** (*Optional* *[* *str* *]* *,* *optional*) – Specified field used as the id
    portion of the redis key (after the prefix) for each
    object. Defaults to None.
  * **keys** (*Optional* *[* *Iterable* *[* *str* *]* *]* *,* *optional*) – Optional iterable of keys.
    Must match the length of objects if provided. Defaults to None.
  * **ttl** (*Optional* *[* *int* *]* *,* *optional*) – Time-to-live in seconds for each key.
    Defaults to None.
  * **preprocess** (*Optional* *[* *Callable* *]* *,* *optional*) – A function to
    preprocess objects before storage. Defaults to None.
  * **batch_size** (*Optional* *[* *int* *]* *,* *optional*) – Number of objects to write in
    a single Redis pipeline execution. Defaults to class’s
    default batch size.
  * **concurrency** (*int* *|* *None*)
* **Returns:**
  List of keys loaded to Redis.
* **Return type:**
  List[str]
* **Raises:**
  * **SchemaValidationError** – If validation fails when validate_on_load is enabled.
  * **RedisVLError** – If there’s an error loading data to Redis.

[code example]

#### `async paginate(query, page_size=30)`

Execute a given query against the index and return results in
paginated batches.

This method accepts a RedisVL query instance, enabling async pagination
of results which allows for subsequent processing over each batch with a
generator.

* **Parameters:**
  * **query** (*BaseQuery*) – The search query to be executed.
  * **page_size** (*int* *,* *optional*) – The number of results to return in each
    batch. Defaults to 30.
* **Yields:**
  An async generator yielding batches of search results.
* **Raises:**
  * **TypeError** – If the page_size argument is not of type int.
  * **ValueError** – If the page_size argument is less than or equal to zero.
* **Return type:**
  *AsyncGenerator*

[code example]

#### `NOTE`
The page_size parameter controls the number of items each result
batch contains. Adjust this value based on performance
considerations and the expected volume of search results.

#### `async query(query)`

Asynchronously execute a query on the index.

This method takes a BaseQuery or AggregationQuery object directly, runs
the search, and handles post-processing of the search.

* **Parameters:**
  **query** (*Union* *[* *BaseQuery* *,* *AggregateQuery* *]*) – The query to run.
* **Returns:**
  A list of search results.
* **Return type:**
  List[Result]

[code example]

#### `async search(*args, **kwargs)`

Perform an async search against the index.

Wrapper around the search API that adds the index name
to the query and passes along the rest of the arguments
to the redis-py ft().search() method.

* **Returns:**
  Raw Redis search results.
* **Return type:**
  Result

#### `set_client(redis_client)`

[DEPRECATED] Manually set the Redis client to use with the search index.
This method is deprecated; please provide connection parameters in \_\_init_\_.

* **Parameters:**
  **redis_client** (*Redis* *|* *RedisCluster* *|* *Redis* *|* *RedisCluster*)

#### `property client: Redis | RedisCluster | None`

The underlying redis-py client object.

#### `property key_separator: str`

The optional separator between a defined prefix and key value in
forming a Redis key.

#### `property name: str`

The name of the Redis search index.

#### `property prefix: str`

The optional key prefix that comes before a unique key value in
forming a Redis key. If multiple prefixes are configured, returns the
first one.

#### `property storage_type: StorageType`

The underlying storage type for the search index; either
hash or json.

from redisvl.index import SearchIndex

# initialize the index object with schema from file
index = SearchIndex.from_yaml(
    "schemas/schema.yaml",
    redis_url="redis://localhost:6379",
    validate_on_load=True
)

# create the index
index.create(overwrite=True, drop=False)

# data is an iterable of dictionaries
index.load(data)

# delete index and data
index.delete(drop=True)

# create an index in Redis; only if one does not exist with given name
index.create()

# overwrite an index in Redis without dropping associated data
index.create(overwrite=True)

# overwrite an index in Redis; drop associated data (clean slate)
index.create(overwrite=True, drop=True)

from redisvl.index import SearchIndex

index = SearchIndex.from_dict({
    "index": {
        "name": "my-index",
        "prefix": "rvl",
        "storage_type": "hash",
    },
    "fields": [
        {"name": "doc-id", "type": "tag"}
    ]
}, redis_url="redis://localhost:6379")

from redisvl.index import SearchIndex

index = SearchIndex.from_yaml("schemas/schema.yaml", redis_url="redis://localhost:6379")

# Iterate over paginated search results in batches of 10
for result_batch in index.paginate(query, page_size=10):
    # Process each batch of results
    pass

from redisvl.query import VectorQuery

query = VectorQuery(
    vector=[0.16, -0.34, 0.98, 0.23],
    vector_field_name="embedding",
    num_results=3
)

results = index.query(query)

from redisvl.index import AsyncSearchIndex

# initialize the index object with schema from file
index = AsyncSearchIndex.from_yaml(
    "schemas/schema.yaml",
    redis_url="redis://localhost:6379",
    validate_on_load=True
)

# create the index
await index.create(overwrite=True, drop=False)

# data is an iterable of dictionaries
await index.load(data)

# delete index and data
await index.delete(drop=True)

queries = [
    "hello world",
    ("goodbye world", {"num_results": 5}),
]

results = await index.batch_search(queries)

# create an index in Redis; only if one does not exist with given name
await index.create()

# overwrite an index in Redis without dropping associated data
await index.create(overwrite=True)

# overwrite an index in Redis; drop associated data (clean slate)
await index.create(overwrite=True, drop=True)

data = [{"test": "foo"}, {"test": "bar"}]

# simple case
keys = await index.load(data)

# set 360 second ttl policy on data
keys = await index.load(data, ttl=360)

# load data with predefined keys
keys = await index.load(data, keys=["rvl:foo", "rvl:bar"])

# load data with preprocessing step
def add_field(d):
    d["new_field"] = 123
    return d
keys = await index.load(data, preprocess=add_field)

# Iterate over paginated search results in batches of 10
async for result_batch in index.paginate(query, page_size=10):
    # Process each batch of results
    pass

from redisvl.query import VectorQuery

query = VectorQuery(
    vector=[0.16, -0.34, 0.98, 0.23],
    vector_field_name="embedding",
    num_results=3
)

results = await index.query(query)


LLM Session Manager

SemanticSessionManager

`class SemanticSessionManager(name, session_tag=None, prefix=None, vectorizer=None, distance_threshold=0.3, redis_client=None, redis_url='redis://localhost:6379', connection_kwargs={}, overwrite=False, **kwargs)`

Bases: `BaseSessionManager`

Initialize session memory with index

Session Manager stores the current and previous user text prompts and
LLM responses to allow for enriching future prompts with session
context. Session history is stored in individual user or LLM prompts and
responses.

* **Parameters:**
  * **name** (*str*) – The name of the session manager index.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
  * **prefix** (*Optional* *[* *str* *]*) – Prefix for the keys for this session data.
    Defaults to None and will be replaced with the index name.
  * **vectorizer** (*Optional* *[* *BaseVectorizer* *]*) – The vectorizer used to create embeddings.
  * **distance_threshold** (*float*) – The maximum semantic distance to be
    included in the context. Defaults to 0.3.
  * **redis_client** (*Optional* *[* *Redis* *]*) – A Redis client instance. Defaults to
    None.
  * **redis_url** (*str* *,* *optional*) – The redis url. Defaults to redis://localhost:6379.
  * **connection_kwargs** (*Dict* *[* *str* *,* *Any* *]*) – The connection arguments
    for the redis client. Defaults to empty {}.
  * **overwrite** (*bool*) – Whether or not to force overwrite the schema for
    the semantic session index. Defaults to false.

The proposed schema will support a single vector embedding constructed
from either the prompt or response in a single string.

#### `add_message(message, session_tag=None)`

Insert a single prompt or response into the session memory.
A timestamp is associated with it so that it can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **message** (*Dict* *[* *str* *,**str* *]*) – The user prompt or LLM response.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `add_messages(messages, session_tag=None)`

Insert a list of prompts and responses into the session memory.
A timestamp is associated with each so that they can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **messages** (*List* *[* *Dict* *[* *str* *,* *str* *]* *]*) – The list of user prompts and LLM responses.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `clear()`

Clears the chat session history.

* **Return type:**
  None

#### `delete()`

Clear all conversation keys and remove the search index.

* **Return type:**
  None

#### `drop(id=None)`

Remove a specific exchange from the conversation history.

* **Parameters:**
  **id** (*Optional* *[* *str* *]*) – The id of the session entry to delete.
  If None then the last entry is deleted.
* **Return type:**
  None

#### `get_recent(top_k=5, as_text=False, raw=False, session_tag=None)`

Retreive the recent conversation history in sequential order.

* **Parameters:**
  * **top_k** (*int*) – The number of previous exchanges to return. Default is 5.
  * **as_text** (*bool*) – Whether to return the conversation as a single string,
    or list of alternating prompts and responses.
  * **raw** (*bool*) – Whether to return the full Redis hash entry or just the
    prompt and response
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Returns:**
  A single string transcription of the session
  : or list of strings if as_text is false.
* **Return type:**
  Union[str, List[str]]
* **Raises:**
  **ValueError** – if top_k is not an integer greater than or equal to 0.

#### `get_relevant(prompt, as_text=False, top_k=5, fall_back=False, session_tag=None, raw=False, distance_threshold=None)`

Searches the chat history for information semantically related to
the specified prompt.

This method uses vector similarity search with a text prompt as input.
It checks for semantically similar prompts and responses and gets
the top k most relevant previous prompts or responses to include as
context to the next LLM call.

* **Parameters:**
  * **prompt** (*str*) – The message text to search for in session memory
  * **as_text** (*bool*) – Whether to return the prompts and responses as text
  * **JSON** (*or as*)
  * **top_k** (*int*) – The number of previous messages to return. Default is 5.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
  * **distance_threshold** (*Optional* *[* *float* *]*) – The threshold for semantic
    vector distance.
  * **fall_back** (*bool*) – Whether to drop back to recent conversation history
    if no relevant context is found.
  * **raw** (*bool*) – Whether to return the full Redis hash entry or just the
    message.
* **Returns:**
  Either a list of strings, or a
  list of prompts and responses in JSON containing the most relevant.
* **Return type:**
  Union[List[str], List[Dict[str,str]]

Raises ValueError: if top_k is not an integer greater or equal to 0.

#### `store(prompt, response, session_tag=None)`

Insert a prompt:response pair into the session memory. A timestamp
is associated with each message so that they can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **prompt** (*str*) – The user prompt to the LLM.
  * **response** (*str*) – The corresponding LLM response.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `property messages: List[str] | List[Dict[str, str]]`

Returns the full chat history.

StandardSessionManager

`class StandardSessionManager(name, session_tag=None, prefix=None, redis_client=None, redis_url='redis://localhost:6379', connection_kwargs={}, **kwargs)`

Bases: `BaseSessionManager`

Initialize session memory

Session Manager stores the current and previous user text prompts and
LLM responses to allow for enriching future prompts with session
context.Session history is stored in individual user or LLM prompts and
responses.

* **Parameters:**
  * **name** (*str*) – The name of the session manager index.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
  * **prefix** (*Optional* *[* *str* *]*) – Prefix for the keys for this session data.
    Defaults to None and will be replaced with the index name.
  * **redis_client** (*Optional* *[* *Redis* *]*) – A Redis client instance. Defaults to
    None.
  * **redis_url** (*str* *,* *optional*) – The redis url. Defaults to redis://localhost:6379.
  * **connection_kwargs** (*Dict* *[* *str* *,* *Any* *]*) – The connection arguments
    for the redis client. Defaults to empty {}.

The proposed schema will support a single combined vector embedding
constructed from the prompt & response in a single string.

#### `add_message(message, session_tag=None)`

Insert a single prompt or response into the session memory.
A timestamp is associated with it so that it can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **message** (*Dict* *[* *str* *,**str* *]*) – The user prompt or LLM response.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `add_messages(messages, session_tag=None)`

Insert a list of prompts and responses into the session memory.
A timestamp is associated with each so that they can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **messages** (*List* *[* *Dict* *[* *str* *,* *str* *]* *]*) – The list of user prompts and LLM responses.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `clear()`

Clears the chat session history.

* **Return type:**
  None

#### `delete()`

Clear all conversation keys and remove the search index.

* **Return type:**
  None

#### `drop(id=None)`

Remove a specific exchange from the conversation history.

* **Parameters:**
  **id** (*Optional* *[* *str* *]*) – The id of the session entry to delete.
  If None then the last entry is deleted.
* **Return type:**
  None

#### `get_recent(top_k=5, as_text=False, raw=False, session_tag=None)`

Retrieve the recent conversation history in sequential order.

* **Parameters:**
  * **top_k** (*int*) – The number of previous messages to return. Default is 5.
  * **as_text** (*bool*) – Whether to return the conversation as a single string,
    or list of alternating prompts and responses.
  * **raw** (*bool*) – Whether to return the full Redis hash entry or just the
    prompt and response
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Returns:**
  A single string transcription of the session
  : or list of strings if as_text is false.
* **Return type:**
  Union[str, List[str]]
* **Raises:**
  **ValueError** – if top_k is not an integer greater than or equal to 0.

#### `store(prompt, response, session_tag=None)`

Insert a prompt:response pair into the session memory. A timestamp
is associated with each exchange so that they can be later sorted
in sequential ordering after retrieval.

* **Parameters:**
  * **prompt** (*str*) – The user prompt to the LLM.
  * **response** (*str*) – The corresponding LLM response.
  * **session_tag** (*Optional* *[* *str* *]*) – Tag to be added to entries to link to a specific
    session. Defaults to instance ULID.
* **Return type:**
  None

#### `property messages: List[str] | List[Dict[str, str]]`

Returns the full chat history.


Threshold Optimizers

CacheThresholdOptimizer

RouterThresholdOptimizer


Vector

Overview

The Vector class in RedisVL is a container that encapsulates a numerical vector, it’s datatype, corresponding index field name, and optional importance weight. It is used when constructing multi-vector queries using the MultiVectorQuery class.

Vector

`class Vector(*, vector, field_name, dtype='float32', weight=1.0)`

Simple object containing the necessary arguments to perform a multi vector query.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

* **Parameters:**
  * **vector** (*List* *[* *float* *]*  *|* *bytes*)
  * **field_name** (*str*)
  * **dtype** (*str*)
  * **weight** (*float*)

#### `validate_vector()`

If the vector passed in is an array of float convert it to a byte string.

* **Return type:**
  *Self*

#### `model_config: ClassVar[ConfigDict] = {}`

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].