sql-redis 0.1.0__tar.gz

sql_redis-0.1.0/.github/workflows/lint.yml

@@ -0,0 +1,57 @@
+name: Lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+env:
+  UV_VERSION: "0.7.13"
+
+jobs:
+  check:
+    name: Style-check ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.9"
+          - "3.11"
+          - "3.13"
+
+    steps:
+    - name: Check out repository
+      uses: actions/checkout@v6
+
+    - name: Install Python
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        version: ${{ env.UV_VERSION }}
+        enable-cache: true
+        python-version: ${{ matrix.python-version }}   # sets UV_PYTHON
+        cache-dependency-glob: |
+          pyproject.toml
+          uv.lock
+
+    - name: Install dependencies
+      run: |
+        uv sync --frozen
+
+    - name: check-sort-import
+      run: |
+        make check-sort-imports
+
+    - name: check-black-format
+      run: |
+        make check-format
+
+    - name: check-mypy
+      run: |
+        make check-types
+

sql_redis-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: Publish Release
+
+on:
+  release:
+    types: [published]
+
+env:
+  PYTHON_VERSION: "3.11"
+  UV_VERSION: "0.7.13"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: ${{ env.PYTHON_VERSION }}   # sets UV_PYTHON
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload build
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: ${{ env.PYTHON_VERSION }}   # sets UV_PYTHON
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install dependencies
+        run: |
+          uv sync --frozen
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI }}
+        run: uv publish

sql_redis-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,48 @@
+name: Test Suite
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  UV_VERSION: "0.7.13"
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Install Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          version: ${{ env.UV_VERSION }}
+          enable-cache: true
+          python-version: ${{ matrix.python-version }}   # sets UV_PYTHON
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Install dependencies
+        run: |
+          uv sync
+
+      - name: Run tests
+        run: |
+          make test
+

sql_redis-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.python-version
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.pytype/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+.ai/
+

sql_redis-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,17 @@
+repos:
+  - repo: local
+    hooks:
+      - id: code-quality-checks
+        name: Run pre-commit checks (format, sort-imports, check-mypy)
+        entry: bash -c 'make format && make check-sort-imports && make check-types'
+        language: system
+        pass_filenames: false
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.2.6
+    hooks:
+      - id: codespell
+        name: Check spelling
+        args:
+          - --write-changes
+          - --skip=*.pyc,*.pyo,*.lock,*.git,*.mypy_cache,__pycache__,*.egg-info,.pytest_cache,env,venv,.venv
+

sql_redis-0.1.0/Makefile

@@ -0,0 +1,67 @@
+.PHONY: install format lint test clean check-types check-format check-sort-imports sort-imports build help
+.DEFAULT_GOAL := help
+
+# Allow passing arguments to make targets (e.g., make test ARGS="...")
+ARGS ?=
+
+install: ## Install the project and all dependencies
+	@echo "🚀 Installing project dependencies with uv"
+	uv sync
+
+format: ## Format code with isort and black
+	@echo "🎨 Formatting code"
+	uv run isort ./sql_redis ./tests/ --profile black
+	uv run black ./sql_redis ./tests/
+
+check-format: ## Check code formatting
+	@echo "🔍 Checking code formatting"
+	uv run black --check ./sql_redis ./tests/
+
+sort-imports: ## Sort imports with isort
+	@echo "📦 Sorting imports"
+	uv run isort ./sql_redis ./tests/ --profile black
+
+check-sort-imports: ## Check import sorting
+	@echo "🔍 Checking import sorting"
+	uv run isort ./sql_redis ./tests/ --check-only --profile black
+
+check-types: ## Run mypy type checking
+	@echo "🔍 Running mypy type checking"
+	uv run python -m mypy ./sql_redis
+
+lint: format check-types ## Run all linting (format + type check)
+
+test: ## Run tests (pass extra args with ARGS="...")
+	@echo "🧪 Running tests"
+	uv run python -m pytest $(ARGS)
+
+test-verbose: ## Run tests with verbose output
+	@echo "🧪 Running tests (verbose)"
+	uv run python -m pytest -vv -s $(ARGS)
+
+test-cov: ## Run tests with coverage report
+	@echo "🧪 Running tests with coverage"
+	uv run python -m pytest --cov=sql_redis --cov-report=term-missing --cov-report=html $(ARGS)
+
+check: lint test ## Run all checks (lint + test)
+
+build: ## Build wheel and source distribution
+	@echo "🏗️ Building distribution packages"
+	uv build
+
+clean: ## Clean up build artifacts and caches
+	@echo "🧹 Cleaning up directory"
+	find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".mypy_cache" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name ".coverage" -delete 2>/dev/null || true
+	find . -type d -name "htmlcov" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "dist" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "build" -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.log" -exec rm -rf {} + 2>/dev/null || true
+
+help: ## Show this help message
+	@echo "Available commands:"
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2}'
+

sql_redis-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: sql-redis
+Version: 0.1.0
+Summary: SQL to Redis command translation utility
+Project-URL: Homepage, https://github.com/redis/sql-redis
+Project-URL: Repository, https://github.com/redis/sql-redis
+Author-email: "Redis Inc." <applied.ai@redis.com>
+License-Expression: MIT
+Keywords: query-translation,redis,redis-client,sql
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.9
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlglot>=26.0.0
+Description-Content-Type: text/markdown
+
+# sql-redis
+
+A proof-of-concept SQL-to-Redis translator that converts SQL SELECT statements into Redis `FT.SEARCH` and `FT.AGGREGATE` commands.
+
+## Status
+
+This is an **early POC** demonstrating feasibility, not a production-ready library. The goal is to explore design decisions and validate the approach before committing to a full implementation.
+
+## Quick Example
+
+```python
+from redis import Redis
+from sql_redis import Translator
+from sql_redis.schema import SchemaRegistry
+from sql_redis.executor import Executor
+
+client = Redis()
+registry = SchemaRegistry(client)
+registry.load_all()  # Loads index schemas from Redis
+
+executor = Executor(client, registry)
+
+# Simple query
+result = executor.execute("""
+    SELECT title, price 
+    FROM products 
+    WHERE category = 'electronics' AND price < 500
+    ORDER BY price ASC
+    LIMIT 10
+""")
+
+for row in result.rows:
+    print(row["title"], row["price"])
+
+# Vector search with params
+result = executor.execute("""
+    SELECT title, vector_distance(embedding, :vec) AS score
+    FROM products
+    LIMIT 5
+""", params={"vec": vector_bytes})
+```
+
+## Design Decisions
+
+### Why SQL instead of a pandas-like Python DSL?
+
+We considered several interface options:
+
+| Approach | Example | Trade-offs |
+|----------|---------|------------|
+| **SQL** | `SELECT * FROM products WHERE price > 100` | Universal, well-understood, tooling exists |
+| **Pandas-like** | `df[df.price > 100]` | Pythonic but limited to Python, no standard |
+| **Builder pattern** | `query.select("*").where(price__gt=100)` | Type-safe but verbose, learning curve |
+
+**We chose SQL because:**
+
+1. **Universality** — SQL is the lingua franca of data. Developers, analysts, and tools all speak it.
+2. **No new DSL to learn** — Users already know SQL. A pandas-like API requires learning our specific dialect.
+3. **Tooling compatibility** — SQL strings can be generated by ORMs, query builders, or AI assistants.
+4. **Clear mapping** — SQL semantics map reasonably well to RediSearch operations (SELECT→LOAD, WHERE→filter, GROUP BY→GROUPBY).
+
+The downside is losing Python's type checking and IDE support, but for a query interface, the universality trade-off is worth it.
+
+### Why sqlglot instead of writing a custom parser?
+
+**Options considered:**
+- **Custom parser** (regex, hand-rolled recursive descent)
+- **PLY/Lark** (parser generators)
+- **sqlglot** (production SQL parser)
+- **sqlparse** (tokenizer, not a full parser)
+
+**We chose sqlglot because:**
+
+1. **Battle-tested** — Used in production by companies like Tobiko (SQLMesh). Handles edge cases we'd miss.
+2. **Full AST** — Provides a complete abstract syntax tree, not just tokens. We can traverse and analyze queries properly.
+3. **Dialect support** — Handles SQL variations. Users can write MySQL-style or PostgreSQL-style queries.
+4. **Active maintenance** — Regular releases, responsive maintainers, good documentation.
+
+The alternative was writing a custom parser, which would be error-prone and time-consuming for a POC. sqlglot lets us focus on the translation logic rather than parsing edge cases.
+
+### Why schema-aware translation?
+
+Redis field types determine query syntax:
+
+| Field Type | Redis Syntax | Example |
+|------------|--------------|---------|
+| TEXT | `@field:term` | `@title:laptop` |
+| NUMERIC | `@field:[min max]` | `@price:[100 500]` |
+| TAG | `@field:{value}` | `@category:{books}` |
+
+**Without schema knowledge**, we can't translate `category = 'books'` correctly — it could be `@category:books` (TEXT search) or `@category:{books}` (TAG exact match).
+
+**Our approach:** The `SchemaRegistry` fetches index schemas via `FT.INFO` at startup. The translator uses this to generate correct syntax per field type.
+
+This adds a Redis round-trip at initialization but ensures correct query generation.
+
+### Architecture: Why this layered design?
+
+```
+SQL String
+    ↓
+┌─────────────────┐
+│   SQLParser     │  Parse SQL → ParsedQuery dataclass
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│ SchemaRegistry  │  Load field types from Redis
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│    Analyzer     │  Classify conditions by field type
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│  QueryBuilder   │  Generate RediSearch syntax per type
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│   Translator    │  Orchestrate pipeline, build command
+└────────┬────────┘
+         ↓
+┌─────────────────┐
+│    Executor     │  Execute command, parse results
+└────────┬────────┘
+         ↓
+QueryResult(rows, count)
+```
+
+**Why separate components?**
+
+1. **Testability** — Each layer has focused unit tests. 100% coverage is achievable because responsibilities are clear.
+2. **Single responsibility** — Parser doesn't know about Redis. QueryBuilder doesn't know about SQL. Changes are localized.
+3. **Extensibility** — Adding a new field type (e.g., GEO) means updating Analyzer and QueryBuilder, not rewriting everything.
+
+**Why not a single monolithic translator?**
+
+Early prototypes combined parsing and translation. This led to:
+- Tests that required Redis connections for simple SQL parsing tests
+- Difficulty testing edge cases in isolation
+- Tangled code that was hard to modify
+
+The layered approach emerged from TDD — writing tests first revealed natural boundaries.
+
+## What's Implemented
+
+- [x] Basic SELECT with field selection
+- [x] WHERE with TEXT, NUMERIC, TAG field types
+- [x] Comparison operators: `=`, `!=`, `<`, `<=`, `>`, `>=`, `BETWEEN`, `IN`
+- [x] Boolean operators: `AND`, `OR`
+- [x] Aggregations: `COUNT`, `SUM`, `AVG`, `MIN`, `MAX`
+- [x] `GROUP BY` with multiple aggregations
+- [x] `ORDER BY` with ASC/DESC
+- [x] `LIMIT` and `OFFSET` pagination
+- [x] Computed fields: `price * 0.9 AS discounted`
+- [x] Vector KNN search: `vector_distance(field, :param)`
+- [x] Hybrid search (filters + vector)
+- [x] Full-text search: `LIKE 'prefix%'` (prefix), `fulltext(field, 'terms')` function
+
+## What's Not Implemented (Yet...)
+
+- [ ] JOINs (Redis doesn't support cross-index joins)
+- [ ] Subqueries
+- [ ] HAVING clause
+- [ ] DISTINCT
+- [ ] GEO field queries
+- [ ] Index creation from SQL (CREATE INDEX)
+
+## Development
+
+```bash
+# Install dependencies
+uv sync --all-extras
+
+# Run tests (requires Docker for testcontainers)
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=sql_redis --cov-report=html
+```
+
+## Testing Philosophy
+
+This project uses strict TDD with 100% test coverage as a hard requirement. The approach:
+
+1. **Write failing tests first** — Define expected behavior before implementation
+2. **One test at a time** — Implement just enough to pass each test
+3. **No untestable code** — If we can't test it, we don't write it
+4. **Integration tests mirror raw Redis** — `test_sql_queries.py` verifies SQL produces same results as equivalent `FT.AGGREGATE` commands in `test_redis_queries.py`
+
+Coverage is enforced in CI. Pragmas (`# pragma: no cover`) are forbidden — if code can't be tested, it shouldn't exist.
+