search_query.upgrade

Utilities for upgrading search queries between versions.

Functions

upgrade_query(query_str, platform, ...[, ...])

Upgrade a database-specific search query from one syntax version to another using the generic query as a platform-agnostic intermediate representation (IR).
search_query.upgrade.upgrade_query(query_str: str, platform: str, version_current: str, version_target: str | None = None) → str

Upgrade a database-specific search query from one syntax version to another using the generic query as a platform-agnostic intermediate representation (IR).

Design intent: - Parse specific query → generic query (IR) → specific query → serialize.

By pivoting through a generic IR we avoid O(N^2) pairwise converters, improving maintainability and testability.

  • Each platform/version only needs: PARSER, TRANSLATOR (to/from IR), SERIALIZER. Adding a new version/platform becomes linear work (plug-in modules).

  • Unsupported features can be flagged with warnings instead of failing silently.

  • Using the same to_generic_syntax() / to_specific_syntax() for upgrades and cross-platform translations ensures consistency and reduces effort.

  • A round-trip parse after serialization confirms syntactic validity.

Notes: - The IR should be the most expressive model across supported syntaxes.

Where unavoidable, translators should emit warnings about lossy conversions.