skip to content

Which Weaviate collection settings can you change after creation, and which are fixed?

level: seniorimportance: should knowfreq 45%

answer

  1. Tunable half versus structural half
  2. Search-time effort can be retuned live
  3. Adding a property is safe; retyping is not
  4. Index type and metric are decided at creation
  5. Fixed settings mean re-import behind an alias

basics

~20 s

Search-time and maintenance settings are mutable through collection.config.update, and properties can be added. The structural choices are fixed: vector index type, distance metric, whether multi-tenancy is enabled, and any existing property's data type. Changing those means a new collection and a re-import.

solid answer

~50 s

Weaviate splits collection configuration into what you can retune and what you decided at creation. Mutable through `collection.config.update(...)` with `Reconfigure`: HNSW search-time effort such as `ef` and the dynamic-ef settings, vector cache size, cleanup interval, whether a quantizer is enabled, inverted-index settings like the BM25 parameters and stopwords, and replication settings. `collection.config.add_property(...)` appends a new property safely. Fixed at creation: the vector index type (hnsw, flat or dynamic), the distance metric, the HNSW build parameters `max_connections` and `ef_construction`, whether multi-tenancy is enabled, and every existing property's data type and index flags. Properties also cannot be deleted. That asymmetry is the operational point. Anything on the fixed list is a migration: create a second collection with the corrected definition, re-import, verify, then cut reads over — an alias makes that switch atomic for clients. So budget the thinking at `collections.create`, and keep the definition in version control.

code

python · 16 lines
python
import weaviate
import weaviate.classes.config as wvcc

client = weaviate.connect_to_local()
articles = client.collections.get("Article")

# mutable: search-time effort
articles.config.update(
    vector_index_config=wvcc.Reconfigure.VectorIndex.hnsw(ef=256),
)

# mutable: additive property
articles.config.add_property(
    wvcc.Property(name="summary", data_type=wvcc.DataType.TEXT),
)
client.close()

go deeper

for a junior

Know that some Weaviate collection settings can be updated later and some cannot, and that adding a property is allowed while changing an existing property's type is not.

for a middle

Name the split concretely: search-time HNSW effort, cache and cleanup, quantizer enablement and inverted-index parameters are mutable; index type, distance metric, build parameters, tenancy and property types are not.

for a senior

Demonstrate the migration mechanics — build alongside, re-import from a source of truth, verify, repoint an alias, delete late — and the habit of verifying live config against the intended definition on startup.

for a principal

Own the consequence: because structural choices are permanent for the life of the data, sizing, tenancy and metric decisions belong to design review, and the re-import path must be rehearsed before you need it.

## Two classes of setting Every Weaviate collection carries a definition, and the useful mental model is that it has a *tunable* half and a *structural* half. The tunable half is everything the server can change while the data sits where it is. The structural half is everything that determines how the data was laid out in the first place — change it and the layout would have to be rebuilt, which Weaviate does not do in place. ## What you can change `collection.config.update(...)` accepts `Reconfigure` objects from `weaviate.classes.config`, mirroring the `Configure` objects you used at creation. In practice you use it for: - **Search-time HNSW effort.** `ef`, and the dynamic-ef minimum, maximum and factor, plus the cutoff at which small filtered result sets fall back to a flat scan. These trade latency against recall and are exactly the knobs you want to move under production load. - **Memory and maintenance.** The vector cache size and the cleanup interval for tombstoned objects. - **Quantization.** Enabling a quantizer on an existing HNSW collection is supported — the common pattern is to import at full precision, then compress once the data is loaded. - **Inverted index behaviour.** BM25 parameters and stopword configuration. - **Replication.** Replication settings, including asynchronous replication, can be adjusted after creation on current versions. - **New properties.** `collection.config.add_property(Property(name="summary", data_type=DataType.TEXT))` is additive and safe; existing objects simply have no value for it. ## What you cannot change - **Vector index type.** hnsw, flat or dynamic is decided at creation. There is no in-place conversion between hnsw and flat. - **Distance metric.** The metric decides how the index was built; switching it invalidates the structure. - **HNSW build parameters.** `max_connections` and `ef_construction` shaped the graph as it was constructed and cannot be revised afterwards. - **Multi-tenancy.** Whether a collection is multi-tenant is fixed. You cannot convert a single-tenant collection into a tenanted one, or the reverse. - **Property data types and index flags.** An existing property keeps its type and its filterable/searchable configuration forever, and properties cannot be deleted. - **The vectoriser module bound to the collection.** ## Why the split exists The fixed list is not arbitrary. Each item determined how bytes were written: which graph edges exist, which shard an object lives in, which inverted-index structures were populated. Changing them means rewriting everything, which is a re-import by another name. Weaviate declines to hide that behind a config call, which is honest — an engine that silently rebuilt a billion-vector index on a config change would be worse. ## The migration pattern When you must change a fixed setting: create a new collection carrying the corrected definition; re-import from your source of truth, which is why the source of truth should never be Weaviate alone; verify by comparing counts and spot-checking queries; then switch readers. Weaviate supports collection aliases, so readers can address a stable alias name that you repoint at the new collection, making the cutover a metadata change rather than a client deployment. Delete the old collection only after you are confident, since deletion is total. Re-import is the expensive part, and it is expensive twice over if the objects have to be re-embedded. If your pipeline keeps the vectors it computed, you can re-import with vectors supplied rather than paying the embedding bill again — a good reason to persist embeddings outside the database. ## Operating consequences Three habits follow. First, treat `collections.create` as a schema migration: reviewed, version-controlled, applied deliberately, not called by application code on startup with whatever defaults were handy. Second, add a startup check that reads `collection.config.get()` and compares it against the definition your code expects, so drift between environments is caught immediately rather than at query time. Third, when planning capacity, remember that the index type and tenancy model you pick are effectively permanent for the life of the data — which is why the sizing and tenancy conversations belong at design time, not after the first million objects.

  • How do you cut clients over to a rebuilt collection without changing application code?
    Point them at a collection alias instead of the collection name. You build the new collection alongside the old one, re-import and verify it, then repoint the alias at the new collection. Readers using the alias follow the switch immediately, so the cutover is a metadata change rather than a coordinated deployment, and rolling back means repointing the alias again.
  • Why is enabling quantization after import a common pattern rather than setting it up front?
    Compressing vectors is a lossy transformation whose quality depends on the data. Importing at full precision first lets you measure baseline recall and latency, then enable the quantizer and measure again, so you know exactly what compression cost you. It also keeps import simple. Since enabling a quantizer on an existing HNSW collection is a supported update, you lose nothing by deferring it.
  • What should you check before assuming a config.update actually took effect?
    Read the definition back with `collection.config.get()` and confirm the field you set has the value you expect. Update calls apply only to mutable settings, so a value you believed you changed may simply have been ignored or rejected. Making that read-back part of your deployment step turns silent no-ops into visible failures, which matters most for settings applied rarely.

saying these in an interview costs you the question

  • Says any collection setting can be updated in place
  • Thinks changing the distance metric just rebuilds automatically
  • Believes properties can be dropped or retyped
  • Assumes multi-tenancy can be switched on later
  • Plans a re-import without a source of truth outside Weaviate

context

resolving links…