ClickHouse/clickhouse-connect v0.13.0

on GitHub

What's Changed

Improvements

• BREAKING CHANGE: Implement native write path for Variant data type with type-aware dispatching. Previously, all values inserted into a Variant column were stringified and sent to the server, which would store them in the String member if present, or attempt server-side conversion otherwise. Values are now serialized using their native ClickHouse types client-side (e.g. inserting 100 into Variant(Int64, String) stores Int64(100) instead of String("100")).

  Key changes:

  • Values that don't match any variant member now raise DataError instead of being stringified and
    delegated to the server.
  • A typed_variant(value, 'TypeName') helper is provided for cases where automatic dispatch
    cannot resolve the target type, such as when multiple variant members map to the same Python
    type (e.g. Array(UInt32) vs Array(String)).

• Added utc_tz_aware="schema" mode which returns timezone-aware datetimes only when the server's column schema explicitly defines a timezone (e.g. DateTime('UTC')), and naive datetimes for bare DateTime columns. This matches the ClickHouse schema definition exactly. Not yet supported for Arrow-based query methods. Closes #645

• Add type annotations to public API methods in Client, AsyncClient, HttpClient, and QueryResult. Ref #567

Bug Fixes

• Fix dict_add parameter typed as builtin any instead of typing.Any.
• Recognize UPDATE as a command so lightweight updates work correctly via client.query() and SQLAlchemy.
• SQLAlchemy: GROUP BY now renders label aliases instead of full expressions which avoids circular reference errors when an alias shadows a source column name in ClickHouse.

Full Changelog: v0.11.0...v0.13.0