Enable RQ compression

This guide shows you how to enable RQ 8-bit compression on existing collections in your Weaviate Cloud cluster. RQ compression significantly reduces vector dimensions costs while maintaining high recall.

Permanent Change

Once compression is enabled on a collection, it cannot be disabled. Always test compression on non-production data first.

Prerequisites

• A Weaviate client library installed
• API key with write access to your Weaviate Cloud cluster

Connect to your cluster

First, establish a connection to your Weaviate Cloud cluster:

PythonJavaScript/TypeScript

  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.

import os, weaviate

# Best practice: store your credentials in environment variables
weaviate_url = os.environ["WEAVIATE_URL"]
weaviate_api_key = os.environ["WEAVIATE_API_KEY"]

client = weaviate.connect_to_weaviate_cloud(
    cluster_url=weaviate_url, auth_credentials=weaviate_api_key
)

import weaviate, { reconfigure } from 'weaviate-client';
// Best practice: store your credentials in environment variables
const weaviateUrl = process.env.WEAVIATE_URL!
const weaviateApiKey = process.env.WEAVIATE_API_KEY!

const client = await weaviate.connectToWeaviateCloud(weaviateUrl, {
    authCredentials: new weaviate.ApiKey(weaviateApiKey),
})

Replace YOUR-WEAVIATE-CLOUD-URL with your cluster URL (e.g., https://your-cluster.weaviate.network) and YOUR-API-KEY with your authentication key.

Update a single collection

The update syntax depends on your collection's vector index type (HNSW, flat, or dynamic) and whether it uses named vectors.

HNSW index (default)

Most collections use the HNSW index. To enable RQ 8-bit compression:

PythonJavaScript/TypeScript

  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.get("MyUncompressedCollection")
collection.config.update(
    vector_config=Reconfigure.Vectors.update(
        name="default",
        vector_index_config=Reconfigure.VectorIndex.hnsw(
            quantizer=Reconfigure.VectorIndex.Quantizer.rq(bits=8),
        ),
    )
)

import weaviate, { reconfigure } from 'weaviate-client';

const collection = client.collections.get("MyUncompressedCollection")
await collection.config.update({
    vectorizers: [ reconfigure.vectors.update({
        name: "default",
        vectorIndexConfig: reconfigure.vectorIndex.hnsw({
            quantizer: reconfigure.vectorIndex.quantizer.rq({ bits: 8 }),
        }),
    })]
})

Named vectors

If your collection uses named vectors (not "default"), update the name parameter to match your vector name.

Flat index

Compression settings on flat indexes are immutable after collection creation. You cannot enable or change compression on an existing flat index. To use RQ compression with a flat index, you must specify the compression settings when creating the collection.

Dynamic index

For collections using the dynamic index, you can update the HNSW compression settings. Note that the flat index portion of a dynamic index cannot be modified after creation:

PythonJavaScript/TypeScript

  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

# For dynamic indexes, only the HNSW portion can be updated after creation
# The flat index compression settings are immutable
collection = client.collections.get("MyUncompressedCollection")
collection.config.update(
    vector_config=Reconfigure.Vectors.update(
        name="default",
        vector_index_config=Reconfigure.VectorIndex.dynamic(
            hnsw=Reconfigure.VectorIndex.hnsw(
                quantizer=Reconfigure.VectorIndex.Quantizer.rq(bits=8),
            ),
        ),
    )
)

import weaviate, { reconfigure } from 'weaviate-client';

// For dynamic indexes, only the HNSW portion can be updated after creation
// The flat index compression settings are immutable
const collectionDynamic = client.collections.get("MyUncompressedCollection")
await collectionDynamic.config.update({
    vectorizers: [ reconfigure.vectors.update({
        name: "default",
        vectorIndexConfig: reconfigure.vectorIndex.dynamic({
            hnsw: reconfigure.vectorIndex.hnsw({
                quantizer: reconfigure.vectorIndex.quantizer.rq({ bits: 8 }),
            }),
        }),
    })]
})

Legacy collections (pre-named vectors)

Collections created before Weaviate v1.24 (when named vectors were introduced) use a different schema structure. For these collections, use vector_index_config directly instead of vector_config:

PythonJavaScript/TypeScript

  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

# For collections created before named vectors were introduced (pre-v1.24),
# use vector_index_config directly instead of vector_config
collection = client.collections.get("MyLegacyCollection")
collection.config.update(
    vector_index_config=Reconfigure.VectorIndex.hnsw(
        quantizer=Reconfigure.VectorIndex.Quantizer.rq(bits=8),
    )
)

import weaviate, { reconfigure } from 'weaviate-client';

// For collections created before named vectors were introduced (pre-v1.24),
// use vectorIndexConfig directly instead of vectorizers
const legacyCollection = client.collections.get("MyLegacyCollection")
await legacyCollection.config.update({
    vectorIndexConfig: reconfigure.vectorIndex.hnsw({
        quantizer: reconfigure.vectorIndex.quantizer.rq({ bits: 8 }),
    })
})

Update multiple collections

Before updating multiple collections, you should understand the index types in your cluster. Different index types require different update syntax.

List collections by index type

The following example categorizes your collections by their vector index types:

PythonJavaScript/TypeScript

  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.collections.classes.config import (
    _VectorIndexConfigHNSW,
    _VectorIndexConfigFlat,
    _VectorIndexConfigDynamic,
)

# Group collections by their vector index type
hnsw_collections = []
flat_collections = []
dynamic_collections = []
legacy_collections = []

collections = client.collections.list_all()

for collection_name in collections:
    collection = client.collections.get(collection_name)
    config = collection.config.get()

    # Check if this is a legacy collection (no named vectors)
    if not config.vector_config:
        # Legacy collection - check the top-level vector_index_config
        legacy_collections.append(collection_name)
        continue

    # For each named vector, determine its index type
    for vector_name, vector_config in config.vector_config.items():
        index_config = vector_config.vector_index_config
        entry = {"collection": collection_name, "vector": vector_name}

        if isinstance(index_config, _VectorIndexConfigHNSW):
            hnsw_collections.append(entry)
        elif isinstance(index_config, _VectorIndexConfigFlat):
            flat_collections.append(entry)
        elif isinstance(index_config, _VectorIndexConfigDynamic):
            dynamic_collections.append(entry)

print(f"HNSW collections: {len(hnsw_collections)}")
print(f"Flat collections: {len(flat_collections)}")
print(f"Dynamic collections: {len(dynamic_collections)}")
print(f"Legacy collections: {len(legacy_collections)}")

import weaviate, { reconfigure } from 'weaviate-client';

// Group collections by their vector index type
const hnswCollections: Array<{collection: string, vector: string}> = []
const flatCollections: Array<{collection: string, vector: string}> = []
const dynamicCollections: Array<{collection: string, vector: string}> = []
const legacyCollections: string[] = []

const allCollections = await client.collections.listAll()

for (const collectionConfig of Object.values(allCollections)) {
    const collectionName = collectionConfig.name
    try {
        const coll = client.collections.get(collectionName)
        const config = await coll.config.get()

        // Check if this is a legacy collection (no named vectors)
        if (!config.vectorizers || Object.keys(config.vectorizers).length === 0) {
            legacyCollections.push(collectionName)
            continue
        }

        // For each named vector, determine its index type
        for (const [vectorName, vectorConfig] of Object.entries(config.vectorizers)) {
            const indexType = vectorConfig.indexType
            const entry = { collection: collectionName, vector: vectorName }

            if (indexType === 'hnsw') {
                hnswCollections.push(entry)
            } else if (indexType === 'flat') {
                flatCollections.push(entry)
            } else if (indexType === 'dynamic') {
                dynamicCollections.push(entry)
            }
        }
    } catch (error) {
        console.log(`Skipping collection ${collectionName}: ${error}`)
    }
}

console.log(`HNSW collections: ${hnswCollections.length}`)
console.log(`Flat collections: ${flatCollections.length}`)
console.log(`Dynamic collections: ${dynamicCollections.length}`)
console.log(`Legacy collections: ${legacyCollections.length}`)

Update multiple collections

The following example enables RQ compression on HNSW collections in batches. To avoid cluster instability, limit each batch to approximately 100 collections:

PythonJavaScript/TypeScript

  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

# Process collections in batches to avoid cluster instability
BATCH_SIZE = 100

# Only process the first batch (adjust slice for subsequent batches)
batch = hnsw_collections[:BATCH_SIZE]

for entry in batch:
    collection_name = entry["collection"]
    vector_name = entry["vector"]

    collection = client.collections.get(collection_name)
    print(f"Enabling RQ-8 compression for {collection_name} (vector: {vector_name})")
    collection.config.update(
        vector_config=Reconfigure.Vectors.update(
            name=vector_name,
            vector_index_config=Reconfigure.VectorIndex.hnsw(
                quantizer=Reconfigure.VectorIndex.Quantizer.rq(bits=8),
            ),
        )
    )

print(
    f"Processed {len(batch)} collections. Remaining: {len(hnsw_collections) - BATCH_SIZE}"
)

import weaviate, { reconfigure } from 'weaviate-client';

// Process collections in batches to avoid cluster instability
const BATCH_SIZE = 100

// Only process the first batch (adjust slice for subsequent batches)
const batch = hnswCollections.slice(0, BATCH_SIZE)

for (const entry of batch) {
    const collectionName = entry.collection
    const vectorName = entry.vector

    const collection = client.collections.get(collectionName)
    console.log(`Enabling RQ-8 compression for ${collectionName} (vector: ${vectorName})`)
    await collection.config.update({
        vectorizers: [ reconfigure.vectors.update({
            name: vectorName,
            vectorIndexConfig: reconfigure.vectorIndex.hnsw({
                quantizer: reconfigure.vectorIndex.quantizer.rq({ bits: 8 }),
            }),
        })]
    })
}

console.log(`Processed ${batch.length} collections. Remaining: ${hnswCollections.length - BATCH_SIZE}`)

Batch size limits

Enabling compression on too many collections at once can cause cluster instability or crashes. Process collections in batches of no more than 100, and for very large collections, update them one at a time.

Dry run

Consider adding a "dry run" mode that only prints what would change without actually updating collections. Comment out the collection.config.update() call and test the logic first.

Performance considerations

Enabling compression requires additional memory during the encoding process. Plan your compression rollout carefully to avoid resource exhaustion.

Memory usage during compression

When compression is enabled on an existing collection, Weaviate re-encodes all vectors. This process temporarily increases memory usage.

Example: A collection with 1 million objects and 1,536 dimensions uses approximately 6.5 GB of memory before compression. During the compression process, memory usage increases by approximately 1.5 GB (~23% overhead) before settling to the compressed size.

Recommended approach for large clusters

Enabling compression on too many collections simultaneously can cause cluster instability or crashes. Follow these guidelines to safely roll out compression:

For clusters with multiple collections or large vector counts:

1. Assess your cluster: Use the list collections script to understand what you're working with
2. Process in batches: Limit each batch to approximately 100 collections to avoid overwhelming cluster resources
3. Handle large collections individually: For very large collections (millions of objects), enable compression one collection at a time
4. Build in buffers: Add sufficient delays between batches to allow compression to complete before starting the next batch
5. Start with smaller collections: Test on smaller collections first to understand timing and resource impact before compressing larger ones

Verify compression status

After enabling compression, verify the configuration:

PythonJavaScript/TypeScript

  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.

collection = client.collections.get("MyUncompressedCollection")
config = collection.config.get()

# Check if this is a legacy collection (no named vectors)
if config.vector_config:
    # Named vectors - iterate through vector_config
    for vector_name, vector_config in config.vector_config.items():
        print(f"\nVector: {vector_name}")
        quantizer = vector_config.vector_index_config.quantizer
        if quantizer:
            print(f"  Quantizer type: {type(quantizer).__name__}")
            if hasattr(quantizer, "bits"):
                print(f"  Bits: {quantizer.bits}")
        else:
            print("  No compression enabled")
else:
    # Legacy collection - check vector_index_config directly
    print(f"\nLegacy collection (no named vectors)")
    quantizer = config.vector_index_config.quantizer
    if quantizer:
        print(f"  Quantizer type: {type(quantizer).__name__}")
        if hasattr(quantizer, "bits"):
            print(f"  Bits: {quantizer.bits}")
    else:
        print("  No compression enabled")

import weaviate, { reconfigure } from 'weaviate-client';

const collectionToCheck = client.collections.get("MyUncompressedCollection")
const configToCheck = await collectionToCheck.config.get()

// Check if this is a legacy collection (no named vectors)
if (configToCheck.vectorizers && Object.keys(configToCheck.vectorizers).length > 0) {
    // Named vectors - iterate through vectorizers
    for (const [vectorName, vectorConfig] of Object.entries(configToCheck.vectorizers)) {
        console.log(`\nVector: ${vectorName}`)
        const quantizer = vectorConfig.indexConfig?.quantizer
        if (quantizer) {
            console.log(`  Quantizer type: ${quantizer.constructor.name}`)
            if ('bits' in quantizer) {
                console.log(`  Bits: ${quantizer.bits}`)
            }
        } else {
            console.log("  No compression enabled")
        }
    }
} else {
    // Legacy collection - check vectorIndexConfig directly
    console.log(`\nLegacy collection (no named vectors)`)
    const quantizer = configToCheck.vectorIndexConfig?.quantizer
    if (quantizer) {
        console.log(`  Quantizer type: ${quantizer.constructor.name}`)
        if ('bits' in quantizer) {
            console.log(`  Bits: ${quantizer.bits}`)
        }
    } else {
        console.log("  No compression enabled")
    }
}

You should see output confirming the quantizer type is rq with bits: 8.

What happens after enabling compression?

When you enable RQ compression on an existing collection:

1. Existing vectors are re-encoded: Weaviate automatically converts existing vector data to use RQ compression
2. Storage and memory usage are reduced: Less disk space and RAM are required for vector data
3. Query performance: Query speed remains similar with minimal recall impact (typically 1-2%)
4. Irreversible: The change cannot be undone

Compression timing

For large collections, the compression process may take some time. Your collection remains queryable during this process, but you may see temporary performance impacts during the conversion.

Best practices

• Test first: Always test compression on a non-production cluster or collection first
• Avoid bulk updates on large clusters: Do not loop through many large collections at once; process them individually or with sufficient delays
• Allow completion time: Large collections may take significant time to re-encode all vectors
• Monitor performance: Check query recall and latency after enabling compression
• Backup data: Although compression is safe, consider backing up critical data before making changes

Further resources

• How-to configure: Rotational quantization (compression)
• Concepts: Vector quantization
• Starter guides: Managing resources - Compression

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.