search_query.upgrade

Utilities for upgrading search queries between versions.

Functions

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

Upgrade a database-specific search query between syntax versions.
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 between syntax versions.

The upgrade uses 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 a parser, a translator (to/from the IR), and a 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() and to_specific_syntax() methods 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.

Parameters:

  • query_str – Database-specific search query to upgrade.

  • platform – Platform whose syntax the query uses.

  • version_current – Current syntax version of the query.

  • version_target – Target syntax version, or None/"latest" for the latest supported version.

Returns:

The query serialized using the target syntax version.