Concepts

Foundational reading for sql-redis. Each page explains a single design choice or sub-system, with enough context to make informed extensions or contributions.

• Architecture

  ---

  The two top-level objects (Executor, SchemaRegistry) and the layered translator they contain.

• Why SQL?

  ---

  The interface choice. SQL versus a pandas-style DSL versus a builder API.

• Why sqlglot?

  ---

  The parser choice. sqlglot versus a hand-rolled recursive-descent parser.

• Schema-aware translation

  ---

  Why field types matter, how the schema registry caches them, lazy versus eager loading.

• FT.SEARCH vs FT.AGGREGATE

  ---

  Which Redis command runs for a given SQL, why the choice is forced, and which feature combinations are illegal.

• Parameter substitution

  ---

  The token-based substitution algorithm and the bugs it fixes.

• Vector substitution

  ---

  Why bytes parameters take a different path: two-stage substitution that keeps vectors out of the SQL string.

• Async invariants

  ---

  Coalesced FT.INFO loads, shielded reads, invalidate-cancels-in-flight. The three guarantees the async path provides.

• Result shape

  ---

  What QueryResult.rows actually contains, why it varies with the command, scoring, and client decoding.

• Testing philosophy

  ---

  TDD, 100% coverage, and why integration tests do not mock Redis.