Rotational Quantization (RQ)
Starting with v1.33, you can set a default quantization for new collections using the DEFAULT_QUANTIZATION environment variable. This variable is not set by default, meaning no quantization is applied unless you explicitly configure it. When set (e.g., to 8-bit RQ quantization), all newly created collections will use that quantization setting. Note that once set on a collection, quantization can't be disabled. Default quantization won't be applied to a collection if the index type isn't supported (for example PQ and SQ aren't supported for the flat index).
Rotational quantization (RQ) is a fast vector compression technique that offers significant performance benefits. Three RQ variants are available in Weaviate:
- 8-bit RQ: Up to 4x compression while retaining almost perfect recall (98-99% on most datasets). Recommended for most use cases.
- 4-bit RQ: Up to 8x compression, roughly half the size of 8-bit RQ, and it depends on rescoring to reach comparable recall. Available for the
hnswindex only. - 1-bit RQ: Close to 32x compression as dimensionality increases with moderate recall across various datasets.
8-bit RQ
v1.32 and v1.358-bit Rotational quantization (RQ) for the HNSW vector index was added in v1.32.
8-bit Rotational quantization (RQ) for the flat vector index was added in v1.35.
8-bit RQ provides up-to 4x compression while maintaining 98-99% recall in internal testing. It is generally recommended for most use cases as the default quantization techniques.
Enable compression for new collection
RQ can be enabled at collection creation time through the collection definition:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
name="MyCollection",
vector_config=Configure.Vectors.text2vec_openai(
quantizer=Configure.VectorIndex.Quantizer.rq()
),
properties=[
Property(name="title", data_type=DataType.TEXT),
],
)
import weaviate, { configure } from '@weaviate/node';
await client.collections.create({
name: "MyCollection",
vectorizers: configure.vectors.text2VecOpenAI({
quantizer: configure.vectorIndex.quantizer.rq()
}),
properties: [
{ name: "title", dataType: weaviate.configure.dataType.TEXT }
]
})
// Define the configuration for RQ. Setting 'enabled' to true
rq_config := map[string]interface{}{
"enabled": true,
}
// Define the class schema
class := &models.Class{
Class: className,
Vectorizer: "text2vec-openai",
// Assign the RQ configuration to the vector index config
VectorIndexConfig: map[string]interface{}{
"rq": rq_config,
},
}
// Create the collection in Weaviate
err = client.Schema().ClassCreator().
WithClass(class).
Do(context.Background())
_, err := client.Collections.Create(ctx, collections.Collection{
Name: "MyCollection",
Properties: []collections.Property{
{Name: "title", DataType: collections.DataTypeText},
},
Vectors: map[string]collections.VectorConfig{
"default": {
Vectorizer: openai.Text2Vec{},
// Set the index explicitly. The client sends compression only with it.
Index: vectorindex.HNSW{},
Compression: compression.RQ{Bits: 8},
},
},
})
if err != nil {
// handle error
panic(err)
}
client.collections.create("MyCollection",
col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc
.quantization(Quantization.rq())
)).properties(Property.text("title")));
await client.Collections.Create(
new CollectionCreateParams
{
Name = "MyCollection",
Properties = [Property.Text("title")],
VectorConfig = Configure.Vector(
"default",
v => v.Text2VecTransformers(),
index: new VectorIndex.HNSW
{
Quantizer = new VectorIndex.Quantizers.RQ(),
}
),
}
);
Enable compression for existing collection
RQ can also be enabled for an existing collection by updating the collection definition:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Reconfigure
collection = client.collections.use("MyCollection")
collection.config.update(
vector_config=Reconfigure.Vectors.update(
name="default",
vector_index_config=Reconfigure.VectorIndex.hnsw(
quantizer=Reconfigure.VectorIndex.Quantizer.rq(),
),
)
)
import { reconfigure } from '@weaviate/node';
const collection = client.collections.use("MyCollection")
await collection.config.update({
vectorizers: [ reconfigure.vectors.update({
name: "default",
vectorIndexConfig: reconfigure.vectorIndex.hnsw({
quantizer: reconfigure.vectorIndex.quantizer.rq(),
}),
})]
})
CollectionHandle<Map<String, Object>> collection =
client.collections.use("MyCollection");
collection.config.update(c -> c.vectorConfig(VectorConfig
.text2vecTransformers(vc -> vc.quantization(Quantization.rq()))));
await collection.Config.Update(c =>
{
var vectorConfig = c.VectorConfig["default"];
vectorConfig.VectorIndexConfig.UpdateHNSW(h =>
h.Quantizer = new VectorIndex.Quantizers.RQ()
);
});
// Get the existing collection configuration
class, err := client.Schema().ClassGetter().
WithClassName(className).Do(context.Background())
if err != nil {
log.Fatalf("get class for vec idx cfg update: %v", err)
}
// Get the current vector index configuration
cfg := class.VectorIndexConfig.(map[string]interface{})
// Add RQ configuration to enable quantization
cfg["rq"] = map[string]interface{}{
"enabled": true,
}
// Update the class configuration
class.VectorIndexConfig = cfg
// Apply the updated configuration to the collection
err = client.Schema().ClassUpdater().
WithClass(class).Do(context.Background())
if err != nil {
log.Fatalf("update class to use rq: %v", err)
}
// Coming soon
4-bit RQ
v1.404-bit RQ stores each dimension in 4 bits, which gives a smaller index than 8-bit RQ at some cost in accuracy. For sizes and trade-offs, see 4-bit RQ.
hnsw indexA dynamic index uses 4-bit RQ only after it converts to HNSW. For the bit widths each index type accepts, see RQ parameters.
Enable compression for new collection
4-bit RQ can be enabled at collection creation time through the collection definition:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
name="MyCollection",
vector_config=Configure.Vectors.text2vec_openai(
quantizer=Configure.VectorIndex.Quantizer.rq(
bits=4,
rescore_limit=20, # Optional: Number of candidates to fetch before rescoring
)
),
properties=[
Property(name="title", data_type=DataType.TEXT),
],
)
import weaviate, { configure } from '@weaviate/node';
await client.collections.create({
name: "MyCollection",
vectorizers: configure.vectors.text2VecOpenAI({
quantizer: configure.vectorIndex.quantizer.rq({
bits: 4,
rescoreLimit: 20, // Optional: Number of candidates to fetch before rescoring
})
}),
properties: [
{ name: "title", dataType: weaviate.configure.dataType.TEXT }
]
})
// Define the configuration for RQ. 'bits' set to 4 requires an hnsw index
rq_config := map[string]interface{}{
"enabled": true,
"bits": 4,
"rescoreLimit": 20, // Optional: Number of candidates to fetch before rescoring
}
// Define the class schema
class := &models.Class{
Class: className,
Vectorizer: "text2vec-openai",
// Assign the RQ configuration to the vector index config
VectorIndexConfig: map[string]interface{}{
"rq": rq_config,
},
}
// Create the collection in Weaviate
err = client.Schema().ClassCreator().
WithClass(class).
Do(context.Background())
client.collections.create("MyCollection",
col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc
.quantization(Quantization.rq(q -> q.bits(4)))
)).properties(Property.text("title")));
await client.Collections.Create(
new CollectionCreateParams
{
Name = "MyCollection",
Properties = [Property.Text("title")],
VectorConfig = Configure.Vector(
"default",
v => v.Text2VecTransformers(),
index: new VectorIndex.HNSW
{
Quantizer = new VectorIndex.Quantizers.RQ
{
Bits = 4,
RescoreLimit = 20, // Optional: Number of candidates to fetch before rescoring
},
}
),
}
);
Enable compression for existing collection
4-bit RQ can also be enabled for an existing collection that is not yet compressed, by updating the collection definition. Weaviate re-encodes the existing vectors in the background.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Reconfigure
collection = client.collections.use("MyCollection")
collection.config.update(
vector_config=Reconfigure.Vectors.update(
name="default",
vector_index_config=Reconfigure.VectorIndex.hnsw(
quantizer=Reconfigure.VectorIndex.Quantizer.rq(
bits=4,
rescore_limit=20,
),
),
)
)
// Get the existing collection configuration
class, err := client.Schema().ClassGetter().
WithClassName(className).Do(context.Background())
if err != nil {
log.Fatalf("get class for vec idx cfg update: %v", err)
}
// Get the current vector index configuration
cfg := class.VectorIndexConfig.(map[string]interface{})
// Add RQ configuration to enable 4-bit quantization
cfg["rq"] = map[string]interface{}{
"enabled": true,
"bits": 4,
"rescoreLimit": 20, // Optional: Number of candidates to fetch before rescoring
}
// Update the class configuration
class.VectorIndexConfig = cfg
// Apply the updated configuration to the collection
err = client.Schema().ClassUpdater().
WithClass(class).Do(context.Background())
if err != nil {
log.Fatalf("update class to use rq: %v", err)
}
CollectionHandle<Map<String, Object>> collection =
client.collections.use("MyCollection");
collection.config
.update(c -> c.vectorConfig(VectorConfig.text2vecTransformers(
vc -> vc.quantization(Quantization.rq(q -> q.bits(4))))));
await collection.Config.Update(c =>
{
var vectorConfig = c.VectorConfig["default"];
vectorConfig.VectorIndexConfig.UpdateHNSW(h =>
h.Quantizer = new VectorIndex.Quantizers.RQ { Bits = 4, RescoreLimit = 20 }
);
});
1-bit RQ
v1.33 and v1.351-bit Rotational quantization (RQ) for the HNSW vector index was added in v1.33.
1-bit Rotational quantization (RQ) for the flat vector index was added in v1.35.
1-bit RQ is an quantization technique that provides close to 32x compression as dimensionality increases. 1-bit RQ serves as a more robust and accurate alternative to BQ with only a slight performance trade-off. While more performant than PQ in terms of encoding time and distance calculations, 1-bit RQ typically offers slightly lower recall than well-tuned PQ.
Enable compression for new collection
RQ can be enabled at collection creation time through the collection definition:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
name="MyCollection",
vector_config=Configure.Vectors.text2vec_openai(
quantizer=Configure.VectorIndex.Quantizer.rq(bits=1)
),
properties=[
Property(name="title", data_type=DataType.TEXT),
],
)
import weaviate, { configure } from '@weaviate/node';
await client.collections.create({
name: "MyCollection",
vectorizers: configure.vectors.text2VecOpenAI({
quantizer: configure.vectorIndex.quantizer.rq({
bits: 1,
})
}),
properties: [
{ name: "title", dataType: weaviate.configure.dataType.TEXT }
]
})
// Define the configuration for RQ. Setting 'enabled' to true
rq_config := map[string]interface{}{
"enabled": true,
"bits": 1,
}
// Define the class schema
class := &models.Class{
Class: className,
Vectorizer: "text2vec-openai",
// Assign the RQ configuration to the vector index config
VectorIndexConfig: map[string]interface{}{
"rq": rq_config,
},
}
// Create the collection in Weaviate
err = client.Schema().ClassCreator().
WithClass(class).
Do(context.Background())
_, err := client.Collections.Create(ctx, collections.Collection{
Name: "MyCollection",
Properties: []collections.Property{
{Name: "title", DataType: collections.DataTypeText},
},
Vectors: map[string]collections.VectorConfig{
"default": {
Vectorizer: openai.Text2Vec{},
// Set the index explicitly. The client sends compression only with it.
Index: vectorindex.HNSW{},
Compression: compression.RQ{Bits: 1},
},
},
})
if err != nil {
// handle error
panic(err)
}
client.collections.create("MyCollection",
col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc
.quantization(Quantization.rq(q -> q.bits(1)))
)).properties(Property.text("title")));
await client.Collections.Create(
new CollectionCreateParams
{
Name = "MyCollection",
Properties = [Property.Text("title")],
VectorConfig = Configure.Vector(
"default",
v => v.Text2VecTransformers(),
index: new VectorIndex.HNSW
{
Quantizer = new VectorIndex.Quantizers.RQ { Bits = 1 },
}
),
}
);
Enable compression for existing collection
RQ can also be enabled for an existing collection by updating the collection definition:
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Reconfigure
collection = client.collections.use("MyCollection")
collection.config.update(
vector_config=Reconfigure.Vectors.update(
name="default",
vector_index_config=Reconfigure.VectorIndex.hnsw(
quantizer=Reconfigure.VectorIndex.Quantizer.rq(bits=1),
),
)
)
import { reconfigure } from '@weaviate/node';
const collection = client.collections.use("MyCollection")
await collection.config.update({
vectorizers: [ reconfigure.vectors.update({
name: "default",
vectorIndexConfig: reconfigure.vectorIndex.hnsw({
quantizer: reconfigure.vectorIndex.quantizer.rq({ bits: 1 }),
}),
})]
})
// Get the existing collection configuration
class, err := client.Schema().ClassGetter().
WithClassName(className).Do(context.Background())
if err != nil {
log.Fatalf("get class for vec idx cfg update: %v", err)
}
// Get the current vector index configuration
cfg := class.VectorIndexConfig.(map[string]interface{})
// Add RQ configuration to enable scalar quantization
cfg["rq"] = map[string]interface{}{
"enabled": true,
"bits": 1,
}
// Update the class configuration
class.VectorIndexConfig = cfg
// Apply the updated configuration to the collection
err = client.Schema().ClassUpdater().
WithClass(class).Do(context.Background())
if err != nil {
log.Fatalf("update class to use rq: %v", err)
}
// Coming soon
CollectionHandle<Map<String, Object>> collection =
client.collections.use("MyCollection");
collection.config
.update(c -> c.vectorConfig(VectorConfig.text2vecTransformers(
vc -> vc.quantization(Quantization.rq(q -> q.bits(1))))));
await collection.Config.Update(c =>
{
var vectorConfig = c.VectorConfig["default"];
vectorConfig.VectorIndexConfig.UpdateHNSW(h =>
h.Quantizer = new VectorIndex.Quantizers.RQ { Bits = 1 }
);
});
RQ parameters
To tune RQ, use these quantization and vector index parameters:
| Parameter | Type | Default | Details |
|---|---|---|---|
rq: bits | integer | 8 | The number of bits used to quantize each data point. Value can be 8, 4 or 1, but not every index type accepts all three. The hnsw index type accepts 8, 4 and 1. The flat index type accepts only 8 and 1. The hfresh index type accepts only 1. This parameter is fixed once RQ is enabled and cannot be changed afterwards. Learn more about 8-bit, 4-bit and 1-bit RQ. |
rq: rescoreLimit | integer | 20 (hnsw, 8-bit and 4-bit)512 (hnsw, 1-bit)-1 (flat) | The minimum number of candidates to fetch before rescoring. Mutable at any time. The default depends on the vector index type, and under hnsw also on bits: 20 for 8-bit and 4-bit RQ, and 512 for 1-bit RQ. Under the flat index type the default is -1, which lets Weaviate pick the limit. The Java client sends this parameter under a field name that Weaviate does not read, so values set from that client are ignored and the server default applies. These defaults apply to the hnsw and flat index types. For the HFresh index, see HFresh index parameters. |
rq: centering | boolean | false | Centers the vectors on their mean before 4-bit RQ compression. Only valid on the hnsw index with bits set to 4. Not supported for multi-vector embeddings without MUVERA. Weaviate computes the mean from a sample of up to trainingLimit vectors. Compression starts once a shard holds more than trainingLimit vectors. Cannot be changed once RQ is enabled. Added in v1.39.3 |
rq: trainingLimit | integer | 10000 | The maximum number of vectors per shard sampled to compute the mean for centering. Must be greater than 0 when centering is true. Has no effect without centering. Added in v1.39.3 |
rq : cache | boolean | false | Whether to cache the vectors in memory. (only when using the flat vector index type) |
vectorCacheMaxObjects | integer | 1e12 | Maximum number of objects in the memory cache. By default, this limit is set to one trillion (1e12) objects when a new collection is created. For sizing recommendations, see Vector cache considerations. |
RQ supports the cosine, dot and l2-squared distance metrics. Other distance metrics are not supported.
If a snippet doesn't work or you have feedback, please open a GitHub issue.
from weaviate.classes.config import Configure, Property, DataType
client.collections.create(
name="MyCollection",
vector_config=Configure.Vectors.text2vec_openai(
quantizer=Configure.VectorIndex.Quantizer.rq(
bits=8, # Optional: Number of bits
rescore_limit=20, # Optional: Number of candidates to fetch before rescoring
cache=True, # Optional: Enable caching for flat index (enabled by default for for HNSW)
),
vector_index_config=Configure.VectorIndex.flat(
vector_cache_max_objects=100000, # Optional: Maximum number of objects in the memory cache
),
),
properties=[
Property(name="title", data_type=DataType.TEXT),
],
)
import weaviate, { configure } from '@weaviate/node';
await client.collections.create({
name: "MyCollection",
vectorizers: configure.vectors.text2VecOpenAI({
quantizer: configure.vectorIndex.quantizer.rq({
bits: 8, // Optional: Number of bits
rescoreLimit: 20, // Optional: Number of candidates to fetch before rescoring
}),
}),
properties: [
{ name: "title", dataType: weaviate.configure.dataType.TEXT }
],
})
// Define a custom configuration for RQ
rq_with_options_config := map[string]interface{}{
"enabled": true,
"bits": 8, // Optional: Number of bits
"rescoreLimit": 20, // Optional: Number of candidates to fetch before rescoring
}
// Define the class schema with the custom RQ config and other HNSW settings
class_with_options := &models.Class{
Class: className,
Vectorizer: "text2vec-openai",
VectorIndexConfig: map[string]interface{}{
"rq": rq_with_options_config,
},
}
// Create the collection in Weaviate
err = client.Schema().ClassCreator().
WithClass(class_with_options).
Do(context.Background())
_, err := client.Collections.Create(ctx, collections.Collection{
Name: "MyCollection",
Properties: []collections.Property{
{Name: "title", DataType: collections.DataTypeText},
},
Vectors: map[string]collections.VectorConfig{
"default": {
Vectorizer: openai.Text2Vec{},
Compression: compression.RQ{
Bits: 8, // Number of bits
RescoreLimit: 20, // Candidates to fetch before rescoring
Cache: true, // Cache for the flat index (HNSW caches by default)
},
Index: vectorindex.Flat{
VectorCacheMaxObjects: 100000, // Maximum number of objects in the memory cache
},
},
},
})
if err != nil {
// handle error
panic(err)
}
client.collections.create("MyCollection",
col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc
.quantization(Quantization.rq(q -> q.bits(8) // Optional: Number of bits
.rescoreLimit(20) // Optional: Number of candidates to fetch before rescoring
))
)).properties(Property.text("title")));
await client.Collections.Create(
new CollectionCreateParams
{
Name = "MyCollection",
Properties = [Property.Text("title")],
VectorConfig = Configure.Vector(
"default",
v => v.Text2VecTransformers(),
index: new VectorIndex.HNSW
{
Quantizer = new VectorIndex.Quantizers.RQ
{
Bits = 8, // Optional: Number of bits
RescoreLimit = 20, // Optional: Number of candidates to fetch before rescoring
},
}
),
}
);
Additional considerations
Multiple vector embeddings (named vectors)
Collections can have multiple named vectors. The vectors in a collection can have their own configurations, and compression must be enabled independently for each vector. Every vector is independent and can use PQ, BQ, RQ, SQ, or no compression.
Multi-vector embeddings (ColBERT, ColPali, etc.)
v1.30Multi-vector embeddings (implemented through models like ColBERT, ColPali, or ColQwen) represent each object or query using multiple vectors instead of a single vector. On an hnsw index, multi-vectors support PQ, BQ, RQ, SQ, or no compression. On an hfresh index (from v1.40), the MUVERA encoding is always compressed with 1-bit RQ.
During the initial search phase, compressed vectors are used for efficiency. However, when computing the MaxSim operation, uncompressed vectors are utilized to ensure more precise similarity calculations. This approach balances the benefits of compression for search efficiency with the accuracy of uncompressed vectors during final scoring.
RQ supports multi-vector embeddings. On an hnsw index, each token vector is rounded up to a multiple of 64 dimensions, which may result in less than the nominal compression ratio for very short vectors. This is a technical limitation that may be addressed in future versions.
Further resources
- Starter guides: Compression
- Reference: Vector index
- Concepts: Vector quantization
- Concepts: Vector index
Questions and feedback
Have a question or feedback? Here's how to reach us.
