Redis OM Python is an object-mapping library that provides high-level abstractions to easily model, validate, and query data in Redis with modern Python applications. It leverages Pydantic for robust data validation and supports both Redis Hashes (`HashModel`) and JSON documents (`JsonModel`) for data storage, including automatic index generation and a fluent query API. Currently at version 1.1.0, the library maintains an active development pace with frequent updates and major version releases every few months.
pip install redis-omVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates defining a `HashModel`, connecting to Redis via an environment variable, running schema migrations, creating and saving model instances, and retrieving them by primary key and through a basic query. It assumes a Redis Stack instance is running locally (e.g., via Docker).
Upgrade Python to 3.10+ and Pydantic to v2. Migrate Pydantic v1 code to v2 syntax (e.g., `@validator` to `@field_validator`, `Config` class to `model_config = ConfigDict(...)`). If migrating from 0.x, refer to the Redis OM Python 0.x to 1.0 Migration Guide for detailed steps, including schema and data migration commands (`om migrate`, `om migrate-data run`).
Adjust application logic to explicitly handle UTC-aware datetimes. If naive datetimes are still desired, convert the UTC-aware datetimes back to naive local time within your application after retrieval (e.g., `dt_obj.astimezone(None)`).
Avoid using version 1.0.5. If using a specific version, ensure it's 1.0.6 or newer for stable synchronous and asynchronous support. Pip will typically install 1.0.6 if 1.0.5 is yanked, but explicit pinning should be checked.
For models requiring nested data structures or embedded models, use `JsonModel` instead of `HashModel`. `JsonModel` serializes the data as JSON, allowing for complex nested objects.
Ensure Redis is running (e.g., `docker run -d -p 6379:6379 redis/redis-stack`). Verify no firewall is blocking port 6379. Confirm the `REDIS_OM_URL` environment variable (or connection string) is correctly set to your Redis instance's address and port.
Ensure all model fields have explicit and correct Python type annotations (e.g., `name: str`, `age: int`). If using custom types, ensure they are properly recognized by Pydantic.
Modify your model definition to explicitly mark the field for full-text search: `field_name: str = Field(index=True, full_text_search=True)`. After updating the model, run `Migrator().run()` to update the RediSearch index.
Ensure you are using `redis-om` version 1.0.0 or newer. If you are, and still encountering issues, check that all other dependencies requiring Pydantic are compatible with v2. If you absolutely must use a Pydantic v1-based library alongside v2, refer to Pydantic's v1 compatibility layer (`pydantic.v1.BaseModel`). However, the recommended fix for `redis-om` is to ensure it's updated to a Pydantic v2 compatible version.