fix: make strict datetime filter comparison opt-in

[sjrl]

Related Issues

• Related to fix: reconcile tz-aware and naive datetimes in ordering filters #11943 and fix: normalize ISO date equality filters #11963
• Fixes Ordering and equality filters disagree on naive vs tz-aware datetimes #12246

Proposed Changes:

Of the options listed in #12246, I opted for “equality could start reconciling,” aligning equality with the existing ordering behavior. Reconciliation can be disabled by setting the new keyword-only parameter strict_datetime_comparison=True. In strict mode, mixed timezone-aware and timezone-naive values are treated as non-matching rather than raising an error.

Added an opt-in strict_datetime_comparison keyword argument to document_matches_filter, InMemoryDocumentStore, and MetadataRouter. When enabled, timezone-naive and timezone-aware datetimes never match each other. By default, mixed-awareness datetimes continue to be reconciled by copying the timezone from the aware value to the naive one, and this behavior is now consistent across equality, membership, and ordering operators.

How did you test it?

New and existing tests

Notes for the reviewer

Checklist

• I have read the contributors guidelines and the code of conduct.
• I have updated the related issue with new insights and changes.
• I have added unit tests and updated the docstrings.
• I've used one of the conventional commit types for my PR title: fix:, feat:, build:, chore:, ci:, docs:, style:, refactor:, perf:, test: and added ! in case the PR includes breaking changes.
• I have documented my code.
• I have added a release note file, following the contributors guidelines.
• I have run pre-commit hooks and fixed any issue.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
haystack-docs	Ignored	Preview	Aug 7, 2026 6:03am

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
haystack/components/routers
metadata_router.py
haystack/document_stores/in_memory
document_store.py					616
haystack/utils
filters.py
Project Total

This report was generated by python-coverage-comment-action

[sjrl]

@julian-risch I've requested your review since you reviewed the most recent PR that introduced the discrepancy between equality and ordering for datetime comparisons so I believe you have the most context!

[julian-risch]

Thanks a lot! Much better! Two things:

• We should delete releasenotes/notes/fix-equality-iso-date-filter-4b7c9d2e1f6a8b03.yaml (the one from #11963 ). Technically not blocking this PR so I can also do that in a separate PR.
• There is an issue with indentation of :param strict_datetime_comparison:. pre-existing issue for :param output_type: too. See the rendering: https://docs.haystack.deepset.ai/reference/next/routers-api#metadatarouter

[sjrl]

@julian-risch both comments addressed in e5d6e0a