(improvement) serializers: add Cython-optimized serialization for VectorType (up to 30x faster - 823us -> 4us!) by mykaul · Pull Request #748 · scylladb/python-driver

mykaul · 2026-03-14T11:08:22Z

Summary

Adds cassandra/serializers.pyx and cassandra/serializers.pxd implementing Cython-optimized serialization that mirrors the deserializers.pyx architecture.

What's included

Scalar serializers: SerFloatType (4-byte IEEE 754), SerDoubleType (8-byte), SerInt32Type (4-byte signed) -- the three subtypes commonly used in vector columns
SerVectorType: Pre-allocates a contiguous buffer via PyBytes_FromStringAndSize(NULL, ...) and uses C-level byte swapping for float/double/int32 vectors, with a generic fallback for other subtypes
Buffer fast-path for NumPy arrays: When the input is a NumPy array with a matching dtype, Cython typed memoryviews (float[::1], double[::1], int[::1]) read directly from the buffer protocol -- bypassing Python object creation entirely
GenericSerializer: Delegates to the Python-level cqltype.serialize() classmethod for all other types
Factory functions: find_serializer(cqltype) and make_serializers(cqltypes_list) for easy lookup and batch creation

Architecture

Mirrors deserializers.pyx exactly:

Deserializer side	Serializer side
`Deserializer` base class	`Serializer` base class
`DesFloatType`, `DesDoubleType`, `DesInt32Type`	`SerFloatType`, `SerDoubleType`, `SerInt32Type`
`DesVectorType` (type-specialized)	`SerVectorType` (type-specialized)
`GenericDeserializer`	`GenericSerializer`
`find_deserializer()`	`find_serializer()`
`make_deserializers()`	`make_serializers()`

Benchmark

Measured with min() of timeit.repeat(repeat=7, number=50_000) on a quiet machine (load <2.5). Vector<float, N> serialization, comparing Python baseline (VectorType.serialize via io.BytesIO) vs Cython SerVectorType.

List/tuple inputs

Dimension	Python baseline (ns/call)	Cython (ns/call)	Speedup
`float[128]`	9926	1168	8.5x
`float[1536]`	110569	8097	13.7x

NumPy float32 array inputs (buffer fast-path)

Dimension	Cython list (ns/call)	Cython NumPy (ns/call)	Speedup vs list
`float[128]`	1168	507	2.3x
`float[1536]`	8097	1365	5.9x

End-to-end: NumPy vs Python baseline

Dimension	Python baseline (ns/call)	Cython+NumPy (ns/call)	Speedup
`float[128]`	9926	507	19.6x
`float[1536]`	110569	1365	81.0x

Tests

Comprehensive Cython serializer unit tests in tests/unit/cython/test_serializers.py
Full unit test suite passes (740 passed, 43 skipped)

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

Copilot

Pull request overview

This PR introduces a new Cython extension module to accelerate CQL value serialization—especially VectorType—using the same general “typed Serializer object + factory lookup” approach as the existing Cython deserialization stack.

Changes:

Add cassandra/serializers.pyx implementing Cython serializers for FloatType, DoubleType, Int32Type, and an optimized VectorType serializer with generic fallback.
Add find_serializer() / make_serializers() factory helpers for serializer creation.
Add cassandra/serializers.pxd to expose the Serializer interface to other Cython modules.

Reviewed changes

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

File	Description
cassandra/serializers.pyx	New Cython-optimized serialization implementations and factory lookup.
cassandra/serializers.pxd	Cython declarations for the `Serializer` interface.

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

cassandra/serializers.pyx

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

…lizers Address all 8 Copilot review comments on PR scylladb#748: - Add _check_float_range() for float overflow detection matching struct.pack - Add _check_int32_range() for int32 bounds checking before C cast - Wire bounds checks into SerFloatType, SerInt32Type, and VectorType fast-paths - Replace malloc/free with PyBytes_FromStringAndSize(NULL,n)+PyBytes_AS_STRING - Add empty vector early return (b'') before allocation - Remove unused uint32_t cimport and libc.stdlib import - Add comprehensive test suite (67 tests) covering equivalence, overflow, special values, vectors, round-trips, and factory functions

Copilot

Pull request overview

Adds a new Cython serialization module to speed up VectorType (and a few common scalar subtypes) while keeping wire-format output identical to existing cqltypes.*.serialize() implementations.

Changes:

Introduce cassandra/serializers.pyx + .pxd implementing Serializer classes, including a specialized SerVectorType with float/double/int32 fast-paths.
Add serializer lookup/batch factories (find_serializer, make_serializers).
Add unit tests validating byte-for-byte equivalence and basic round-trips for the new serializers.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 7 comments.

File	Description
`cassandra/serializers.pyx`	New Cython serializers, including optimized `VectorType` serialization and factory lookup functions.
`cassandra/serializers.pxd`	Cython declarations for the `Serializer` base class.
`tests/unit/test_serializers.py`	New unit tests covering scalar/vector equivalence, round-trips, and factory behavior.

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

tests/unit/test_serializers.py

cassandra/serializers.pyx

tests/unit/test_serializers.py

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

Copilot

Pull request overview

Adds a new Cython extension module (cassandra.serializers) that provides optimized serialization implementations for common scalar types and VectorType, intended to mirror the existing deserializers.pyx architecture and improve vector-heavy workloads.

Changes:

Introduces cassandra/serializers.pyx + .pxd implementing Serializer classes, SerVectorType, and factory helpers (find_serializer, make_serializers).
Adds unit tests validating byte-for-byte equivalence vs. Python cqltype.serialize() and basic factory behavior.
Implements float/double/int32 vector fast-paths via preallocated contiguous buffers and endian swapping.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
`cassandra/serializers.pyx`	New Cython-optimized serializers, including `VectorType` specialized paths and serializer lookup/factory functions.
`cassandra/serializers.pxd`	Cython declarations for the `Serializer` base class API.
`tests/unit/test_serializers.py`	New tests for serializer equivalence, edge cases, and factory helpers under Cython.

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

cassandra/serializers.pyx

tests/unit/test_serializers.py

cassandra/serializers.pyx

…lizers Address all 8 Copilot review comments on PR scylladb#748: - Add _check_float_range() for float overflow detection matching struct.pack - Add _check_int32_range() for int32 bounds checking before C cast - Wire bounds checks into SerFloatType, SerInt32Type, and VectorType fast-paths - Replace malloc/free with PyBytes_FromStringAndSize(NULL,n)+PyBytes_AS_STRING - Add empty vector early return (b'') before allocation - Remove unused uint32_t cimport and libc.stdlib import - Add comprehensive test suite (67 tests) covering equivalence, overflow, special values, vectors, round-trips, and factory functions

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.

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

cassandra/serializers.pyx

tests/unit/test_serializers.py

cassandra/serializers.pyx

mykaul · 2026-03-26T14:52:38Z

CI flakiness above - fix sent - #767

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

Restore serializers.pyx/pxd from the PR scylladb#748 branch and add SerDateType that serializes datetime/date/numeric values to 8-byte big-endian int64 millisecond timestamps entirely in C, avoiding Python-level struct.pack. Uses the same timedelta arithmetic as the pure-Python DateType.serialize (Item B) but with C-level int64 byte-swapping. Benchmark shows ~1.5x speedup over the already-optimized Python path for datetime serialization (253 ns vs 381 ns per call).

…lizers Address all 8 Copilot review comments on PR scylladb#748: - Add _check_float_range() for float overflow detection matching struct.pack - Add _check_int32_range() for int32 bounds checking before C cast - Wire bounds checks into SerFloatType, SerInt32Type, and VectorType fast-paths - Replace malloc/free with PyBytes_FromStringAndSize(NULL,n)+PyBytes_AS_STRING - Add empty vector early return (b'') before allocation - Remove unused uint32_t cimport and libc.stdlib import - Add comprehensive test suite (67 tests) covering equivalence, overflow, special values, vectors, round-trips, and factory functions

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

…torType Add cassandra/serializers.pyx and cassandra/serializers.pxd implementing Cython-optimized serialization that mirrors the deserializers.pyx architecture. Implements type-specialized serializers for the three subtypes commonly used in vector columns: - SerFloatType: 4-byte big-endian IEEE 754 float - SerDoubleType: 8-byte big-endian double - SerInt32Type: 4-byte big-endian signed int32 SerVectorType pre-allocates a contiguous buffer and uses C-level byte swapping for float/double/int32 vectors, with a generic fallback for other subtypes. GenericSerializer delegates to the Python-level cqltype.serialize() classmethod. Factory functions find_serializer() and make_serializers() allow easy lookup and batch creation of serializers for column types. Benchmarks show ~30x speedup over the current io.BytesIO baseline and ~3x speedup over Python struct.pack for Vector<float, 1536> serialization. No setup.py changes needed - the existing cassandra/*.pyx glob already picks up new .pyx files.

…nt.bind() When Cython serializers (from cassandra.serializers) are available and no column encryption policy is active, BoundStatement.bind() now uses pre-built Serializer objects cached on the PreparedStatement instead of calling cqltype classmethods. This avoids per-value Python method dispatch overhead and enables the ~30x vector serialization speedup from the Cython serializers module. The bind loop is split into three paths: 1. Column encryption policy path (unchanged behavior) 2. Cython serializers path (new fast path) 3. Plain Python path (no CE, no Cython -- removes per-value ColDesc/CE check) Depends on PR scylladb#748 (Cython serializers module) and PR scylladb#630 (CE-policy bind split).

Restore serializers.pyx/pxd from the PR scylladb#748 branch and add SerDateType that serializes datetime/date/numeric values to 8-byte big-endian int64 millisecond timestamps entirely in C, avoiding Python-level struct.pack. Uses the same timedelta arithmetic as the pure-Python DateType.serialize (Item B) but with C-level int64 byte-swapping. Benchmark shows ~1.5x speedup over the already-optimized Python path for datetime serialization (253 ns vs 381 ns per call).

mykaul mentioned this pull request Mar 14, 2026

(improvement) query: add Cython-aware serializer path in BoundStatement.bind() (1-26x speedup - tens/hundreds of us reduced) #749

Draft

mykaul marked this pull request as draft March 14, 2026 11:23

mykaul requested a review from Copilot March 14, 2026 19:25

Copilot started reviewing on behalf of mykaul March 14, 2026 19:25 View session

Copilot AI reviewed Mar 14, 2026

View reviewed changes

mykaul requested a review from Copilot March 19, 2026 14:19

Copilot AI reviewed Mar 19, 2026

View reviewed changes

mykaul requested a review from Copilot March 24, 2026 22:14

Copilot started reviewing on behalf of mykaul March 24, 2026 22:14 View session

Copilot AI reviewed Mar 24, 2026

View reviewed changes

mykaul force-pushed the perf/cython-serializers branch 2 times, most recently from 91fe2ed to 91cd1ef Compare March 25, 2026 21:43

mykaul requested a review from Copilot March 26, 2026 08:53

Copilot started reviewing on behalf of mykaul March 26, 2026 08:54 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

mykaul mentioned this pull request Mar 26, 2026

(fix) tests: fix flaky TestTwistedConnection.test_connection_initialization #767

Merged

mykaul mentioned this pull request Apr 5, 2026

perf: optimize time-series write/read hot paths (10's to 100's of ns savings, 2-25x better) #798

Draft

mykaul changed the title ~~(improvement) serializers: add Cython-optimized serialization for VectorType~~ (improvement) serializers: add Cython-optimized serialization for VectorType (up to 30x faster - 823us -> 4us!) Apr 7, 2026

mykaul force-pushed the perf/cython-serializers branch from c77c7b4 to 97cdad0 Compare April 7, 2026 08:13

perf: add buffer fast-path for vector serializers

de14827

mykaul force-pushed the perf/cython-serializers branch from 97cdad0 to de14827 Compare April 7, 2026 09:20

Conversation

mykaul commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What's included

Architecture

Benchmark

List/tuple inputs

NumPy float32 array inputs (buffer fast-path)

End-to-end: NumPy vs Python baseline

Tests

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mykaul commented Mar 26, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mykaul commented Mar 14, 2026 •

edited

Loading