Scalar Quantization (SQ)

Added in v1.26.0

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 Client v4

from weaviate.classes.config import Configure

client.collections.create(
    name="MyCollection",
    vector_config=Configure.Vectors.text2vec_openai(
        name="default",
        quantizer=Configure.VectorIndex.Quantizer.sq(),
    ),
)

  API docs

Python Client v3

class_definition = {
    "class": "MyCollection",
    "vectorizer": "text2vec-openai",  # Can be any vectorizer
    "vectorIndexType": "hnsw",
    "vectorIndexConfig": {
        "SQ": {
            "enabled": True,
        },
    },
    #  Remainder not shown
}

client.schema.create_class(class_definition)

  API docs  Deprecated (v3)

Go

// Define the configuration for SQ. Setting 'enabled' to true
sq_config := map[string]interface{}{
  "enabled": true,
}

// Define the class schema
class := &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 Weaviate
err = client.Schema().ClassCreator().
  WithClass(class).
  Do(context.Background())

  API docs

Java

WeaviateClass myCollection = WeaviateClass.builder()
    .className("MyCollection")
    .vectorizer("text2vec-openai")
    .vectorIndexConfig(VectorIndexConfig.builder()
        .sq(SQConfig.builder()
            .enabled(true)
            .build())
        .build())
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build()))
    .build();

Result<Boolean> createResult = client.schema().classCreator()
    .withClass(myCollection)
    .run();

  API docs

Enable compression for existing collection

Added in v1.31

The ability to enable SQ compression after collection creation was added in Weaviate v1.31.

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

Python Client v4

from weaviate.classes.config import Reconfigure

collection = client.collections.get("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
            ),
        )
    )
)

  API docs

Go

// 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)
}

  API docs

Java

WeaviateClass updatedCollection = WeaviateClass.builder()
    .className("MyCollection")
    .description("Updated collection with SQ compression")
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build()))
    .vectorizer("text2vec-openai")
    .vectorIndexConfig(VectorIndexConfig.builder()
        .sq(SQConfig.builder()
            .enabled(true)
            .rescoreLimit(10L)
            .build())
        .build())
    .build();

Result<Boolean> updateResult = client.schema().classUpdater()
    .withClass(updatedCollection)
    .run();

  API docs

SQ parameters

To tune SQ, set these vectorIndexConfig parameters.

Parameter	Type	Default	Details
sq: enabled	boolean	false	Uses SQ when true. The Python client v4 does not use the enabled parameter. To enable SQ with the v4 client, set a quantizer in the collection definition.
sq: rescoreLimit	integer	-1	The minimum number of candidates to fetch before rescoring.
sq: trainingLimit	integer	100000	The size of the training set to determine scalar bucket boundaries.
sq: cache	boolean	false	Use the vector cache when true.
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 Client v4

from weaviate.classes.config import Configure

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

  API docs

Python Client v3

class_definition = {
    "class": "MyCollection",
    "vectorizer": "text2vec-openai",  # Can be any vectorizer
    "vectorIndexType": "hnsw",
    "vectorIndexConfig": {
        "SQ": {
            "enabled": True,
            "rescoreLimit": 200,  # The minimum number of candidates to fetch before rescoring
            "cache": True,  # Default: False
        },
        "vectorCacheMaxObjects": 100000,  # Cache size (used if `cache` enabled)
    },
    # Remainder not shown
}

client.schema.create_class(class_definition)

  API docs  Deprecated (v3)

Go

// 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 settings
class_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 Weaviate
err = client.Schema().ClassCreator().
  WithClass(class_with_options).
  Do(context.Background())

  API docs

Java

WeaviateClass myCollection = WeaviateClass.builder()
    .className("MyCollection")
    .vectorizer("text2vec-openai")
    .vectorIndexConfig(VectorIndexConfig.builder()
        .sq(SQConfig.builder()
            .enabled(true)
            .rescoreLimit(20L)
            .build())
        .build())
    .properties(Arrays.asList(
        Property.builder()
            .name("title")
            .dataType(Arrays.asList(DataType.TEXT))
            .build()))
    .build();

Result<Boolean> createResult = client.schema().classCreator()
    .withClass(myCollection)
    .run();

  API docs

Additional considerations

Multiple vector embeddings (named vectors)

Added in v1.24

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

• Starter guides: Compression
• Reference: Vector index
• Concepts: Vector quantization
• Concepts: Vector index

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.