Add secondary indexes to accelerate cache lookups

src/sqlmem/engine.py

@@ -24,6 +24,7 @@ class CachingEngine:
         source_engine: Engine,
         delta: dict[str, DeltaConfig] | None = None,
         ttl: dict[str, int] | None = None,
+        indexes: dict[str, list[str | list[str]]] | None = None,
     ) -> None:
         self._source_engine = source_engine
         self._cache = CacheManager(CACHE_DB_PATH, BACKUP_INTERVAL_SECONDS)
@@ -32,6 +33,7 @@ class CachingEngine:
         self._refresh_interval = REFRESH_INTERVAL_SECONDS
         self._delta = self._resolve_delta(delta or {})
         self._ttl = dict(ttl or {})
+        self._index_columns = self._register_indexes(indexes or {})
         self._refresher = DeltaRefresher(self._cache, self._delta)
 
         overlap = set(self._delta) & set(self._ttl)
@@ -48,6 +50,22 @@ class CachingEngine:
 
         logger.info("CachingEngine initialized.")
 
+    def _register_indexes(
+        self, indexes: dict[str, list[str | list[str]]]
+    ) -> dict[str, list[str]]:
+        """Register secondary indexes on the cache; return columns to load per table."""
+        index_columns: dict[str, list[str]] = {}
+        for table, specs in indexes.items():
+            wanted: list[str] = []
+            for spec in specs:
+                columns = [spec] if isinstance(spec, str) else list(spec)
+                self._cache.add_index(table, columns)
+                for col in columns:
+                    if col not in wanted:
+                        wanted.append(col)
+            index_columns[table] = wanted
+        return index_columns
+
     def _resolve_delta(self, delta: dict[str, DeltaConfig]) -> dict[str, ResolvedDelta]:
         """Resolve each DeltaConfig, auto-discovering the primary key when omitted."""
         resolved: dict[str, ResolvedDelta] = {}
@@ -95,7 +113,13 @@ class CachingEngine:
         with self._source_engine.connect() as sa_conn:
             raw_conn = cast(sqlite3.Connection, sa_conn.connection.dbapi_connection)
             executor = QueryExecutor(
-                self._cache, self._registry, raw_conn, self._stats, self._delta, self._ttl
+                self._cache,
+                self._registry,
+                raw_conn,
+                self._stats,
+                self._delta,
+                self._ttl,
+                self._index_columns,
             )
             return executor.execute(parsed)