0
# Milvus Lite
1

2
A lightweight version of Milvus wrapped with Python for AI applications requiring vector similarity search. Milvus Lite provides the core vector search functionality of Milvus in a compact, embedded form suitable for development environments, prototyping, and edge devices.
3

4
## Package Information
5

6
- **Package Name**: milvus-lite
7
- **Language**: Python
8
- **Installation**: `pip install milvus-lite` (or `pip install pymilvus` which includes milvus-lite)
9

10
## Core Imports
11

12
```python
13
# Import through pymilvus (recommended approach)
14
from pymilvus import MilvusClient
15

16
# Direct imports (advanced usage)
17
from milvus_lite.server import Server
18
from milvus_lite.server_manager import server_manager_instance
19

20
# Package version
21
import milvus_lite
22
print(milvus_lite.__version__)
23
```
24

25
## Basic Usage
26

27
```python
28
from pymilvus import MilvusClient
29
import numpy as np
30

31
# Create client with local database file (this activates milvus-lite)
32
client = MilvusClient("./milvus_demo.db")
33

34
# Create a collection with vector dimension
35
client.create_collection(
36
    collection_name="demo_collection",
37
    dimension=384  # Vector dimension
38
)
39

40
# Prepare sample data
41
docs = [
42
    "Artificial intelligence was founded as an academic discipline in 1956.",
43
    "Alan Turing was the first person to conduct substantial research in AI.",
44
    "Born in Maida Vale, London, Turing was raised in southern England.",
45
]
46

47
# Generate vectors (in practice, use actual embedding models)
48
vectors = [[np.random.uniform(-1, 1) for _ in range(384)] for _ in range(len(docs))]
49
data = [{"id": i, "vector": vectors[i], "text": docs[i], "subject": "history"} for i in range(len(vectors))]
50

51
# Insert data
52
client.insert(collection_name="demo_collection", data=data)
53

54
# Perform vector search
55
results = client.search(
56
    collection_name="demo_collection",
57
    data=[vectors[0]],  # Query vector
58
    filter="subject == 'history'",
59
    limit=2,
60
    output_fields=["text", "subject"]
61
)
62
print(results)
63

64
# Query with filters
65
results = client.query(
66
    collection_name="demo_collection", 
67
    filter="subject == 'history'",
68
    output_fields=["text", "subject"]
69
)
70
print(results)
71
```
72

73
## Architecture
74

75
Milvus Lite is a hybrid Python-C++ implementation that provides embedded vector database functionality:
76

77
- **Python Layer**: High-level API through pymilvus SDK with automatic milvus-lite activation for local files
78
- **Server Management**: Thread-safe server lifecycle management with file locking and resource cleanup
79
- **C++ Core**: Native milvus binary providing high-performance vector operations
80
- **Process Communication**: Unix Domain Sockets (UDS) for IPC or TCP for remote connections
81
- **Data Persistence**: File-based storage with database files containing vector data and metadata
82
- **Platform Support**: Native binaries for Linux (x86_64/arm64) and macOS (Intel/Apple Silicon)
83

84
This architecture enables seamless development workflows where the same API works from local prototyping with milvus-lite to production deployment with Milvus Standalone or Distributed.
85

86
## Capabilities
87

88
### Primary Usage via PyMilvus
89

90
The recommended way to use milvus-lite through the pymilvus client interface, which automatically activates milvus-lite when using local file URIs. This provides the complete Milvus API surface including collections, vector operations, indexing, and querying.
91

92
```python { .api }
93
from pymilvus import MilvusClient
94

95
client = MilvusClient(uri="./database.db")  # Activates milvus-lite
96
# Full Milvus API available through client
97
```
98

99
[PyMilvus Integration](./pymilvus-integration.md)
100

101
### Direct Server Management
102

103
Advanced server lifecycle management for custom integrations and process control. Provides direct access to the underlying milvus server process with configuration options for networking, logging, and resource management.
104

105
```python { .api }
106
class Server:
107
    def __init__(self, db_file: str, address: Optional[str] = None): ...
108
    def init(self) -> bool: ...
109
    def start(self) -> bool: ...
110
    def stop(self) -> None: ...
111
    
112
    @property
113
    def uds_path(self) -> str: ...
114
    @property  
115
    def args(self) -> List[str]: ...
116
```
117

118
[Server Management](./server-management.md)
119

120
### Multi-Instance Management
121

122
Thread-safe management of multiple milvus-lite server instances with automatic lifecycle handling and resource cleanup. Useful for applications managing multiple independent databases or multi-tenant scenarios.
123

124
```python { .api }
125
class ServerManager:
126
    def start_and_get_uri(self, path: str, args=None) -> Optional[str]: ...
127
    def release_server(self, path: str) -> None: ...
128
    def release_all(self) -> None: ...
129

130
server_manager_instance: ServerManager  # Global singleton
131
```
132

133
[Multi-Instance Management](./multi-instance.md)
134

135
### Command Line Tools  
136

137
Data export and migration utilities for moving data between milvus-lite and other Milvus deployments. Includes collection dumping with support for various vector types and bulk data operations.
138

139
```bash { .api }
140
milvus-lite dump -d DB_FILE -c COLLECTION -p PATH
141
```
142

143
[Command Line Tools](./cli-tools.md)
144

145
## Types
146

147
```python { .api }
148
from typing import Optional, List, Dict, Any, Union
149

150
# Package-level exports
151
__version__: str  # Package version string
152

153
# Constants
154
BIN_PATH: str  # Path to directory containing milvus binary and libraries
155

156
# Core types used across the API  
157
PathType = str  # File system path to database file
158
AddressType = Optional[str]  # Network address (host:port) or None for UDS
159
URIType = str  # Connection URI (file path for milvus-lite)
160
```
161

162
## Error Handling
163

164
Milvus Lite raises specific exceptions for different error conditions:
165

166
- `RuntimeError`: Invalid database names, path issues, server startup failures
167
- `BlockingIOError`: Database file locked by another process
168
- `subprocess.TimeoutExpired`: Server process management timeouts
169
- `FileNotFoundError`: Missing binary files or database files
170

171
## Platform Requirements
172

173
- **Linux**: Ubuntu >= 20.04 (x86_64, arm64) 
174
- **macOS**: >= 11.0 (Intel x86_64, Apple Silicon M1/M2)
175
- **Windows**: Not supported
176

177
## Database Constraints
178

179
- Database filename must match regex: `^[a-zA-Z0-9.\-_]+$`
180
- Maximum filename length: 36 characters  
181
- Suitable for datasets up to ~1 million vectors
182
- File locking prevents concurrent access from multiple processes