Binary Quantization (BQ)

Binary quantization (BQ) is a vector compression technique that can reduce the size of a vector.

To use BQ, enable it as shown below and add data to the collection.

Additional information

How to set the index type

Enable compression for new collection

BQ can be enabled at collection creation time through the collection definition:

Python

from weaviate.classes.config import Configureclient.collections.create(    name="MyCollection",    vector_config=Configure.Vectors.text2vec_openai(        name="default",        quantizer=Configure.VectorIndex.Quantizer.bq(),    ),)

JavaScript/TypeScript

const collection = await client.collections.create({
  name: 'MyCollection',
  vectorizers: weaviate.configure.vectors.selfProvided({
    vectorIndexConfig: weaviate.configure.vectorIndex.hnsw({
      quantizer: weaviate.configure.vectorIndex.quantizer.bq(),
    })
  })
})

// Define the configuration for BQ. Setting 'enabled' to truebq_config := map[string]interface{}{  "enabled": true,}// Define the class schemaclass := &models.Class{  Class:      className,  Vectorizer: "text2vec-openai",  // Assign the BQ configuration to the vector index config  VectorIndexConfig: map[string]interface{}{    "bq": bq_config,  },}// Create the collection in Weaviateerr = client.Schema().ClassCreator().  WithClass(class).  Do(context.Background())

Java

client.collections.create("MyCollection",    col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc        .quantization(Quantization.bq())    )).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.BQ(),            }        ),    });

Enable compression for existing collection

BQ can also be enabled for an existing collection by updating the collection definition:

Python

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.flat(
            quantizer=Reconfigure.VectorIndex.Quantizer.bq(
                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 BQ configuration to enable binary quantization
cfg["bq"] = map[string]interface{}{
  "enabled":      true,
  "rescoreLimit": 200,
  "cache":        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 bq: %v", err)
}

Java

CollectionHandle<Map<String, Object>> collection =
    client.collections.use("MyCollection");
collection.config.update(c -> c.vectorConfig(VectorConfig
    .text2vecTransformers(vc -> vc.quantization(Quantization.bq()))));

await collection.Config.Update(c =>
{
    var vectorConfig = c.VectorConfig["default"];
    vectorConfig.VectorIndexConfig.UpdateHNSW(h =>
        h.Quantizer = new VectorIndex.Quantizers.BQ()
    );
});

BQ parameters

The following parameters are available for BQ compression, under vectorIndexConfig:

Parameter	Type	Default	Details
`bq` : `enabled`	boolean	`false`	Enable BQ. Weaviate uses binary quantization (BQ) compression when `true`. The Python client does not use the `enabled` parameter. To enable BQ with the v4 client, set a `quantizer` in the collection definition.
`bq` : `rescoreLimit`	integer	`-1`	The minimum number of candidates to fetch before rescoring. A default of `-1` lets Weaviate pick the limit. (only when using the `flat` vector index type) Under the `hnsw` vector index type, BQ has no `rescoreLimit` setting. A value set there is accepted by the API but silently discarded, and it does not appear when you read the collection definition back.
`bq` : `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.

For example:

Python

from weaviate.classes.config import Configureclient.collections.create(    name="MyCollection",    vector_config=Configure.Vectors.text2vec_openai(        name="default",        quantizer=Configure.VectorIndex.Quantizer.bq(rescore_limit=200, cache=True),        vector_index_config=Configure.VectorIndex.flat(            vector_cache_max_objects=100000,        ),    ),)

JavaScript/TypeScript

const collection = await client.collections.create({
  name: 'MyCollection',
  vectorizers: weaviate.configure.vectors.selfProvided({
    vectorIndexConfig: weaviate.configure.vectorIndex.hnsw({
      quantizer: weaviate.configure.vectorIndex.quantizer.bq({
        cache: true,     // Enable caching
        rescoreLimit: 200, // The minimum number of candidates to fetch before rescoring
      }),
      vectorCacheMaxObjects: 10000 // Cache size (used if `cache` enabled)
    })
  })
})

// Define a custom configuration for BQbq_with_options_config := map[string]interface{}{  "enabled":      true,  "rescoreLimit": 200,  // The minimum number of candidates to fetch before rescoring  "cache":        true, // Enable caching of binary quantized vectors}// Define the class schema with the custom BQ config and other HNSW settingsclass_with_options := &models.Class{  Class:      className,  Vectorizer: "text2vec-openai",  VectorIndexConfig: map[string]interface{}{    "bq": bq_with_options_config,    "distance":              "cosine", // Set the distance metric for HNSW    "vectorCacheMaxObjects": 100000,   // Configure the vector cache  },}// Create the collection in Weaviateerr = client.Schema().ClassCreator().  WithClass(class_with_options).  Do(context.Background())

Java

client.collections.create("MyCollection",    col -> col.vectorConfig(VectorConfig.text2vecTransformers(vc -> vc        .quantization(Quantization.bq(q -> q.cache(true).rescoreLimit(200)))        .vectorIndex(Hnsw.of(c -> c.vectorCacheMaxObjects(100000)))    )).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
            {
                VectorCacheMaxObjects = 100000,
                Quantizer = new VectorIndex.Quantizers.BQ
                {
                    Cache = true,
                    RescoreLimit = 200,
                },
            }
        // highlight-end
        ),
    }
);

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

Multi-vector embeddings (implemented through models like ColBERT, ColPali, or ColQwen) represent each object or query using multiple vectors instead of a single vector. Just like with single vectors, multi-vectors support PQ, BQ, RQ, SQ, or no compression.

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.

Further resources

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.