SDK Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Milvus Rust SDK is a high-performance, asynchronous client library designed to interface with the Milvus vector database. Its architecture is built upon a layered approach, utilizing tonic for gRPC communication and prost for Protocol Buffer serialization. The SDK provides a structured interface for database management, collection operations, data manipulation, and security controls.
The core of the SDK is the Client struct, which acts as the primary entry point for all operations. It manages the underlying gRPC connection (channel), authentication state, and database context. The architecture emphasizes modularity, with specific functionalities separated into modules such as authentication, database, collection, and partition.
Sources: src/lib.rs, src/database.rs:31-41, Cargo.toml:13-28
Core Components and Modules
The SDK is organized into several key modules that handle specific domains of the Milvus API.
| Module | Description |
|---|---|
client | Manages the gRPC connection, interceptors, and high-level client logic. |
authentication | Handles user, role, and privilege management including RBAC. |
database | Provides operations for managing Milvus databases (create, drop, list, switch). |
collection | Manages collection lifecycles, schemas, and statistics. |
proto | Contains generated Rust code from Protocol Buffer definitions. |
schema | Defines builders and structures for collection and field schemas. |
Sources: src/lib.rs:17-36, src/database.rs:1-29, src/authentication.rs:1-35
Client and Interceptor Flow
The Client uses a layered interceptor pattern to handle cross-cutting concerns like Authentication and Database context. When a request is made, it passes through a CombinedInterceptor which bundles AuthInterceptor and DbInterceptor logic.
Protocol and Communication Layer
The SDK communicates with Milvus via gRPC. The protocol layer is automatically generated from .proto files during the build process using tonic-prost-build.
Service Clients
The SDK implements several specialized gRPC clients derived from the Protobuf definitions:
- MilvusServiceClient: The primary service for data and metadata operations.
- ProxyServiceClient: Used for administrative tasks like link registration.
Message Structure
Most requests wrap a MsgBase structure which includes information such as MsgType and timestamps.
Database Management Architecture
The database module allows for multi-tenancy within a single Milvus instance. It supports custom properties like replica numbers and disk quotas.
Database Switching
When using_database is called, the SDK performs the following architectural changes:
- Clears the internal
CollectionCache. - Updates the
db_namein the client state. - Re-instantiates the gRPC client with a new
DbInterceptorto inject the database name into every subsequent header.
Authentication and RBAC System
The SDK implements a robust Role-Based Access Control (RBAC) system. It supports User management, Role assignment, and Privilege granularity (Global, Database, or Collection level).
Security Implementation
- Password Handling: All passwords provided by the user are Base64 encoded before being transmitted over the wire to the
CreateCredentialorUpdateCredentialendpoints. - Privilege APIs: The SDK supports both
OperatePrivilege(v1) andOperatePrivilegeV2for more collection-centric authorization.
Error Handling and Status Processing
The SDK maps Milvus server responses to Rust Result types. Every gRPC response from the server includes a Status message.
Status Message Fields
| Field | Type | Description |
|---|---|---|
code | i32 | Numeric error code. |
reason | string | Human-readable explanation of the error. |
retriable | bool | Indicates if the client should attempt the request again. |
detail | string | Technical details regarding the failure. |
Sources: src/proto/milvus.proto.common.rs:3-17, src/utils.rs
Summary
The Milvus Rust SDK architecture is a type-safe, asynchronous wrapper around the Milvus gRPC API. By leveraging Rust's ownership model and the tonic ecosystem, it provides a performant and reliable way to interact with vector data. The use of interceptors for authentication and database context management ensures that developer code remains clean while maintaining complex server-side requirements for multi-tenancy and security.