[slorello89]

Motivation

Filtered vector queries on Search on Flex require an explicit execution policy. Expose this through SQLQuery(hybrid_policy="ADHOC_BF") or SQLQuery(hybrid_policy="BATCHES").

Changes

• Forward the option to sql-redis for command translation and synchronous/asynchronous execution.
• Preserve policy-specific executor caching and existing behavior when the option is omitted.
• Document policy mapping and precedence, and test forwarding, cache separation, and caller-option preservation.

Dependency: Keep this PR in draft until the companion sql-redis policy support is released. sql-redis 0.7.1 does not accept the option. Before merging, update both SQL dependency minimums and the lockfile to the supporting release and validate against it. Current end-to-end validation uses the local companion patch.

Release Notes

Add SQLQuery.hybrid_policy for filtered vector queries. With a supporting sql-redis version, it selects FT.SEARCH HYBRID_POLICY or FT.HYBRID FILTER ... POLICY; ADHOC_BF maps to ADHOC for FT.HYBRID.

Review record

Reviewed at 9edb472 by Codex (GPT-6) with pre-pr-review.
Lenses: correctness (option forwarding), security (query options), design (public API), tests (new coverage), docs (API behavior), Redis behavior (policy syntax). None skipped.

• 1 finding raised and retained after independent challenge: the companion dependency must ship before this feature can be merged. Open; no released minimum version is assumed.
• No other findings; no findings rejected.

Verified: 44 focused unit tests; 153 SQL integration tests passed with 2 expected failures; 8 real Redis policy checks covering both commands, both policies, and sync/async execution with the companion patch; type checks passed for 120 source files; formatting and changed-file pre-commit hooks passed.

Full-tree pre-commit found an existing spelling issue in redisvl/redis/connection.py; its unrelated automatic correction was reverted. The SQL integration run also logged async cleanup Event loop is closed errors despite passing tests.

Docs consulted: https://redis.io/docs/latest/develop/ai/search-and-query/vectors/ and https://redis.io/docs/latest/commands/ft.hybrid/.

Not checked: full repository test suite, docs build, cluster mode, external providers, or an eventual released sql-redis version containing policy support.