Add support for QBit data type

[joe-clickhouse]

Summary

Adds full read/write support for the (currently) experimental QBit data type.

QBit is a transformation type that stores vectors of Floats as bit-transposed Tuples of FixedStrings to optimize storage and search on the server. This implementation handles the matrix transposition logic on the client side, allowing users to interact with standard lists of floats while the driver handles the wire-format bit packing.

Key implementation details

Transformation architecture

• Implemented QBit not as a standalone storage container, but as a transformation layer.
• The write path transposes input vectors (list of floats) into vertical bit planes, packs them into FixedString buffers, and delegates the actual wire serialization to the existing Tuple and FixedString serializers.
• The read path reads the raw Tuple(FixedString) from the wire and untransposes the bit planes back into standard python lists of floats.

Type support

• Supports all valid QBit element types: Float32, Float64, and BFloat16
• BFloat16 is handled via bit-manipulation (truncating/shifting Float32s) since python lacks a native type.

Performance

This transformation is pretty CPU intensive for interpreted languages like python, so if you're using the QBit type, it is HIGHLY recommended to have NumPy installed in your environment. Because:

• NumPy fast path: There is a vectorized implementation using numpy (if available) to handle the bit-transposition. This results in an order of magnitude speedup for the transpose/untranspose operations compared to the pure python implementation.
• The fast path will be automatically taken if you simply have numpy installed

Pure python fallback

If you can't install numpy in your env there is still a robust fallback, but it's not going to be fast.

Verification

• Added round-trip tests for all three element types and validated against clickhouse-server 25.10+.

References

• The server's QBit serialization code is a huge help
• The server docs for QBit type
• Server docs about nn search with the QBit type

Checklist

Delete items not relevant to your PR:

• Unit and integration tests covering the common scenarios were added
• A human-readable description of the changes was provided to include in CHANGELOG
• For significant changes, documentation in https://github.com/ClickHouse/clickhouse-docs was updated with further explanations or tutorials

Closes #570

[Copilot]

Pull Request Overview

This PR adds comprehensive support for the experimental QBit data type, which stores float vectors as bit-transposed tuples for optimized vector search operations. The implementation handles the client-side matrix transposition logic, allowing users to work with standard Python lists of floats while the driver manages the wire-format bit packing.

Key Changes:

• Implemented QBit transformation layer supporting Float32, Float64, and BFloat16 element types
• Added NumPy-accelerated fast path for transpose operations (20-50x speedup)
• Included pure Python fallback for environments without NumPy
• Added SQLAlchemy integration for QBit type

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
clickhouse_connect/datatypes/vector.py	Core QBit implementation with bit transposition logic and NumPy optimization
clickhouse_connect/cc_sqlalchemy/datatypes/sqltypes.py	SQLAlchemy QBit type wrapper
clickhouse_connect/datatypes/init.py	Module registration for vector types
tests/unit_tests/test_qbit_type.py	Comprehensive unit tests for QBit transposition and edge cases
tests/integration_tests/test_vector.py	Integration tests for QBit round-trip operations and database interactions
tests/unit_tests/test_sqlalchemy/test_types.py	SQLAlchemy QBit type tests
tests/integration_tests/test_sqlalchemy/test_ddl.py	SQLAlchemy DDL integration test
CHANGELOG.md	Release notes entry

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.