Scalar Quantization (SQ)

Scalar quantization (SQ) is a vector compression technique that can reduce the size of a vector.

To use SQ, enable it in the collection definition, then add data to the collection.

Enable compression for new collection

SQ 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.sq(),    ),)

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.sq(),
    })
  })
})

// Define the configuration for SQ. Setting 'enabled' to truesq_config := map[string]interface{}{  "enabled": true,}// Define the class schemaclass := &models.Class{  Class:      className,  Vectorizer: "text2vec-openai",  // Assign the SQ configuration to the vector index config  VectorIndexConfig: map[string]interface{}{    "sq": sq_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.sq())    )).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.SQ(),            }        ),    });

Enable compression for existing collection

SQ 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.hnsw(
            quantizer=Reconfigure.VectorIndex.Quantizer.sq(
                rescore_limit=20
            ),
        )
    )
)

JavaScript/TypeScript

const collection = client.collections.use('MyCollection');

await collection.config.update({
  vectorizers: [
    weaviate.reconfigure.vectors.update({
      name: 'default',
      vectorIndexConfig: weaviate.reconfigure.vectorIndex.hnsw({
        quantizer: weaviate.reconfigure.vectorIndex.quantizer.sq({
          rescoreLimit: 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 SQ configuration to enable scalar quantization
cfg["sq"] = map[string]interface{}{
  "enabled":       true,
  "rescoreLimit":  200,   // Optional: number of candidates to fetch before rescoring
  "trainingLimit": 50000, // Optional: number of vectors to use for training
  "cache":         true,  // Optional: enable caching of quantized vectors
}

// 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 sq: %v", err)
}

Java

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

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

SQ parameters

To tune SQ, set these vectorIndexConfig parameters.

Parameter	Type	Default	Details
`sq`: `enabled`	boolean	`false`	Uses SQ when `true`. The Python client does not use the `enabled` parameter. To enable SQ with the v4 client, set a `quantizer` in the collection definition.
`sq`: `rescoreLimit`	integer	`20` (`hnsw`) `-1` (`flat`)	The minimum number of candidates to fetch before rescoring. The default depends on the vector index type: `20` under `hnsw`, and `-1` under `flat`, which lets Weaviate pick the limit.
`sq`: `trainingLimit`	integer	100000	The size of the training set to determine scalar bucket boundaries.
`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.

Python

from weaviate.classes.config import Configureclient.collections.create(    name="MyCollection",    vector_config=Configure.Vectors.text2vec_openai(        name="default",        quantizer=Configure.VectorIndex.Quantizer.sq(            rescore_limit=200,            training_limit=50000,            cache=True,        ),        vector_index_config=Configure.VectorIndex.hnsw(            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.sq({
        rescoreLimit: 200,    // The minimum number of candidates to fetch before rescoring
        trainingLimit: 50000, // The size of the training set used to determine the bucket boundaries
      }),
      vectorCacheMaxObjects: 100000 // Maximum number of objects in the vector cache
    })
  })
})

// Define a custom configuration for SQ.sq_with_options_config := map[string]interface{}{  "enabled":       true,  "rescoreLimit":  200,   // The number of candidates to fetch before rescoring  "trainingLimit": 50000, // The number of vectors to use for training the quantizer  "cache":         true,  // Enable caching of quantized vectors}// Define the class schema with the custom SQ config and other HNSW settingsclass_with_options := &models.Class{  Class:      className,  Vectorizer: "text2vec-openai",  VectorIndexConfig: map[string]interface{}{    "sq": sq_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            .sq(q -> q.cache(true).trainingLimit(50000).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.SQ
                {
                    TrainingLimit = 50000,
                    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.