From d57f36f13b1bae28862b183ba1fabbc2ecaec2e2 Mon Sep 17 00:00:00 2001 From: Andrew Brookins Date: Fri, 13 Mar 2026 11:58:33 -0700 Subject: [PATCH 1/2] Document 1.1 timestamp normalization --- docs/migrations.md | 28 ++++++++++++++++++++++++++++ docs/release_notes_1.1.md | 19 +++++++++++++++++++ mkdocs.yml | 2 +- 3 files changed, 48 insertions(+), 1 deletion(-) create mode 100644 docs/release_notes_1.1.md diff --git a/docs/migrations.md b/docs/migrations.md index 5a39e065..aac71f2b 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -217,6 +217,34 @@ Redis OM includes a built-in migration for datetime field indexing improvements. For detailed information about this migration, see the **[0.x to 1.0 Migration Guide](migration_guide_0x_to_1x.md#datetime-migration-details)**. +### Datetime Timezone Normalization in 1.1.0 + +Redis OM Python 1.1.0 tightens timestamp handling for both `datetime.datetime` and `datetime.date` fields: + +- `datetime.datetime` values are read back as **UTC-aware** datetimes. +- `datetime.date` values are stored as **midnight UTC** instead of local-midnight timestamps. + +This is usually what you want, but it matters if you already have data written by versions before 1.1.0: + +- Older `datetime.datetime` records still represent the same instant in time, but code that expected naive datetimes may need to handle UTC-aware values. +- Older `datetime.date` records written in a **non-UTC** environment may load as a different calendar day after upgrading, and equality queries may stop matching those records. + +If you have existing `datetime.date` data from a pre-1.1.0 release and your application was not running in UTC, plan to migrate or re-save that data after upgrading. + +Example symptom after upgrade: + +- Stored before 1.1.0 in `Asia/Karachi`: `date(2023, 1, 1)` -> `1672513200` (local midnight) +- Stored in 1.1.0+: `date(2023, 1, 1)` -> `1672531200` (midnight UTC) + +If your application relies on date equality queries, verify old records after upgrading: + +```bash +# Spot-check records after upgrading +om migrate-data status +``` + +If needed, create a custom data migration to normalize affected `datetime.date` fields by re-saving them with Redis OM 1.1.0+. + ## Advanced Usage ### Module-Based Migrations diff --git a/docs/release_notes_1.1.md b/docs/release_notes_1.1.md new file mode 100644 index 00000000..b6bc3c88 --- /dev/null +++ b/docs/release_notes_1.1.md @@ -0,0 +1,19 @@ +# Redis OM Python 1.1 Release Notes + +Redis OM Python 1.1 focuses on compatibility updates and timestamp normalization fixes. + +## Notable Changes + +- RedisVL dependency updated to allow newer Python versions +- `datetime.datetime` values now round-trip as UTC-aware datetimes +- `datetime.date` values now store as midnight UTC instead of local-midnight timestamps + +## Timestamp Upgrade Note + +The timestamp normalization change is important if you already have data written by earlier releases: + +- Existing `datetime.datetime` records still represent the same instant in time, but code that expected naive datetimes may need to handle UTC-aware values. +- Existing `datetime.date` records written in a non-UTC environment may load as a different calendar day after upgrading. +- Date equality queries may stop matching those older records until the data is re-saved or migrated. + +For migration guidance, see [Migrations: Datetime Timezone Normalization in 1.1.0](migrations.md#datetime-timezone-normalization-in-110). diff --git a/mkdocs.yml b/mkdocs.yml index 8ce85fa2..1a2f355b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -72,6 +72,7 @@ nav: - Reference: - Errors: errors.md - Release Notes 1.0: release_notes_1.0.md + - Release Notes 1.1: release_notes_1.1.md - Upgrade Guide (0.x → 1.x): migration_guide_0x_to_1x.md plugins: @@ -105,4 +106,3 @@ extra_css: copyright: | © 2024 Redis - From 6ce865f0fb5765317f8c4e083d72d876d30f3dd1 Mon Sep 17 00:00:00 2001 From: Andrew Brookins Date: Fri, 13 Mar 2026 12:07:09 -0700 Subject: [PATCH 2/2] Fix spelling in 1.1 docs --- docs/migrations.md | 6 +++--- docs/release_notes_1.1.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/migrations.md b/docs/migrations.md index aac71f2b..db1b5217 100644 --- a/docs/migrations.md +++ b/docs/migrations.md @@ -221,15 +221,15 @@ For detailed information about this migration, see the **[0.x to 1.0 Migration G Redis OM Python 1.1.0 tightens timestamp handling for both `datetime.datetime` and `datetime.date` fields: -- `datetime.datetime` values are read back as **UTC-aware** datetimes. +- `datetime.datetime` values are read back as **UTC-aware** `datetime` values. - `datetime.date` values are stored as **midnight UTC** instead of local-midnight timestamps. This is usually what you want, but it matters if you already have data written by versions before 1.1.0: -- Older `datetime.datetime` records still represent the same instant in time, but code that expected naive datetimes may need to handle UTC-aware values. +- Older `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values. - Older `datetime.date` records written in a **non-UTC** environment may load as a different calendar day after upgrading, and equality queries may stop matching those records. -If you have existing `datetime.date` data from a pre-1.1.0 release and your application was not running in UTC, plan to migrate or re-save that data after upgrading. +If you have existing `datetime.date` data from a release before 1.1.0 and your application was not running in UTC, plan to migrate or re-save that data after upgrading. Example symptom after upgrade: diff --git a/docs/release_notes_1.1.md b/docs/release_notes_1.1.md index b6bc3c88..11f17c04 100644 --- a/docs/release_notes_1.1.md +++ b/docs/release_notes_1.1.md @@ -5,14 +5,14 @@ Redis OM Python 1.1 focuses on compatibility updates and timestamp normalization ## Notable Changes - RedisVL dependency updated to allow newer Python versions -- `datetime.datetime` values now round-trip as UTC-aware datetimes +- `datetime.datetime` values now round-trip as UTC-aware `datetime` values - `datetime.date` values now store as midnight UTC instead of local-midnight timestamps ## Timestamp Upgrade Note The timestamp normalization change is important if you already have data written by earlier releases: -- Existing `datetime.datetime` records still represent the same instant in time, but code that expected naive datetimes may need to handle UTC-aware values. +- Existing `datetime.datetime` records still represent the same instant in time, but code that expected naive `datetime` values may need to handle UTC-aware values. - Existing `datetime.date` records written in a non-UTC environment may load as a different calendar day after upgrading. - Date equality queries may stop matching those older records until the data is re-saved or migrated.