Keep vector mutations visible and isolated

Learning objective

Manage inserts, updates, reindexing, and tenant isolation.

Core idea

A vector database is a changing serving system. Write acknowledgment, read visibility, index readiness, and authorization answer different questions. A successful write alone does not establish that the next request sees the intended version, or that another tenant cannot retrieve it.

The data-source identity and ingestion pipeline belong to 6.3.2 and 6.3.3. This lesson starts when that pipeline hands the database a known record and asks how to insert or correct it, serve the intended state, replace its search structure, and enforce the tenant boundary. Keep those decisions explicit in the writer and reader interfaces.

How it works

Choose insert or replacement deliberately

Milvus insert() does not check for duplicate primary keys. Repeating an insert with an existing key can create duplicate entities. An ingestion retry must therefore not assume that sending the same key turns insert() into replacement.

Use upsert() when the request should insert a missing entity or update an existing one. In override mode, Milvus combines insertion of the supplied replacement and deletion of the existing entity. Send the intended complete record, including its vector and access metadata. If a text correction changes the embedding input, supply its recomputed vector with the corrected text; replacing only the text leaves retrieval searching the previous representation.

Milvus 2.6.2+ also supports merge mode through partial_update=True. Include the primary key and the fields to change. The documented mechanism performs a strongly consistent read, applies the supplied field changes, inserts the modified data, and deletes the previous entity. The target collection must be loaded and queryable. Merge avoids resending every field but adds read work; it is a different write path from a blind full-record replacement.

Omitted fields matter. In override mode, an omitted nullable field can become null instead of retaining its value. In merge mode, omitted fields are preserved, but a JSON field is treated as a whole: updating it does not selectively merge its individual keys. An access-policy correction that unintentionally replaces a metadata object can remove restrictions, so test the resulting record rather than counting updated rows alone.

For stable application-controlled record identity, configure the primary field accordingly. With autoID enabled, an override-mode upsert still requires the existing primary key to locate the entity, but Milvus generates a different key for the inserted replacement. Do not design a stable external-to-database ID mapping around the assumption that this replacement preserves that key.

Specify what the next reader must see

Milvus exposes consistency_level on collection creation and individual searches or queries. Its documented choices are Strong, Bounded, Eventually, and Session; Bounded is the default. Strong waits for the serving node to reach the required timestamp before searching. That wait is a latency cost, not an index-accuracy setting.

Session uses the client’s insertion timestamp to provide visibility of its writes. It fits a same-client read-after-write requirement; it is not the same requirement as arbitrary readers seeing another client’s correction. Choose Strong where a verification read must include an acknowledged correction across that boundary. Choose bounded or eventual visibility only when the application accepts that freshness behavior.

Retractions use delete() with primary keys or a filtering condition. Include the trusted tenant condition in a batch filter so a source-level deletion cannot cross tenant scope. After a correction or retraction, verify through the same serving route and required consistency level as production. A control-plane record that says “write accepted” is insufficient to establish the reader’s result.

Replace a collection behind an alias

Treat a substantial index or embedding migration as a serving change. Milvus collection aliases provide a mutable name for a collection. The documented replacement workflow creates a separate collection, populates and indexes it, and atomically reassigns the alias when it is ready. Use create_alias() to establish the serving name and alter_alias() to repoint it.

Keep the existing collection serving while validating the replacement’s data, tenant metadata, loaded search behavior, and recall–latency targets from 6.2.2. Plan capacity for both collections during overlap. If writes continue during preparation, the ingestion owner must replay the intervening source changes into the replacement or pause writes for a controlled catch-up interval before switching. Alias reassignment changes routing; it is not the application’s change-replay mechanism.

Retain the previous collection for a defined rollback interval. If it stops receiving updates, replay those updates before treating it as a valid rollback destination. A working alias switch to an outdated collection is still a freshness failure. Coordinate the query embedding configuration with a representation migration so requests use the representation that matches their target collection.

The alias moves only after the replacement is populated, indexed and validated, and after intervening changes are replayed if writes continue; the previous collection is retained for rollback.

Match tenant layout to enforcement

Milvus documents database-, collection-, partition-, and partition-key-level tenancy. Database and collection strategies support role-based access control (RBAC); partition and partition-key strategies do not provide RBAC at those respective levels. A partition layout can organize or prune data without becoming a per-tenant permission boundary.

For NVIDIA RAG Blueprint’s Milvus integration, enable authentication with common.security.authorizationEnabled: true in Milvus configuration. Its runtime APIs document Milvus credentials through the Authorization header. Missing collection privileges produce an authorization error; grant only the required collection operations to the appropriate role. The Blueprint’s POST /collection API does not support passing that token through the header, so handle collection provisioning as a separately controlled operation.

Key distinctions and trade-offs

Choose tenancy based on who enforces access and who shares a schema:

An upsert decides record replacement; consistency decides visibility; an alias decides collection routing; RBAC decides permitted operations. None substitutes for the others. Authentication identifies a caller but must be paired with the collection privileges and tenant routing the application intends.

Architecture / decision scenario

An insurance analytics assistant serves 40 firms whose analysts use separate database identities. The requirement is collection-level access enforcement and visibility of approved corrections before an analyst confirms them. A replacement index must be prepared within a 30-minute window while ingestion continues at 20 updates per second. These are project constraints.

The tempting design uses one partition per firm and grants every analyst access to the shared collection. The security owner rejects it because partition-level tenancy lacks its own RBAC. Choose one collection per firm with scoped privileges. This costs more collection management but meets the required enforcement boundary.

The ingestion owner uses controlled primary keys and full-record upsert() for text corrections, reserving partial_update=True for reviewed metadata changes. Confirmation reads use Strong rather than accepting the default bounded visibility. For reindexing, prepare each replacement behind its eventual serving alias, replay up to 36,000 intervening updates over the 30-minute window, and verify catch-up before alter_alias(). Retractions are tenant-scoped deletes and must also reach the replacement. The platform owner funds overlapping loaded collections and retains a reconciled rollback target. Merely finishing the initial bulk copy does not authorize the switch.

Common exam traps

• Treating repeated insert() calls as primary-key deduplication.
• Assuming partial updates preserve individual keys inside a replaced JSON field.
• Confusing strong read visibility with nearest-neighbor recall.
• Switching an alias before replaying changes made during preparation.
• Treating a partition key as an RBAC boundary.
• Expecting an auto-generated replacement ID to remain the same after override-mode upsert.

What to remember

Use the write operation that matches replacement semantics, verify visibility explicitly, and migrate collections through a prepared alias target. Preserve changes and tenant metadata throughout reindexing. Choose database or collection isolation when tenant permissions must be enforced there; partition organization alone does not supply that enforcement.

Knowledge check

References

• Milvus, Insert Entities
• Milvus, Upsert Entities
• Milvus, Delete Entities
• Milvus, Consistency Level
• Milvus, Manage Aliases
• Milvus, Implement Multi-tenancy
• NVIDIA, Milvus Configuration for NVIDIA RAG Blueprint