Add `AVX-512VL` to dynamic dispatch and optimise `QBit` [un]transposition by rienath · Pull Request #88445 · ClickHouse/ClickHouse

rienath · 2025-10-13T11:02:04Z

Not for changelog because QBit hasn't been released yet. New things in this PR:

Optimised logic around bit transposition. Previously, it would accept a vector of floats and produce a vector of bytes. This meant we had to first read the floats into the vector, then run transposition, write results to a separate vector so that we can later write them to FixedStrings. Now, we can read a single float, transpose it, and write directly into the affected FixedStrings, reducing intermediate memory allocations and increasing ingestion speed.
Added VL instruction set as an option for AVX-512 dispatch. Previously, it was only available with VBMI instructions, but there are machines that have VL without VBMI. This change was needed for ↓.
Added vectorised algorithms for QBit untransposition, speeding up distance calculations on it. To make this possible, simplified serialisation and removed MSB -> LSB -> MSB trickery we used before.
More detailed documentation for QBit serialisation and gtest_qbit_serialization.cpp test fix.
Binary [de]serialisation of QBit [de]serialised trailing padding zeroes that QBit had. This was not necessary, as we read/write vector. Thus, zeroes were removed.

Changelog category (leave one):

Not for changelog (changelog entry is not required)

clickhouse-gh · 2025-10-13T11:02:33Z

Workflow [PR], commit [47c15c5]

Summary: ❌

job_name	test_name	status	info
Integration tests (amd_binary, 5/5)		failure
	test_storage_nats/test_nats_jet_stream.py::test_nats_overloaded_insert	FAIL	cidb
Stress test (arm_asan, s3)		failure
	Server died	FAIL	cidb
	Hung check failed, possible deadlock found (see hung_check.log)	FAIL	cidb
	Killed by signal (in clickhouse-server.log)	FAIL	cidb
	Fatal message in clickhouse-server.log (see fatal_messages.txt)	FAIL	cidb
	Killed by signal (output files)	FAIL	cidb

rienath · 2025-10-13T14:16:09Z

Internal representation of values was reversed to simplify serialization, that is why these changed

rienath · 2025-10-13T14:17:19Z

-SELECT vec.7 FROM qbit ORDER BY id;
-SELECT vec.15 FROM qbit ORDER BY id;
-SELECT vec.23 FROM qbit ORDER BY id;
-SELECT vec.31 FROM qbit ORDER BY id;
+SELECT bin(vec.7) FROM qbit ORDER BY id;
+SELECT bin(vec.15) FROM qbit ORDER BY id;
+SELECT bin(vec.23) FROM qbit ORDER BY id;
+SELECT bin(vec.31) FROM qbit ORDER BY id;


Makes sense to look at underlying binary values, because displaying bytes as characters doesn't tell us what went wrong

Avogar · 2025-10-14T18:05:20Z

+    if (size > DEFAULT_MAX_STRING_SIZE)
+        throw Exception(ErrorCodes::TOO_LARGE_ARRAY_SIZE, "Too large QBit dimension (maximum: {})", DEFAULT_MAX_STRING_SIZE);


We have a setting max_binary_array_size in FormatSettings for binary formats. Let's use it instead of DEFAULT_MAX_STRING_SIZE.

Avogar · 2025-10-14T18:11:13Z

+    /// If the dimension % 8 != 0, the buffer will contain padding floats. Thus, `size` can be larger, equal, but never smaller than dimension
+    if (size < dimension)
+        throw Exception(
+            ErrorCodes::SERIALIZATION_ERROR, "Size of the read QBit {} doesn't match expected size {}", size, (dimension / 8) * 8);
+
+    return size;


Wait, does it mean that in RowBinary format we output padding floats? If yes, we need to fix this, we should output array with dimension floats. Otherwise user will get unexpected 0-s in their vectors during deserialization

Isn't client aware of the dimension? It is one of the members of SerializationQBit. If not, it might also be a good idea to remove

if (size != dimension) throw Exception( ErrorCodes::SERIALIZATION_ERROR, "Dimension of the read QBit {} doesn't match expected dimension {}", size, dimension);

in validateAndReadQBitSize too

I removed trailing zeroes

Avogar · 2025-10-14T18:23:57Z

+    }

-    const char * value_bytes = reinterpret_cast<const char *>(value_floats.data());
+    /// We do not need to worry about skipping padding floats at the tail here like we do in deserializeFloatsToQBitTuple(...) .


We just should not have padding floats at all in any format

…ion size

rienath

@Avogar thanks for the review, I have addressed the highlighted problems. PTAL when you have time

Avogar

Just 2 small comments, everything else looks good

Avogar · 2025-10-17T13:42:33Z

-    /// Transpose data
-    std::vector<char> transposed_bytes(bytes_per_fixedstring * element_size);
-    transposeBits<Word>(reinterpret_cast<const Word *>(value_bytes), reinterpret_cast<Word *>(transposed_bytes.data()), padded_n);
+    while (i < dimension)


Now it can be just simple for loop.

Good idea, done

Co-authored-by: Pavel Kruglov <48961922+Avogar@users.noreply.github.com>

…se/ClickHouse into qbit-transposition-optimisation

rienath · 2025-10-18T08:59:10Z

Integration tests (amd_binary, 5/5)

Flaky test_storage_nats/test_nats_jet_stream.py::test_nats_overloaded_insert #88775

Stress test (arm_asan, s3)

Stress test fails with Disk does not support WriteMode::Append #84669

clickhouse-gh Bot added the pr-not-for-changelog This PR should not be mentioned in the changelog label Oct 13, 2025

rienath changed the title ~~Add AVX512VL to dynamic dispatch and optimise QBit [un]transposition~~ Add AVX-512VL to dynamic dispatch and optimise QBit [un]transposition Oct 13, 2025

Implement [un]transposition optimisations

49f6a01

rienath force-pushed the qbit-transposition-optimisation branch from c1cfd2c to 49f6a01 Compare October 13, 2025 11:07

Remove broken casts

632ce2e

rienath commented Oct 13, 2025

View reviewed changes

Avogar self-assigned this Oct 14, 2025

Avogar reviewed Oct 14, 2025

View reviewed changes

Use max_binary_array_size settings to validate QBit binary serializat…

c6a5309

…ion size

rienath commented Oct 16, 2025

View reviewed changes

Remove trailing zeroes in QBit RowBinary serialization

eda0769

rienath force-pushed the qbit-transposition-optimisation branch from 5877065 to eda0769 Compare October 16, 2025 11:37

Avogar approved these changes Oct 17, 2025

View reviewed changes

rienath and others added 4 commits October 17, 2025 16:20

Use array_size instead of string_size for array

566b631

Co-authored-by: Pavel Kruglov <48961922+Avogar@users.noreply.github.com>

Optimise loop

be72a5a

Merge branch 'qbit-transposition-optimisation' of github.com:ClickHou…

f307135

…se/ClickHouse into qbit-transposition-optimisation

Use array_size instead of string_size for array 2.0

47c15c5

rienath added this pull request to the merge queue Oct 18, 2025

Merged via the queue into master with commit f3fc9af Oct 18, 2025
120 of 123 checks passed

rienath deleted the qbit-transposition-optimisation branch October 18, 2025 09:27

robot-clickhouse-ci-1 added the pr-synced-to-cloud The PR is synced to the cloud repo label Oct 18, 2025

-              11100000
-              11100000
-              11100000
-              11100000
-              11100000
-              11100000
+              00000111
+              00000111
+              00000111
+              00000111
+              00000111
+              00000111

		if (size > DEFAULT_MAX_STRING_SIZE)
		throw Exception(ErrorCodes::TOO_LARGE_ARRAY_SIZE, "Too large QBit dimension (maximum: {})", DEFAULT_MAX_STRING_SIZE);

Conversation

rienath commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog category (leave one):

Uh oh!

clickhouse-gh Bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Avogar Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rienath left a comment

Choose a reason for hiding this comment

Uh oh!

Avogar left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rienath commented Oct 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rienath commented Oct 13, 2025 •

edited

Loading

clickhouse-gh Bot commented Oct 13, 2025 •

edited

Loading

Avogar Oct 14, 2025 •

edited

Loading

rienath commented Oct 18, 2025 •

edited

Loading