Redis OM Python

Redis OM Python is an object-mapping library that lets you model Redis data as declarative Python classes backed by Pydantic. You define fields, types, and indexes on a model, and the library handles serialization, validation, persistence, and secondary-index generation against Redis and the RediSearch/RedisJSON modules.

On top of storage it provides a fluent, expressive query API so you can filter, sort, and paginate indexed models without writing raw Redis commands. Both synchronous and asyncio interfaces are generated from a single codebase, making it a natural fit for FastAPI, Flask, and other modern Python applications.

What You Get

• Declarative HashModel and JsonModel base classes for mapping Python objects to Redis
• Automatic secondary-index generation so fields become queryable without manual index management
• A fluent, chainable query API for filtering, sorting, and paginating indexed data
• Pydantic-powered validation and serialization built into every model
• Parallel synchronous and asyncio APIs generated from one source tree

Common Use Cases

• Persisting and querying application entities in Redis without hand-writing commands
• Building fast, index-backed lookups over Redis-Stack data from FastAPI or Flask services
• Using Redis as a primary data store with validated, schema-defined models
• Modeling embedded and nested documents with JsonModel and RedisJSON

Under The Hood

Architecture - The core lives in aredis_om/model/model.py, a ~3,900-line module defining the RedisModel, HashModel, and JsonModel metaclass machinery that turns Pydantic field definitions into Redis key layouts and RediSearch index schemas. Query construction flows through query_resolver.py and an Expression tree that renders to RediSearch query strings, with token_escaper.py and render_tree.py handling escaping and debug output. A codegen step (make_sync.py) transforms the async aredis_om package into the synchronous redis_om package so both APIs stay in lockstep.

Tech Stack - Pure Python (>=3.10), built on redis (>=4.2), pydantic v2 for modeling and validation, python-ulid for identifiers, redisvl for vector/search integration, and hiredis for fast protocol parsing. Packaging uses a modern pyproject.toml with uv for lockfiles.

Code Quality - The repository has an extensive test suite under tests/ covering hash models, JSON models, query resolution, datetime handling, KNN expressions, schema migration, and regression bug fixes, run against a live Redis Stack via docker-compose. Tooling includes mypy, ruff, and bandit, and the package ships py.typed for downstream type checking.

API Design - The developer experience is ergonomic: models are declared like ordinary Pydantic classes, .save()/.get()/Model.find() read naturally, and the fluent expression syntax keeps queries close to Python. The main learning curve is understanding which fields to index and provisioning a Redis instance with the RediSearch and RedisJSON modules.