{
  "id": "schema",
  "title": "Schema",
  "url": "https://redis.io/docs/latest/develop/ai/redisvl/0.11.1/api/schema/",
  "summary": "",
  "content": "\n\nSchema in RedisVL provides a structured format to define index settings and\nfield configurations using the following three components:\n\n| Component   | Description                                                                        |\n|-------------|------------------------------------------------------------------------------------|\n| version     | The version of the schema spec. Current supported version is 0.1.0.                |\n| index       | Index specific settings like name, key prefix, key separator, and storage type.    |\n| fields      | Subset of fields within your data to include in the index and any custom settings. |\n\n## IndexSchema\n\n\u003ca id=\"indexschema-api\"\u003e\u003c/a\u003e\n\n### `class IndexSchema(*, index, fields=\u003cfactory\u003e, version='0.1.0')`\n\nA schema definition for a search index in Redis, used in RedisVL for\nconfiguring index settings and organizing vector and metadata fields.\n\nThe class offers methods to create an index schema from a YAML file or a\nPython dictionary, supporting flexible schema definitions and easy\nintegration into various workflows.\n\nAn example schema.yaml file might look like this:\n\n```yaml\nversion: '0.1.0'\n\nindex:\n    name: user-index\n    prefix: user\n    key_separator: \":\"\n    storage_type: json\n\nfields:\n    - name: user\n      type: tag\n    - name: credit_score\n      type: tag\n    - name: embedding\n      type: vector\n      attrs:\n        algorithm: flat\n        dims: 3\n        distance_metric: cosine\n        datatype: float32\n```\n\nLoading the schema for RedisVL from yaml is as simple as:\n\n```python\nfrom redisvl.schema import IndexSchema\n\nschema = IndexSchema.from_yaml(\"schema.yaml\")\n```\n\nLoading the schema for RedisVL from dict is as simple as:\n\n```python\nfrom redisvl.schema import IndexSchema\n\nschema = IndexSchema.from_dict({\n    \"index\": {\n        \"name\": \"user-index\",\n        \"prefix\": \"user\",\n        \"key_separator\": \":\",\n        \"storage_type\": \"json\",\n    },\n    \"fields\": [\n        {\"name\": \"user\", \"type\": \"tag\"},\n        {\"name\": \"credit_score\", \"type\": \"tag\"},\n        {\n            \"name\": \"embedding\",\n            \"type\": \"vector\",\n            \"attrs\": {\n                \"algorithm\": \"flat\",\n                \"dims\": 3,\n                \"distance_metric\": \"cosine\",\n                \"datatype\": \"float32\"\n            }\n        }\n    ]\n})\n```\n\n#### `NOTE`\nThe fields attribute in the schema must contain unique field names to ensure\ncorrect and unambiguous field references.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **index** (*IndexInfo*)\n  * **fields** (*Dict* *[* *str* *,* *BaseField* *]*)\n  * **version** (*Literal* *[* *'0.1.0'* *]*)\n\n#### `add_field(field_inputs)`\n\nAdds a single field to the index schema based on the specified field\ntype and attributes.\n\nThis method allows for the addition of individual fields to the schema,\nproviding flexibility in defining the structure of the index.\n\n* **Parameters:**\n  **field_inputs** (*Dict* *[* *str* *,* *Any* *]*) – A field to add.\n* **Raises:**\n  **ValueError** – If the field name or type are not provided or if the name\n      already exists within the schema.\n\n```python\n# Add a tag field\nschema.add_field({\"name\": \"user\", \"type\": \"tag})\n\n# Add a vector field\nschema.add_field({\n    \"name\": \"user-embedding\",\n    \"type\": \"vector\",\n    \"attrs\": {\n        \"dims\": 1024,\n        \"algorithm\": \"flat\",\n        \"datatype\": \"float32\"\n    }\n})\n```\n\n#### `add_fields(fields)`\n\nExtends the schema with additional fields.\n\nThis method allows dynamically adding new fields to the index schema. It\nprocesses a list of field definitions.\n\n* **Parameters:**\n  **fields** (*List* *[* *Dict* *[* *str* *,* *Any* *]* *]*) – A list of fields to add.\n* **Raises:**\n  **ValueError** – If a field with the same name already exists in the\n      schema.\n\n```python\nschema.add_fields([\n    {\"name\": \"user\", \"type\": \"tag\"},\n    {\"name\": \"bio\", \"type\": \"text\"},\n    {\n        \"name\": \"user-embedding\",\n        \"type\": \"vector\",\n        \"attrs\": {\n            \"dims\": 1024,\n            \"algorithm\": \"flat\",\n            \"datatype\": \"float32\"\n        }\n    }\n])\n```\n\n#### `classmethod from_dict(data)`\n\nCreate an IndexSchema from a dictionary.\n\n* **Parameters:**\n  **data** (*Dict* *[* *str* *,* *Any* *]*) – The index schema data.\n* **Returns:**\n  The index schema.\n* **Return type:**\n  [IndexSchema](#indexschema)\n\n```python\nfrom redisvl.schema import IndexSchema\n\nschema = IndexSchema.from_dict({\n    \"index\": {\n        \"name\": \"docs-index\",\n        \"prefix\": \"docs\",\n        \"storage_type\": \"hash\",\n    },\n    \"fields\": [\n        {\n            \"name\": \"doc-id\",\n            \"type\": \"tag\"\n        },\n        {\n            \"name\": \"doc-embedding\",\n            \"type\": \"vector\",\n            \"attrs\": {\n                \"algorithm\": \"flat\",\n                \"dims\": 1536\n            }\n        }\n    ]\n})\n```\n\n#### `classmethod from_yaml(file_path)`\n\nCreate an IndexSchema from a YAML file.\n\n* **Parameters:**\n  **file_path** (*str*) – The path to the YAML file.\n* **Returns:**\n  The index schema.\n* **Return type:**\n  [IndexSchema](#indexschema)\n\n```python\nfrom redisvl.schema import IndexSchema\nschema = IndexSchema.from_yaml(\"schema.yaml\")\n```\n\n#### `remove_field(field_name)`\n\nRemoves a field from the schema based on the specified name.\n\nThis method is useful for dynamically altering the schema by removing\nexisting fields.\n\n* **Parameters:**\n  **field_name** (*str*) – The name of the field to be removed.\n\n#### `to_dict()`\n\nSerialize the index schema model to a dictionary, handling Enums\nand other special cases properly.\n\n* **Returns:**\n  The index schema as a dictionary.\n* **Return type:**\n  Dict[str, Any]\n\n#### `to_yaml(file_path, overwrite=True)`\n\nWrite the index schema to a YAML file.\n\n* **Parameters:**\n  * **file_path** (*str*) – The path to the YAML file.\n  * **overwrite** (*bool*) – Whether to overwrite the file if it already exists.\n* **Raises:**\n  **FileExistsError** – If the file already exists and overwrite is False.\n* **Return type:**\n  None\n\n#### `property field_names: List[str]`\n\nA list of field names associated with the index schema.\n\n* **Returns:**\n  A list of field names from the schema.\n* **Return type:**\n  List[str]\n\n#### `fields: Dict[str, BaseField]`\n\nFields associated with the search index and their properties.\n\nNote: When creating from dict/YAML, provide fields as a list of field definitions.\nThe validator will convert them to a Dict[str, BaseField] internally.\n\n#### `index: IndexInfo`\n\nDetails of the basic index configurations.\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `version: Literal['0.1.0']`\n\nVersion of the underlying index schema.\n\n## Defining Fields\n\nFields 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.\n\n**YAML Example**:\n\n```yaml\n- name: title\n  type: text\n  path: $.document.title\n  attrs:\n    weight: 1.0\n    no_stem: false\n    withsuffixtrie: true\n```\n\n**Python Dictionary Example**:\n\n```python\n{\n    \"name\": \"location\",\n    \"type\": \"geo\",\n    \"attrs\": {\n        \"sortable\": true\n    }\n}\n```\n\n## Basic Field Types\n\nRedisVL supports several basic field types for indexing different kinds of data. Each field type has specific attributes that customize its indexing and search behavior.\n\n### `Text Fields`\n\nText fields support full-text search with stemming, phonetic matching, and other text analysis features.\n\n### `class TextField(*, name, type=FieldTypes.TEXT, path=None, attrs=\u003cfactory\u003e)`\n\nBases: `BaseField`\n\nText field supporting a full text search index\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.TEXT* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([TextFieldAttributes](#textfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[TextFieldAttributes](#textfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.TEXT]`\n\nField type\n\n### `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)`\n\nFull text field attributes\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **sortable** (*bool*)\n  * **index_missing** (*bool*)\n  * **no_index** (*bool*)\n  * **weight** (*float*)\n  * **no_stem** (*bool*)\n  * **withsuffixtrie** (*bool*)\n  * **phonetic_matcher** (*str* *|* *None*)\n  * **index_empty** (*bool*)\n  * **unf** (*bool*)\n\n#### `index_empty: bool`\n\nAllow indexing and searching for empty strings\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `no_stem: bool`\n\nDisable stemming on the text field during indexing\n\n#### `phonetic_matcher: str | None`\n\nUsed to perform phonetic matching during search\n\n#### `unf: bool`\n\nUn-normalized form - disable normalization on sortable fields (only applies when sortable=True)\n\n#### `weight: float`\n\nDeclares the importance of this field when calculating results\n\n#### `withsuffixtrie: bool`\n\nKeep a suffix trie with all terms which match the suffix to optimize certain queries\n\n### `Tag Fields`\n\nTag fields are optimized for exact-match filtering and faceted search on categorical data.\n\n### `class TagField(*, name, type=FieldTypes.TAG, path=None, attrs=\u003cfactory\u003e)`\n\nBases: `BaseField`\n\nTag field for simple boolean-style filtering\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.TAG* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([TagFieldAttributes](#tagfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[TagFieldAttributes](#tagfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.TAG]`\n\nField type\n\n### `class TagFieldAttributes(*, sortable=False, index_missing=False, no_index=False, separator=',', case_sensitive=False, withsuffixtrie=False, index_empty=False)`\n\nTag field attributes\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **sortable** (*bool*)\n  * **index_missing** (*bool*)\n  * **no_index** (*bool*)\n  * **separator** (*str*)\n  * **case_sensitive** (*bool*)\n  * **withsuffixtrie** (*bool*)\n  * **index_empty** (*bool*)\n\n#### `case_sensitive: bool`\n\nTreat text as case sensitive or not. By default, tag characters are converted to lowercase\n\n#### `index_empty: bool`\n\nAllow indexing and searching for empty strings\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `separator: str`\n\nIndicates how the text in the original attribute is split into individual tags\n\n#### `withsuffixtrie: bool`\n\nKeep a suffix trie with all terms which match the suffix to optimize certain queries\n\n### `Numeric Fields`\n\nNumeric fields support range queries and sorting on numeric data.\n\n### `class NumericField(*, name, type=FieldTypes.NUMERIC, path=None, attrs=\u003cfactory\u003e)`\n\nBases: `BaseField`\n\nNumeric field for numeric range filtering\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.NUMERIC* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([NumericFieldAttributes](#numericfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[NumericFieldAttributes](#numericfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.NUMERIC]`\n\nField type\n\n### `class NumericFieldAttributes(*, sortable=False, index_missing=False, no_index=False, unf=False)`\n\nNumeric field attributes\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **sortable** (*bool*)\n  * **index_missing** (*bool*)\n  * **no_index** (*bool*)\n  * **unf** (*bool*)\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `unf: bool`\n\nUn-normalized form - disable normalization on sortable fields (only applies when sortable=True)\n\n### `Geo Fields`\n\nGeo fields enable location-based search with geographic coordinates.\n\n### `class GeoField(*, name, type=FieldTypes.GEO, path=None, attrs=\u003cfactory\u003e)`\n\nBases: `BaseField`\n\nGeo field with a geo-spatial index for location based search\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.GEO* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([GeoFieldAttributes](#geofieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[GeoFieldAttributes](#geofieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.GEO]`\n\nField type\n\n### `class GeoFieldAttributes(*, sortable=False, index_missing=False, no_index=False)`\n\nNumeric field attributes\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **sortable** (*bool*)\n  * **index_missing** (*bool*)\n  * **no_index** (*bool*)\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n## Vector Field Types\n\nVector fields enable semantic similarity search using various algorithms. All vector fields share common attributes but have algorithm-specific configurations.\n\n### `Common Vector Attributes`\n\nAll vector field types share these base attributes:\n\n### `class BaseVectorFieldAttributes(*, dims, algorithm, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False)`\n\nBase vector field attributes shared by FLAT, HNSW, and SVS-VAMANA fields\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **dims** (*int*)\n  * **algorithm** (*VectorIndexAlgorithm*)\n  * **datatype** (*VectorDataType*)\n  * **distance_metric** (*VectorDistanceMetric*)\n  * **initial_cap** (*int* *|* *None*)\n  * **index_missing** (*bool*)\n\n#### `classmethod uppercase_strings(v)`\n\nValidate that provided values are cast to uppercase\n\n#### `algorithm: VectorIndexAlgorithm`\n\nFLAT, HNSW, or SVS-VAMANA\n\n* **Type:**\n  The indexing algorithm for the field\n\n#### `datatype: VectorDataType`\n\nThe float datatype for the vector embeddings\n\n#### `dims: int`\n\nDimensionality of the vector embeddings field\n\n#### `distance_metric: VectorDistanceMetric`\n\nThe distance metric used to measure query relevance\n\n#### `property field_data: Dict[str, Any]`\n\nSelect attributes required by the Redis API\n\n#### `index_missing: bool`\n\nAllow indexing and searching for missing values (documents without the field)\n\n#### `initial_cap: int | None`\n\nInitial vector capacity in the index affecting memory allocation size of the index\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n**Key Attributes:**\n\n- dims: Dimensionality of the vector (e.g., 768, 1536).\n- algorithm: Indexing algorithm for vector search:\n  - flat: Brute-force exact search. 100% recall, slower for large datasets. Best for \u003c10K vectors.\n  - hnsw: Graph-based approximate search. Fast with high recall (95-99%). Best for general use.\n  - 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.\n\n  #### NOTE\n  For detailed algorithm comparison and selection guidance, see [Vector Algorithm Comparison](#vector-algorithm-comparison).\n- datatype: Float precision (bfloat16, float16, float32, float64). Note: SVS-VAMANA only supports float16 and float32.\n- distance_metric: Similarity metric (COSINE, L2, IP).\n- initial_cap: Initial capacity hint for memory allocation (optional).\n- index_missing: When True, allows searching for documents missing this field (optional).\n\n### `HNSW Vector Fields`\n\nHNSW (Hierarchical Navigable Small World) - Graph-based approximate search with excellent recall. **Best for general-purpose vector search (10K-1M+ vectors).**\n\n### `When to use HNSW \u0026 Performance Details`\n\n**Use HNSW when:**\n\n- Medium to large datasets (100K-1M+ vectors) requiring high recall rates\n- Search accuracy is more important than memory usage\n- Need general-purpose vector search with balanced performance\n- Cross-platform deployments where hardware-specific optimizations aren’t available\n\n**Performance characteristics:**\n\n- **Search speed**: Very fast approximate search with tunable accuracy\n- **Memory usage**: Higher than compressed SVS-VAMANA but reasonable for most applications\n- **Recall quality**: Excellent recall rates (95-99%), often better than other approximate methods\n- **Build time**: Moderate construction time, faster than SVS-VAMANA for smaller datasets\n\n### `class HNSWVectorField(*, name, type='vector', path=None, attrs)`\n\nBases: `BaseField`\n\nVector field with HNSW (Hierarchical Navigable Small World) indexing for approximate nearest neighbor search.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *'vector'* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([HNSWVectorFieldAttributes](#hnswvectorfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[HNSWVectorFieldAttributes](#hnswvectorfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal['vector']`\n\nField type\n\n### `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)`\n\nHNSW vector field attributes for approximate nearest neighbor search.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **dims** (*int*)\n  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.HNSW* *]*)\n  * **datatype** (*VectorDataType*)\n  * **distance_metric** (*VectorDistanceMetric*)\n  * **initial_cap** (*int* *|* *None*)\n  * **index_missing** (*bool*)\n  * **m** (*int*)\n  * **ef_construction** (*int*)\n  * **ef_runtime** (*int*)\n  * **epsilon** (*float*)\n\n#### `algorithm: Literal[VectorIndexAlgorithm.HNSW]`\n\nThe indexing algorithm (fixed as ‘hnsw’)\n\n#### `ef_construction: int`\n\n100-800)\n\n* **Type:**\n  Max edge candidates during build time (default\n* **Type:**\n  200, range\n\n#### `ef_runtime: int`\n\n1. - primary tuning parameter\n\n* **Type:**\n  Max top candidates during search (default\n\n#### `epsilon: float`\n\n0.01)\n\n* **Type:**\n  Range search boundary factor (default\n\n#### `m: int`\n\n8-64)\n\n* **Type:**\n  Max outgoing edges per node in each layer (default\n* **Type:**\n  16, range\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n**HNSW Examples:**\n\n**Balanced configuration (recommended starting point):**\n\n```yaml\n- name: embedding\n  type: vector\n  attrs:\n    algorithm: hnsw\n    dims: 768\n    distance_metric: cosine\n    datatype: float32\n    # Balanced settings for good recall and performance\n    m: 16\n    ef_construction: 200\n    ef_runtime: 10\n```\n\n**High-recall configuration:**\n\n```yaml\n- name: embedding\n  type: vector\n  attrs:\n    algorithm: hnsw\n    dims: 768\n    distance_metric: cosine\n    datatype: float32\n    # Tuned for maximum accuracy\n    m: 32\n    ef_construction: 400\n    ef_runtime: 50\n```\n\n### `SVS-VAMANA Vector Fields`\n\nSVS-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 (\u003e100K vectors) on Intel hardware with memory constraints.**\n\n### `When to use SVS-VAMANA \u0026 Detailed Guide`\n\n**Requirements:**\n: - Redis \u003e= 8.2.0 with RediSearch \u003e= 2.8.10\n  - datatype must be ‘float16’ or ‘float32’ (float64/bfloat16 not supported)\n\n**Use SVS-VAMANA when:**\n: - Large datasets where memory is expensive\n  - Cloud deployments with memory-based pricing\n  - When 90-95% recall is acceptable\n  - High-dimensional vectors (\u003e1024 dims) with LeanVec compression\n\n**Performance vs other algorithms:**\n: - **vs FLAT**: Much faster search, significantly lower memory usage with compression, but approximate results\n  - **vs HNSW**: Better memory efficiency with compression, similar or better recall, Intel-optimized\n\n**Compression selection guide:**\n\n- **No compression**: Best performance, standard memory usage\n- **LVQ4/LVQ8**: Good balance of compression (2x-4x) and performance\n- **LeanVec4x8/LeanVec8x8**: Maximum compression (up to 8x) with dimensionality reduction\n\n**Memory Savings Examples (1M vectors, 768 dims):**\n: - No compression (float32): 3.1 GB\n  - LVQ4x4 compression: 1.6 GB (~48% savings)\n  - LeanVec4x8 + reduce to 384: 580 MB (~81% savings)\n\n### `class SVSVectorField(*, name, type=FieldTypes.VECTOR, path=None, attrs)`\n\nBases: `BaseField`\n\nVector field with SVS-VAMANA indexing and compression for memory-efficient approximate nearest neighbor search.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.VECTOR* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([SVSVectorFieldAttributes](#svsvectorfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[SVSVectorFieldAttributes](#svsvectorfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.VECTOR]`\n\nField type\n\n### `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)`\n\nSVS-VAMANA vector field attributes with compression support.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **dims** (*int*)\n  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.SVS_VAMANA* *]*)\n  * **datatype** (*VectorDataType*)\n  * **distance_metric** (*VectorDistanceMetric*)\n  * **initial_cap** (*int* *|* *None*)\n  * **index_missing** (*bool*)\n  * **graph_max_degree** (*int*)\n  * **construction_window_size** (*int*)\n  * **search_window_size** (*int*)\n  * **epsilon** (*float*)\n  * **compression** (*CompressionType* *|* *None*)\n  * **reduce** (*int* *|* *None*)\n  * **training_threshold** (*int* *|* *None*)\n\n#### `validate_svs_params()`\n\nValidate SVS-VAMANA specific constraints\n\n#### `algorithm: Literal[VectorIndexAlgorithm.SVS_VAMANA]`\n\nThe indexing algorithm for the vector field\n\n#### `compression: CompressionType | None`\n\nLVQ4, LVQ8, LeanVec4x8, LeanVec8x8\n\n* **Type:**\n  Vector compression\n\n#### `construction_window_size: int`\n\n1. - affects quality vs build time\n\n* **Type:**\n  Build-time candidates (default\n\n#### `epsilon: float`\n\n0.01)\n\n* **Type:**\n  Range query boundary factor (default\n\n#### `graph_max_degree: int`\n\n1. - affects recall vs memory\n\n* **Type:**\n  Max edges per node (default\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `reduce: int | None`\n\nDimensionality reduction for LeanVec types (must be \u003c dims)\n\n#### `search_window_size: int`\n\n1. - primary tuning parameter\n\n* **Type:**\n  Search candidates (default\n\n#### `training_threshold: int | None`\n\n10,240)\n\n* **Type:**\n  Min vectors before compression training (default\n\n**SVS-VAMANA Examples:**\n\n**Basic configuration (no compression):**\n\n```yaml\n- name: embedding\n  type: vector\n  attrs:\n    algorithm: svs-vamana\n    dims: 768\n    distance_metric: cosine\n    datatype: float32\n    # Standard settings for balanced performance\n    graph_max_degree: 40\n    construction_window_size: 250\n    search_window_size: 20\n```\n\n**High-performance configuration with compression:**\n\n```yaml\n- name: embedding\n  type: vector\n  attrs:\n    algorithm: svs-vamana\n    dims: 768\n    distance_metric: cosine\n    datatype: float32\n    # Tuned for better recall\n    graph_max_degree: 64\n    construction_window_size: 500\n    search_window_size: 40\n    # Maximum compression with dimensionality reduction\n    compression: LeanVec4x8\n    reduce: 384  # 50% dimensionality reduction\n    training_threshold: 1000\n```\n\n**Important Notes:**\n\n- **Requirements**: SVS-VAMANA requires Redis \u003e= 8.2 with RediSearch \u003e= 2.8.10.\n- **Datatype limitations**: SVS-VAMANA only supports float16 and float32 datatypes (not bfloat16 or float64).\n- **Compression compatibility**: The reduce parameter is only valid with LeanVec compression types (LeanVec4x8 or LeanVec8x8).\n- **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.\n- **Performance tip**: Start with default parameters and tune search_window_size first for your speed vs accuracy requirements.\n\n### `FLAT Vector Fields`\n\nFLAT - Brute-force exact search. **Best for small datasets (\u003c10K vectors) requiring 100% accuracy.**\n\n### `When to use FLAT \u0026 Performance Details`\n\n**Use FLAT when:**\n: - Small datasets (\u003c100K vectors) where exact results are required\n  - Search accuracy is critical and approximate results are not acceptable\n  - Baseline comparisons when evaluating approximate algorithms\n  - Simple use cases where setup simplicity is more important than performance\n\n**Performance characteristics:**\n: - **Search accuracy**: 100% exact results (no approximation)\n  - **Search speed**: Linear time O(n) - slower as dataset grows\n  - **Memory usage**: Minimal overhead, stores vectors as-is\n  - **Build time**: Fastest index construction (no preprocessing)\n\n**Trade-offs vs other algorithms:**\n: - **vs HNSW**: Much slower search but exact results, faster index building\n  - **vs SVS-VAMANA**: Slower search and higher memory usage, but exact results\n\n### `class FlatVectorField(*, name, type=FieldTypes.VECTOR, path=None, attrs)`\n\nBases: `BaseField`\n\nVector field with FLAT (exact search) indexing for exact nearest neighbor search.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **name** (*str*)\n  * **type** (*Literal* *[* *FieldTypes.VECTOR* *]*)\n  * **path** (*str* *|* *None*)\n  * **attrs** ([FlatVectorFieldAttributes](#flatvectorfieldattributes))\n\n#### `as_redis_field()`\n\nConvert schema field to Redis Field object\n\n* **Return type:**\n  *Field*\n\n#### `attrs: `[FlatVectorFieldAttributes](#flatvectorfieldattributes)\n\nSpecified field attributes\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n#### `type: Literal[FieldTypes.VECTOR]`\n\nField type\n\n### `class FlatVectorFieldAttributes(*, dims, algorithm=VectorIndexAlgorithm.FLAT, datatype=VectorDataType.FLOAT32, distance_metric=VectorDistanceMetric.COSINE, initial_cap=None, index_missing=False, block_size=None)`\n\nFLAT vector field attributes for exact nearest neighbor search.\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n* **Parameters:**\n  * **dims** (*int*)\n  * **algorithm** (*Literal* *[* *VectorIndexAlgorithm.FLAT* *]*)\n  * **datatype** (*VectorDataType*)\n  * **distance_metric** (*VectorDistanceMetric*)\n  * **initial_cap** (*int* *|* *None*)\n  * **index_missing** (*bool*)\n  * **block_size** (*int* *|* *None*)\n\n#### `algorithm: Literal[VectorIndexAlgorithm.FLAT]`\n\nThe indexing algorithm (fixed as ‘flat’)\n\n#### `block_size: int | None`\n\nBlock size for processing (optional) - improves batch operation throughput\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n**FLAT Example:**\n\n```yaml\n- name: embedding\n  type: vector\n  attrs:\n    algorithm: flat\n    dims: 768\n    distance_metric: cosine\n    datatype: float32\n    # Optional: tune for batch processing\n    block_size: 1024\n```\n\n**Note**: FLAT is recommended for small datasets or when exact results are mandatory. For larger datasets, consider HNSW or SVS-VAMANA for better performance.\n\n## SVS-VAMANA Configuration Utilities\n\nFor SVS-VAMANA indices, RedisVL provides utilities to help configure compression settings and estimate memory savings.\n\n### `CompressionAdvisor`\n\n### `class CompressionAdvisor`\n\nBases: `object`\n\nHelper to recommend compression settings based on vector characteristics.\n\nThis class provides utilities to:\n- Recommend optimal SVS-VAMANA configurations based on vector dimensions and priorities\n- Estimate memory savings from compression and dimensionality reduction\n\n### `Examples`\n\n```pycon\n\u003e\u003e # Get recommendations for high-dimensional vectors\n\u003e\u003e config = CompressionAdvisor.recommend(dims=1536, priority=\"balanced\")\n\u003e\u003e config.compression\n'LeanVec4x8'\n\u003e\u003e config.reduce\n768\n```\n\n```pycon\n\u003e\u003e # Estimate memory savings\n\u003e\u003e savings = CompressionAdvisor.estimate_memory_savings(\n...     compression=\"LeanVec4x8\",\n...     dims=1536,\n...     reduce=768\n... )\n\u003e\u003e savings\n81.2\n```\n\n#### `static estimate_memory_savings(compression, dims, reduce=None)`\n\nEstimate memory savings percentage from compression.\n\nCalculates the percentage of memory saved compared to uncompressed float32 vectors.\n\n* **Parameters:**\n  * **compression** (*str*) – Compression type (e.g., \"LVQ4\", \"LeanVec4x8\")\n  * **dims** (*int*) – Original vector dimensionality\n  * **reduce** (*int* *|* *None*) – Reduced dimensionality (for LeanVec compression)\n* **Returns:**\n  Memory savings percentage (0-100)\n* **Return type:**\n  float\n\n### `Examples`\n\n```pycon\n\u003e\u003e # LeanVec with dimensionality reduction\n\u003e\u003e CompressionAdvisor.estimate_memory_savings(\n...     compression=\"LeanVec4x8\",\n...     dims=1536,\n...     reduce=768\n... )\n81.2\n```\n\n```pycon\n\u003e\u003e # LVQ without dimensionality reduction\n\u003e\u003e CompressionAdvisor.estimate_memory_savings(\n...     compression=\"LVQ4\",\n...     dims=384\n... )\n87.5\n```\n\n#### `static recommend(dims, priority='balanced', datatype=None)`\n\nRecommend compression settings based on dimensions and priorities.\n\n* **Parameters:**\n  * **dims** (*int*) – Vector dimensionality (must be \u003e 0)\n  * **priority** (*Literal* *[* *'speed'* *,*  *'memory'* *,*  *'balanced'* *]*) – Optimization priority:\n    - \"memory\": Maximize memory savings\n    - \"speed\": Optimize for query speed\n    - \"balanced\": Balance between memory and speed\n  * **datatype** (*str* *|* *None*) – Override datatype (default: float16 for high-dim, float32 for low-dim)\n* **Returns:**\n  Complete SVS-VAMANA configuration including:\n  : - algorithm: \"svs-vamana\"\n    - datatype: Recommended datatype\n    - compression: Compression type\n    - reduce: Dimensionality reduction (for LeanVec only)\n    - graph_max_degree: Graph connectivity\n    - construction_window_size: Build-time candidates\n    - search_window_size: Query-time candidates\n* **Return type:**\n  dict\n* **Raises:**\n  **ValueError** – If dims \u003c= 0\n\n### `Examples`\n\n```pycon\n\u003e\u003e # High-dimensional embeddings (e.g., OpenAI ada-002)\n\u003e\u003e config = CompressionAdvisor.recommend(dims=1536, priority=\"memory\")\n\u003e\u003e config.compression\n'LeanVec4x8'\n\u003e\u003e config.reduce\n768\n```\n\n```pycon\n\u003e\u003e # Lower-dimensional embeddings\n\u003e\u003e config = CompressionAdvisor.recommend(dims=384, priority=\"speed\")\n\u003e\u003e config.compression\n'LVQ4x8'\n```\n\n### `SVSConfig`\n\n### `class SVSConfig(*, algorithm='svs-vamana', datatype=None, compression=None, reduce=None, graph_max_degree=None, construction_window_size=None, search_window_size=None)`\n\nBases: `BaseModel`\n\nSVS-VAMANA configuration model.\n\n* **Parameters:**\n  * **algorithm** (*Literal* *[* *'svs-vamana'* *]*)\n  * **datatype** (*str* *|* *None*)\n  * **compression** (*str* *|* *None*)\n  * **reduce** (*int* *|* *None*)\n  * **graph_max_degree** (*int* *|* *None*)\n  * **construction_window_size** (*int* *|* *None*)\n  * **search_window_size** (*int* *|* *None*)\n\n#### `algorithm`\n\nAlways \"svs-vamana\"\n\n* **Type:**\n  Literal[‘svs-vamana’]\n\n#### `datatype`\n\nVector datatype (float16, float32)\n\n* **Type:**\n  str | None\n\n#### `compression`\n\nCompression type (LVQ4, LeanVec4x8, etc.)\n\n* **Type:**\n  str | None\n\n#### `reduce`\n\nReduced dimensionality (only for LeanVec)\n\n* **Type:**\n  int | None\n\n#### `graph_max_degree`\n\nMax edges per node\n\n* **Type:**\n  int | None\n\n#### `construction_window_size`\n\nBuild-time candidates\n\n* **Type:**\n  int | None\n\n#### `search_window_size`\n\nQuery-time candidates\n\n* **Type:**\n  int | None\n\nCreate a new model by parsing and validating input data from keyword arguments.\n\nRaises [ValidationError][pydantic_core.ValidationError] if the input data cannot be\nvalidated to form a valid model.\n\nself is explicitly positional-only to allow self as a field name.\n\n#### `model_config: ClassVar[ConfigDict] = {}`\n\nConfiguration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].\n\n\u003ca id=\"vector-algorithm-comparison\"\u003e\u003c/a\u003e\n\n## Vector Algorithm Comparison\n\nThis section provides detailed guidance for choosing between vector search algorithms.\n\n### `Algorithm Selection Guide`\n\n#### `Vector Algorithm Comparison`\n\n| Algorithm      | Best For                               | Performance                    | Memory Usage              | Trade-offs                            |\n|----------------|----------------------------------------|--------------------------------|---------------------------|---------------------------------------|\n| **FLAT**       | Small datasets (\u003c100K vectors)         | 100% recall, O(n) search       | Minimal overhead          | Exact but slow for large data         |\n| **HNSW**       | General purpose (100K-1M+ vectors)     | 95-99% recall, O(log n) search | Moderate (graph overhead) | Fast approximate search               |\n| **SVS-VAMANA** | Large datasets with memory constraints | 90-95% recall, O(log n) search | Low (with compression)    | Intel-optimized, requires newer Redis |\n\n### `When to Use Each Algorithm`\n\n**Choose FLAT when:**\n: - Dataset size \u003c 100,000 vectors\n  - Exact results are mandatory\n  - Simple setup is preferred\n  - Query latency is not critical\n\n**Choose HNSW when:**\n: - Dataset size 100K - 1M+ vectors\n  - Need balanced speed and accuracy\n  - Cross-platform compatibility required\n  - Most common choice for production\n\n**Choose SVS-VAMANA when:**\n: - Dataset size \u003e 100K vectors\n  - Memory usage is a primary concern\n  - Running on Intel hardware\n  - Can accept 90-95% recall for memory savings\n\n### `Performance Characteristics`\n\n**Search Speed:**\n: - FLAT: Linear time O(n) - gets slower as data grows\n  - HNSW: Logarithmic time O(log n) - scales well\n  - SVS-VAMANA: Logarithmic time O(log n) - scales well\n\n**Memory Usage (1M vectors, 768 dims, float32):**\n: - FLAT: ~3.1 GB (baseline)\n  - HNSW: ~3.7 GB (20% overhead for graph)\n  - SVS-VAMANA: 1.6-3.1 GB (depends on compression)\n\n**Recall Quality:**\n: - FLAT: 100% (exact search)\n  - HNSW: 95-99% (tunable via ef_runtime)\n  - SVS-VAMANA: 90-95% (depends on compression)\n\n### `Migration Considerations`\n\n**From FLAT to HNSW:**\n: - Straightforward migration\n  - Expect slight recall reduction but major speed improvement\n  - Tune ef_runtime to balance speed vs accuracy\n\n**From HNSW to SVS-VAMANA:**\n: - Requires Redis \u003e= 8.2 with RediSearch \u003e= 2.8.10\n  - Change datatype to float16 or float32 if using others\n  - Consider compression options for memory savings\n\n**From SVS-VAMANA to others:**\n: - May need to change datatype back if using float64/bfloat16\n  - HNSW provides similar performance with broader compatibility\n\nFor complete Redis field documentation, see: [https://redis.io/commands/ft.create/](https://redis.io/commands/ft.create/)\n",
  "tags": [],
  "last_updated": "2026-04-01T08:10:08-05:00"
}