Skip to main content
Go to documentation:
⌘U
Weaviate Database

Develop AI applications using Weaviate's APIs and tools

Deploy

Deploy, configure, and maintain Weaviate Database

Query Agent

Run agentic search over your Weaviate Cloud collections

Weaviate Cloud

Manage and scale Weaviate in the cloud

Engram

Persistent memory for LLM agents and applications

Additional resources

Integrations
Weaviate Academy

Need help?

Weaviate LogoAsk AI Assistant⌘K
Support
Community Forum
Contributor guide

Rotational Quantization (RQ)

Compression by Default

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 hnsw index only.
  • 1-bit RQ: Close to 32x compression as dimensionality increases with moderate recall across various datasets.

8-bit RQ​

Added in v1.32 and v1.35

8-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:

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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:

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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​

Added in v1.40

4-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.

4-bit RQ requires the hnsw index

A 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:

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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​

Added in v1.33 and v1.35

1-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:

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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:

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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:

ParameterTypeDefaultDetails
rq: bitsinteger8The 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: rescoreLimitinteger20 (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: centeringbooleanfalseCenters 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: trainingLimitinteger10000The 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 : cachebooleanfalseWhether to cache the vectors in memory.
(only when using the flat vector index type)
vectorCacheMaxObjectsinteger1e12Maximum 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.

py docs  API docs
More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

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.)​

Added in v1.30

Multi-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.

Multi-vector performance

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​

Questions and feedback​