docs: 4-bit rotational quantization (preview, 1.39) - #509
Open
g-despot wants to merge 5 commits into
Open
Conversation
Completes the 1.39 4-bit RQ page: the Go, Java and C# tabs of the "Enable compression for new collection" and "Enable compression for existing collection" sections under 4-bit RQ now have real snippets, matching the Python and TypeScript examples already in place. - Go, C#: set bits to 4 and raise the rescore limit to 50. Both clients put the rescore limit on the wire under the name the server reads. - Java: sets bits to 4 only. The Java client serialises the rescore limit under a name the server ignores, so an example that set it would not do anything (tracked separately). - No flat-index example at 4 bits: the flat index rejects it. Also removes the Java rescore caveat include and its usage from the page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Secrets |  0  0  0  0 |
View in Orca |
Verifier findings on the 4-bit RQ branch. - Starter guide claimed "8-bit and 1-bit RQ work with every index type in the table". False for the HFresh column: hfresh accepts 1-bit only (entities/vectorindex/hfresh/config.go:142-144 at v1.39.0). Restate the support per index type: hnsw 8/4/1, flat 8/1, hfresh 1 only, dynamic per side. - The shared RQ parameters include named only the flat restriction, so a reader on the vector index reference (where it renders directly below the HFresh section) was told 8, 4 and 1 are all valid for HFresh. Name all three index types. Also state the fixed 1-bit width on the HFresh rq row. - Remove the TypeScript tab from the 4-bit "existing collection" example. It rendered an empty code block because the TS client's reconfigure path takes no bits value. The swizzled Tabs component now shows the honest "not yet available" message instead. - Rename the Go marker UpdateSchemaToEnableRQ to 8BitUpdateSchema so no marker name is a prefix of another, since FilteredTextBlock matches markers by substring. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
g-despot
marked this pull request as ready for review
August 12, 2026 13:50
…unt example Review feedback on PR #509. - Replace the "4-bit RQ limitations" subsection with a short note under "## 4-bit RQ" carrying the hnsw-only constraint. The per-index bit widths and the immutability of `bits` are already documented in the RQ parameters table and the compression starter guide. - Keep the RQ distance metric support statement by moving it into the "RQ parameters" section; it applies to all RQ variants, not just 4-bit. - Remove the 1536-dimensional byte-count example from the RQ characteristics section of the vector quantization concepts page. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documents preview support for 4-bit rotational quantization in Weaviate 1.39.
Changes:
- Adds RQ4 concepts, compatibility, sizing, and rescoring guidance.
- Adds configuration examples across five client languages.
- Updates index and environment-variable references.
Reviewed changes
Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
docs/weaviate/starter-guides/managing-resources/compression.mdx |
Clarifies RQ index compatibility. |
docs/weaviate/configuration/compression/rq-compression.md |
Adds RQ4 configuration guidance and examples. |
docs/weaviate/config-refs/indexing/vector-index.mdx |
Documents HFresh’s fixed 1-bit RQ width. |
docs/weaviate/concepts/vector-quantization.md |
Explains RQ4 mechanics, sizing, and recall. |
docs/deploy/configuration/env-vars/index.md |
Adds the rq-4 default quantization value. |
_includes/starter-guides/compression-types.mdx |
Extends the RQ overview to 4-bit. |
_includes/feature-notes/rq-4bit.mdx |
Adds the RQ4 preview notice. |
_includes/configuration/rq-compression-parameters.mdx |
Documents bit-width and rescoring parameters. |
_includes/code/java-v6/src/test/java/ConfigureRQTest.java |
Adds Java RQ4 examples. |
_includes/code/howto/go/docs/configure/compression.rq_test.go |
Adds tested Go RQ4 examples. |
_includes/code/howto/configure-rq/rq-compression-v4.py |
Adds Python RQ4 examples. |
_includes/code/howto/configure-rq/rq-compression-v3.ts |
Adds a TypeScript creation example. |
_includes/code/csharp/ConfigureRQTest.cs |
Adds C# RQ4 examples. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The "RQ comes in three bit widths" paragraph linked only the 4-bit mention. Link the first 8-bit and 1-bit mentions to the matching headings on the RQ compression reference page, using the same absolute path form as the existing 4-bit link. Later mentions of each width stay unlinked, following the first-mention convention. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… headroom Two review findings from PR #509. The compression starter-guide include claimed 98-99% recall "without any configuration" for RQ as a whole. That is an 8-bit figure. This branch extended the include to cover 4-bit, which inherits rescoreLimit 20 and does not reach that recall at its defaults. Scope the claim to 8-bit and point the narrower widths at the rescore guidance. The same broadening had reached three neighbouring claims on the host page (memory saving, the typical-recall list, and "RQ can run without rescoring"), so scope those too. The 4-bit rescoreLimit guidance said "at least the largest query limit", which permits rescoreLimit == limit. At v1.39.0 the HNSW rescore path truncates the candidate pool to rescoreLimit when rescoreLimit >= k, so that setting rescores exactly as many candidates as it returns: it can reorder the results but cannot recover a neighbour the compressed distances dropped. A query with limit 20 against the 4-bit default of 20 lands on that zero-headroom case. Require a value strictly greater than the largest query limit, give ef as the ceiling, and keep the warning that 0 disables rescoring. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents
bits: 4for rotational quantization, a headline 1.39 feature. Preview tier.Extends the existing RQ pages rather than adding new ones: the compression config page, the quantization concepts page, both starter-guide compression pages, the RQ parameter include, and the env-var reference. Examples in Python, Go, Java and C#.
The two facts that matter most
It is HNSW-only. A flat index rejects
bits: 4with "RQ bits must be either 1 or 8", and HFresh accepts 1-bit only. A dynamic index holds a flat and an HNSW config side by side, so 4-bit can only be set on the HNSW side.The default rescore limit undercuts the feature.
bits: 4inheritsrescoreLimit20, because the per-width default is keyed onBits == 1only. The recall RQ4 is sold on assumes a top-50 window, so users must raise it. The page says so.Rescore limit is shown per client, not uniformly
Go and C# show it; both put
rescoreLimiton the wire correctly. Java omits it:RQ.javaserialisesrescore_limitin snake_case while the server reads onlyrescoreLimit, so a Java-set value is silently dropped. Tracked separately.Also corrected here
The starter guide claimed "8-bit and 1-bit RQ work with every index type in the table". That was false: HFresh accepts 1-bit only. Each index type is now stated explicitly, verified against v1.39.0.
No TypeScript tab on one section
The TypeScript client's
reconfigurepath has nobitsparameter, so it cannot express 4-bit on an existing collection. That tab is omitted, which renders the standard "not yet available" message rather than a blank code block. Client gap tracked separately.Verification
Build warnings identical to a freshly built base. Go, Java and C# snippets type-check against the real clients. Every rendered code block was checked for the marker-substring hazard, including a Go marker rename to remove a latent one. The bytes-per-vector figures are verified against
rq4.go: 16 bytes metadata plusOutputDim/2, so 1536d gives 1552 for 8-bit and 784 for 4-bit.Known, not fixed here
The Java 8-bit example under "RQ parameters" still sets
.rescoreLimit(20), the call that is silently ignored. Pre-existing.Docs owner is John Trengrove, who also wrote the core PR, and should review before this merges. Two claims are worth his eye specifically: the recall figures, which no in-repo benchmark asserts, and the Preview label, which is editorial since 4-bit ships ungated.