Merge pull request #19 from redis-developer/feat/RAAE-1542/schema_lazy_load

executor factory pattern

Author: rbs333

sql_redis/__init__.py

@@ -1,6 +1,13 @@
 """SQL to Redis command translation utility."""
 
-from sql_redis.executor import AsyncExecutor, Executor, QueryResult
+from sql_redis.executor import (
+    AsyncExecutor,
+    Executor,
+    QueryResult,
+    SchemaCacheStrategy,
+    create_async_executor,
+    create_executor,
+)
 from sql_redis.schema import AsyncSchemaRegistry, SchemaRegistry
 from sql_redis.translator import TranslatedQuery, Translator
 from sql_redis.version import __version__
@@ -12,6 +19,9 @@
     "AsyncSchemaRegistry",
     "Executor",
     "AsyncExecutor",
+    "create_executor",
+    "create_async_executor",
+    "SchemaCacheStrategy",
     "QueryResult",
     "__version__",
 ]

sql_redis/executor.py

@@ -4,7 +4,7 @@
 
 import re
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal, cast
 
 import redis
 
@@ -15,6 +15,18 @@
     import redis.asyncio as async_redis
 
 
+SchemaCacheStrategy = Literal["lazy", "load_all"]
+
+
+def _validate_schema_cache_strategy(
+    schema_cache_strategy: str,
+) -> SchemaCacheStrategy:
+    """Validate and normalize the schema cache strategy."""
+    if schema_cache_strategy not in {"lazy", "load_all"}:
+        raise ValueError("schema_cache_strategy must be one of: 'lazy', 'load_all'")
+    return cast(SchemaCacheStrategy, schema_cache_strategy)
+
+
 def _substitute_params(sql: str, params: dict[str, Any]) -> str:
     """Substitute parameter placeholders in SQL with actual values.
 
@@ -270,3 +282,51 @@ async def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
                 rows.append(row)
 
         return QueryResult(rows=rows, count=count)
+
+
+def create_executor(
+    client: redis.Redis,
+    *,
+    schema_registry: SchemaRegistry | None = None,
+    schema_cache_strategy: SchemaCacheStrategy = "lazy",
+) -> Executor:
+    """Create a sync SQL executor with the requested schema cache strategy.
+
+    Args:
+        client: Redis client used by the executor.
+        schema_registry: Optional existing registry to reuse.
+        schema_cache_strategy: Schema loading strategy. ``"lazy"`` defers
+            ``FT.INFO`` calls until a referenced index is needed. ``"load_all"``
+            preserves the historical eager behavior by preloading all schemas.
+    """
+    schema_cache_strategy = _validate_schema_cache_strategy(schema_cache_strategy)
+
+    registry = schema_registry or SchemaRegistry(client)
+    if schema_cache_strategy == "load_all":
+        registry.load_all()
+
+    return Executor(client, registry)
+
+
+async def create_async_executor(
+    client: "async_redis.Redis",
+    *,
+    schema_registry: AsyncSchemaRegistry | None = None,
+    schema_cache_strategy: SchemaCacheStrategy = "lazy",
+) -> AsyncExecutor:
+    """Create an async SQL executor with the requested schema cache strategy.
+
+    Args:
+        client: Async Redis client used by the executor.
+        schema_registry: Optional existing async registry to reuse.
+        schema_cache_strategy: Schema loading strategy. ``"lazy"`` defers
+            ``FT.INFO`` calls until a referenced index is needed. ``"load_all"``
+            preserves the historical eager behavior by preloading all schemas.
+    """
+    schema_cache_strategy = _validate_schema_cache_strategy(schema_cache_strategy)
+
+    registry = schema_registry or AsyncSchemaRegistry(client)
+    if schema_cache_strategy == "load_all":
+        await registry.load_all()
+
+    return AsyncExecutor(client, registry)

tests/test_schema_caching.py

@@ -16,7 +16,12 @@
 import redis
 import redis.asyncio as async_redis
 
-from sql_redis.executor import AsyncExecutor, Executor
+from sql_redis.executor import (
+    AsyncExecutor,
+    Executor,
+    create_async_executor,
+    create_executor,
+)
 from sql_redis.schema import AsyncSchemaRegistry, SchemaRegistry
 
 # ---------------------------------------------------------------------------
@@ -322,6 +327,42 @@ def test_executor_multiple_queries_reuse_cache(
         assert schema_after_first is schema_after_second
 
 
+class TestExecutorFactories:
+    """Factory helpers configure schema loading strategies correctly."""
+
+    def test_create_executor_defaults_to_lazy(
+        self, redis_client: redis.Redis, caching_indexes: list[str]
+    ):
+        """Default factory behavior should not preload schemas."""
+        executor = create_executor(redis_client)
+
+        assert isinstance(executor, Executor)
+        assert executor._schema_registry._schemas == {}
+
+    def test_create_executor_load_all_preloads_schemas(
+        self, redis_client: redis.Redis, caching_indexes: list[str]
+    ):
+        """load_all strategy preserves eager schema loading."""
+        executor = create_executor(redis_client, schema_cache_strategy="load_all")
+
+        assert set(executor._schema_registry._schemas) == set(caching_indexes)
+
+    def test_create_executor_reuses_registry(
+        self, redis_client: redis.Redis, caching_indexes: list[str]
+    ):
+        """Factories should preserve a caller-provided registry instance."""
+        registry = SchemaRegistry(redis_client)
+
+        executor = create_executor(
+            redis_client,
+            schema_registry=registry,
+            schema_cache_strategy="load_all",
+        )
+
+        assert executor._schema_registry is registry
+        assert set(registry._schemas) == set(caching_indexes)
+
+
 # ---------------------------------------------------------------------------
 # Tests: Negative caching (sync)
 # ---------------------------------------------------------------------------
@@ -767,3 +808,48 @@ async def test_async_executor_multiple_queries_reuse_cache(
         assert result2.count == 1
         # Same dict object — was not re-fetched
         assert schema_after_first is schema_after_second
+
+
+class TestAsyncExecutorFactories:
+    """Async factory helpers configure schema loading strategies correctly."""
+
+    async def test_create_async_executor_defaults_to_lazy(
+        self,
+        async_caching_client: async_redis.Redis,
+        async_caching_indexes: list[str],
+    ):
+        """Default async factory behavior should not preload schemas."""
+        executor = await create_async_executor(async_caching_client)
+
+        assert isinstance(executor, AsyncExecutor)
+        assert executor._schema_registry._schemas == {}
+
+    async def test_create_async_executor_load_all_preloads_schemas(
+        self,
+        async_caching_client: async_redis.Redis,
+        async_caching_indexes: list[str],
+    ):
+        """Async load_all strategy preserves eager schema loading."""
+        executor = await create_async_executor(
+            async_caching_client,
+            schema_cache_strategy="load_all",
+        )
+
+        assert set(executor._schema_registry._schemas) == set(async_caching_indexes)
+
+    async def test_create_async_executor_reuses_registry(
+        self,
+        async_caching_client: async_redis.Redis,
+        async_caching_indexes: list[str],
+    ):
+        """Async factories should preserve a caller-provided registry instance."""
+        registry = AsyncSchemaRegistry(async_caching_client)
+
+        executor = await create_async_executor(
+            async_caching_client,
+            schema_registry=registry,
+            schema_cache_strategy="load_all",
+        )
+
+        assert executor._schema_registry is registry
+        assert set(registry._schemas) == set(async_caching_indexes)