fix: (schema) ensure field modifiers follow canonical order for RediSearch parser (#434)

Fix field modifier ordering to satisfy RediSearch parser requirements
where
INDEXEMPTY and INDEXMISSING must appear BEFORE SORTABLE in field
definitions.
This resolves index creation failures when using index_missing=True with
sortable=True.

Changes:
- Add _normalize_field_modifiers() helper function with set-based
optimization
- Refactor TextField, TagField, NumericField, GeoField to use helper
- Implement canonical order: [INDEXEMPTY] [INDEXMISSING] [SORTABLE
[UNF]] [NOINDEX]
- Add unit tests for helper and field classes
- Add integration tests against live Redis

Fixes: issue
[#431](#431 (comment))
Related: Field 'INDEXMISSING' does not have a type error

BREAKING CHANGE: None - backward compatible, only changes internal
ordering

Author: nkanu17

redisvl/schema/fields.py

@@ -35,7 +35,7 @@
 """
 
 from enum import Enum
-from typing import Any, Dict, Literal, Optional, Tuple, Type, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, Type, Union
 
 from pydantic import BaseModel, Field, field_validator, model_validator
 from redis.commands.search.field import Field as RedisField
@@ -97,6 +97,49 @@ class CompressionType(str, Enum):
     LeanVec8x8 = "LeanVec8x8"
 
 
+### Helper Functions ###
+
+
+def _normalize_field_modifiers(
+    field: RedisField, canonical_order: List[str], want_unf: bool = False
+) -> None:
+    """Normalize field modifier ordering for RediSearch parser.
+
+    RediSearch has a parser limitation where INDEXEMPTY and
+    INDEXMISSING must appear BEFORE SORTABLE in field definitions. This function
+    reorders field.args_suffix to match the canonical order.
+
+    Args:
+        field: Redis field object whose args_suffix will be normalized
+        canonical_order: List of modifiers in desired canonical order
+        want_unf: Whether UNF should be added after SORTABLE (default: False)
+
+    Time Complexity: O(n + m), where n = len(field.args_suffix), m = len(canonical_order).
+        - O(n) to create the set from field.args_suffix
+        - O(m) to iterate over canonical_order and perform set lookups (O(1) average case per lookup)
+    Space Complexity: O(n)
+
+    Example:
+        >>> field = RedisTextField("title")
+        >>> field.args_suffix = ["SORTABLE", "INDEXMISSING"]
+        >>> _normalize_field_modifiers(field, ["INDEXEMPTY", "INDEXMISSING", "SORTABLE"])
+        >>> field.args_suffix
+        ['INDEXMISSING', 'SORTABLE']
+    """
+    suffix_set = set(field.args_suffix)
+
+    # Build new suffix with only known modifiers in canonical order
+    new_suffix = []
+    for modifier in canonical_order:
+        if modifier in suffix_set:
+            new_suffix.append(modifier)
+            # Special case: UNF only appears with SORTABLE
+            if modifier == "SORTABLE" and want_unf and "UNF" not in suffix_set:
+                new_suffix.append("UNF")
+
+    field.args_suffix = new_suffix
+
+
 ### Field Attributes ###
 
 
@@ -290,7 +333,7 @@ def validate_svs_params(self):
         ):
             logger.warning(
                 f"LeanVec compression selected without 'reduce'. "
-                f"Consider setting reduce={self.dims//2} for better performance"
+                f"Consider setting reduce={self.dims // 2} for better performance"
             )
 
         if self.graph_max_degree and self.graph_max_degree < 32:
@@ -371,16 +414,11 @@ def as_redis_field(self) -> RedisField:
 
         field = RedisTextField(name, **kwargs)
 
-        # Add UNF support (only when sortable)
-        # UNF must come before NOINDEX in the args_suffix
-        if self.attrs.unf and self.attrs.sortable:  # type: ignore
-            if "NOINDEX" in field.args_suffix:
-                # Insert UNF before NOINDEX
-                noindex_idx = field.args_suffix.index("NOINDEX")
-                field.args_suffix.insert(noindex_idx, "UNF")
-            else:
-                # No NOINDEX, append normally
-                field.args_suffix.append("UNF")
+        # Normalize suffix ordering to satisfy RediSearch parser expectations.
+        # Canonical order: [INDEXEMPTY] [INDEXMISSING] [SORTABLE [UNF]] [NOINDEX]
+        canonical_order = ["INDEXEMPTY", "INDEXMISSING", "SORTABLE", "UNF", "NOINDEX"]
+        want_unf = self.attrs.unf and self.attrs.sortable  # type: ignore
+        _normalize_field_modifiers(field, canonical_order, want_unf)
 
         return field
 
@@ -416,7 +454,14 @@ def as_redis_field(self) -> RedisField:
         if self.attrs.no_index:  # type: ignore
             kwargs["no_index"] = True
 
-        return RedisTagField(name, **kwargs)
+        field = RedisTagField(name, **kwargs)
+
+        # Normalize suffix ordering to satisfy RediSearch parser expectations.
+        # Canonical order: [INDEXEMPTY] [INDEXMISSING] [SORTABLE] [NOINDEX]
+        canonical_order = ["INDEXEMPTY", "INDEXMISSING", "SORTABLE", "NOINDEX"]
+        _normalize_field_modifiers(field, canonical_order)
+
+        return field
 
 
 class NumericField(BaseField):
@@ -446,16 +491,12 @@ def as_redis_field(self) -> RedisField:
 
         field = RedisNumericField(name, **kwargs)
 
-        # Add UNF support (only when sortable)
-        # UNF must come before NOINDEX in the args_suffix
-        if self.attrs.unf and self.attrs.sortable:  # type: ignore
-            if "NOINDEX" in field.args_suffix:
-                # Insert UNF before NOINDEX
-                noindex_idx = field.args_suffix.index("NOINDEX")
-                field.args_suffix.insert(noindex_idx, "UNF")
-            else:
-                # No NOINDEX, append normally
-                field.args_suffix.append("UNF")
+        # Normalize suffix ordering to satisfy RediSearch parser expectations.
+        # Canonical order: [INDEXMISSING] [SORTABLE [UNF]] [NOINDEX]
+        # Note: INDEXEMPTY is not supported for NUMERIC fields
+        canonical_order = ["INDEXMISSING", "SORTABLE", "UNF", "NOINDEX"]
+        want_unf = self.attrs.unf and self.attrs.sortable  # type: ignore
+        _normalize_field_modifiers(field, canonical_order, want_unf)
 
         return field
 
@@ -485,7 +526,15 @@ def as_redis_field(self) -> RedisField:
         if self.attrs.no_index:  # type: ignore
             kwargs["no_index"] = True
 
-        return RedisGeoField(name, **kwargs)
+        field = RedisGeoField(name, **kwargs)
+
+        # Normalize suffix ordering to satisfy RediSearch parser expectations.
+        # Canonical order: [INDEXMISSING] [SORTABLE] [NOINDEX]
+        # Note: INDEXEMPTY is not supported for GEO fields
+        canonical_order = ["INDEXMISSING", "SORTABLE", "NOINDEX"]
+        _normalize_field_modifiers(field, canonical_order)
+
+        return field
 
 
 class FlatVectorField(BaseField):