0
# Qdrant Client
1

2
A comprehensive Python client library for the Qdrant vector search engine, enabling developers to interact with Qdrant databases for vector similarity search, neural matching, and AI-powered search applications. The library offers both synchronous and asynchronous API methods with full type hints, supports both REST and gRPC protocols for optimal performance, includes a local mode for development without running a separate server, and provides helper methods for common operations like collection management and bulk data uploading.
3

4
## Package Information
5

6
- **Package Name**: qdrant-client
7
- **Language**: Python  
8
- **Installation**: `pip install qdrant-client`
9
- **Optional Features**: `pip install qdrant-client[fastembed]` for embedding generation
10

11
## Core Imports
12

13
```python
14
from qdrant_client import QdrantClient
15
```
16

17
For async operations:
18

19
```python
20
from qdrant_client import AsyncQdrantClient
21
```
22

23
Import models and types:
24

25
```python
26
from qdrant_client import models
27
from qdrant_client.models import Distance, VectorParams, PointStruct, Filter
28
```
29

30
## Basic Usage
31

32
```python
33
from qdrant_client import QdrantClient, models
34
import numpy as np
35

36
# Initialize client (local mode for development)
37
client = QdrantClient(":memory:")  # or QdrantClient(path="./qdrant_storage")
38

39
# For remote server
40
# client = QdrantClient(host="localhost", port=6333)
41

42
# Create a collection
43
client.create_collection(
44
    collection_name="my_collection",
45
    vectors_config=models.VectorParams(size=100, distance=models.Distance.COSINE),
46
)
47

48
# Insert vectors
49
vectors = np.random.rand(10, 100)
50
client.upsert(
51
    collection_name="my_collection",
52
    points=[
53
        models.PointStruct(
54
            id=idx,
55
            vector=vector.tolist(),
56
            payload={"category": "example", "number": idx}
57
        )
58
        for idx, vector in enumerate(vectors)
59
    ]
60
)
61

62
# Search for similar vectors
63
query_vector = np.random.rand(100)
64
hits = client.query_points(
65
    collection_name="my_collection",
66
    query=query_vector,
67
    limit=5
68
)
69

70
# Search with filtering
71
filtered_hits = client.query_points(
72
    collection_name="my_collection",
73
    query=query_vector,
74
    query_filter=models.Filter(
75
        must=[
76
            models.FieldCondition(
77
                key="number",
78
                range=models.Range(gte=3)
79
            )
80
        ]
81
    ),
82
    limit=5
83
)
84
```
85

86
## Architecture
87

88
The Qdrant client library is built around several key components:
89

90
- **Client Classes**: `QdrantClient` and `AsyncQdrantClient` provide the main interface
91
- **Transport Layer**: Automatic REST/gRPC protocol handling with conversion between formats
92
- **Local Mode**: `QdrantLocal` enables development without running a separate server
93
- **FastEmbed Integration**: Optional automatic embedding generation for text and images
94
- **Model System**: Comprehensive type definitions ensuring compatibility between REST and gRPC APIs
95
- **Authentication**: Bearer token support for secure connections
96

97
## Capabilities
98

99
### Client Initialization & Connection
100

101
Core client setup, connection management, and configuration options supporting local mode, remote servers, and cloud instances with authentication.
102

103
```python { .api }
104
class QdrantClient:
105
    def __init__(
106
        self,
107
        location: Optional[str] = None,
108
        url: Optional[str] = None,
109
        port: Optional[int] = 6333,
110
        grpc_port: Optional[int] = 6334,
111
        prefer_grpc: bool = False,
112
        https: Optional[bool] = None,
113
        api_key: Optional[str] = None,
114
        prefix: Optional[str] = None,
115
        timeout: Optional[float] = None,
116
        host: Optional[str] = None,
117
        path: Optional[str] = None,
118
        **kwargs
119
    ): ...
120

121
class AsyncQdrantClient:
122
    def __init__(self, **kwargs): ...
123
```
124

125
[Client Setup](./client-setup.md)
126

127
### Collection Management
128

129
Collection creation, deletion, configuration, and metadata management including vector space configuration, optimization settings, and aliasing.
130

131
```python { .api }
132
def create_collection(
133
    self,
134
    collection_name: str,
135
    vectors_config: Union[VectorParams, VectorsConfig],
136
    shard_number: Optional[int] = None,
137
    replication_factor: Optional[int] = None,
138
    write_consistency_factor: Optional[int] = None,
139
    on_disk_payload: Optional[bool] = None,
140
    hnsw_config: Optional[HnswConfig] = None,
141
    optimizers_config: Optional[OptimizersConfig] = None,
142
    wal_config: Optional[WalConfig] = None,
143
    quantization_config: Optional[QuantizationConfig] = None,
144
    init_from: Optional[InitFrom] = None,
145
    timeout: Optional[int] = None,
146
) -> bool: ...
147

148
def delete_collection(self, collection_name: str, timeout: Optional[int] = None) -> bool: ...
149
def get_collection(self, collection_name: str) -> CollectionInfo: ...
150
def get_collections(self) -> CollectionsResponse: ...
151
def collection_exists(self, collection_name: str) -> bool: ...
152
```
153

154
[Collection Management](./collection-management.md)
155

156
### Vector Operations
157

158
Point insertion, updating, deletion, and retrieval operations including batch processing and bulk upload utilities.
159

160
```python { .api }
161
def upsert(
162
    self,
163
    collection_name: str,
164
    points: Iterable[PointStruct],
165
    wait: bool = True,
166
    ordering: Optional[WriteOrdering] = None,
167
    shard_key_selector: Optional[ShardKeySelector] = None,
168
    **kwargs
169
) -> UpdateResult: ...
170

171
def upload_points(
172
    self,
173
    collection_name: str,
174
    points: Iterable[PointStruct],
175
    batch_size: int = 100,
176
    parallel: int = 1,
177
    max_retries: int = 3,
178
    wait: bool = True,
179
    shard_key_selector: Optional[ShardKeySelector] = None,
180
) -> None: ...
181

182
def delete(
183
    self,
184
    collection_name: str,
185
    points_selector: Union[PointIdsList, FilterSelector],
186
    wait: bool = True,
187
    ordering: Optional[WriteOrdering] = None,
188
    shard_key_selector: Optional[ShardKeySelector] = None,
189
    **kwargs
190
) -> UpdateResult: ...
191
```
192

193
[Vector Operations](./vector-operations.md)
194

195
### Search & Query
196

197
Vector similarity search, recommendations, discovery, and hybrid search capabilities with filtering and result ranking.
198

199
```python { .api }
200
def query_points(
201
    self,
202
    collection_name: str,
203
    query: Union[QueryRequest, NumpyArray, QueryResponse, Document, str, List[float]],
204
    query_filter: Optional[Filter] = None,
205
    search_params: Optional[SearchParams] = None,
206
    limit: int = 10,
207
    offset: Optional[int] = None,
208
    with_payload: Union[bool, List[str], PayloadSelector] = True,
209
    with_vectors: Union[bool, List[str]] = False,
210
    score_threshold: Optional[float] = None,
211
    using: Optional[str] = None,
212
    timeout: Optional[int] = None,
213
    shard_key_selector: Optional[ShardKeySelector] = None,
214
    **kwargs
215
) -> QueryResponse: ...
216

217
def recommend(
218
    self,
219
    collection_name: str,
220
    positive: Optional[List[PointId]] = None,
221
    negative: Optional[List[PointId]] = None,
222
    query_filter: Optional[Filter] = None,
223
    search_params: Optional[SearchParams] = None,
224
    limit: int = 10,
225
    offset: int = 0,
226
    with_payload: Union[bool, List[str], PayloadSelector] = True,
227
    with_vectors: Union[bool, List[str]] = False,
228
    score_threshold: Optional[float] = None,
229
    using: Optional[str] = None,
230
    lookup_from: Optional[LookupLocation] = None,
231
    timeout: Optional[int] = None,
232
    shard_key_selector: Optional[ShardKeySelector] = None,
233
    **kwargs
234
) -> List[ScoredPoint]: ...
235

236
def discover(
237
    self,
238
    collection_name: str,
239
    target: Optional[PointId] = None,
240
    context: Optional[List[ContextExamplePair]] = None,
241
    query_filter: Optional[Filter] = None,
242
    search_params: Optional[SearchParams] = None,
243
    limit: int = 10,
244
    offset: int = 0,
245
    with_payload: Union[bool, List[str], PayloadSelector] = True,
246
    with_vectors: Union[bool, List[str]] = False,
247
    using: Optional[str] = None,
248
    lookup_from: Optional[LookupLocation] = None,
249
    timeout: Optional[int] = None,
250
    shard_key_selector: Optional[ShardKeySelector] = None,
251
    **kwargs
252
) -> List[ScoredPoint]: ...
253
```
254

255
[Search & Query](./search-query.md)
256

257
### FastEmbed Integration
258

259
Automatic embedding generation for text and images using the FastEmbed library, enabling semantic search without manual vector creation.
260

261
```python { .api }
262
def get_embedding_size(self, model_name: str) -> int: ...
263

264
def upload_collection(
265
    self,
266
    collection_name: str,
267
    vectors: Union[
268
        Iterable[VectorStruct],
269
        Iterable[PointStruct], 
270
        Iterable[Record],
271
        Iterable[Document],
272
        Iterable[ImageDocument]
273
    ],
274
    ids: Optional[Iterable[PointId]] = None,
275
    batch_size: int = 100,
276
    parallel: int = 1,
277
    max_retries: int = 3,
278
    payload: Optional[Iterable[Payload]] = None,
279
    wait: bool = True,
280
    shard_key_selector: Optional[ShardKeySelector] = None,
281
) -> None: ...
282

283
def query_qdrant(
284
    self,
285
    collection_name: str,
286
    query: Union[str, Document, ImageDocument],
287
    query_filter: Optional[Filter] = None,
288
    limit: int = 10,
289
    search_params: Optional[SearchParams] = None,
290
    **kwargs
291
) -> List[QueryResponse]: ...
292
```
293

294
[FastEmbed Integration](./fastembed-integration.md)
295

296
### Indexing & Optimization
297

298
Payload field indexing, collection optimization, and performance tuning capabilities.
299

300
```python { .api }
301
def create_payload_index(
302
    self,
303
    collection_name: str,
304
    field_name: str,
305
    field_schema: Optional[PayloadFieldSchema] = None,
306
    wait: bool = True,
307
    ordering: Optional[WriteOrdering] = None,
308
    **kwargs
309
) -> UpdateResult: ...
310

311
def delete_payload_index(
312
    self,
313
    collection_name: str,
314
    field_name: str,
315
    wait: bool = True,
316
    ordering: Optional[WriteOrdering] = None,
317
    **kwargs
318
) -> UpdateResult: ...
319
```
320

321
[Indexing & Optimization](./indexing-optimization.md)
322

323
### Clustering & Sharding
324

325
Distributed operation support including shard key management, cluster operations, and multi-tenant configurations.
326

327
```python { .api }
328
def create_shard_key(
329
    self,
330
    collection_name: str,
331
    shard_key: ShardKey,
332
    shards_number: Optional[int] = None,
333
    replication_factor: Optional[int] = None,
334
    placement: Optional[List[int]] = None,
335
    timeout: Optional[int] = None,
336
    **kwargs
337
) -> bool: ...
338

339
def delete_shard_key(
340
    self,
341
    collection_name: str,
342
    shard_key: ShardKey,
343
    timeout: Optional[int] = None,
344
    **kwargs
345
) -> bool: ...
346
```
347

348
[Clustering & Sharding](./clustering-sharding.md)
349

350
### Snapshots & Backup
351

352
Collection and full database snapshot creation, management, and restoration capabilities for backup and disaster recovery.
353

354
```python { .api }
355
def create_snapshot(
356
    self,
357
    collection_name: str,
358
    wait: bool = True,
359
    **kwargs
360
) -> SnapshotDescription: ...
361

362
def create_full_snapshot(self, wait: bool = True, **kwargs) -> SnapshotDescription: ...
363
def list_snapshots(self, collection_name: str, **kwargs) -> List[SnapshotDescription]: ...
364
def delete_snapshot(
365
    self,
366
    collection_name: str,
367
    snapshot_name: str,
368
    wait: bool = True,
369
    **kwargs
370
) -> bool: ...
371
```
372

373
[Snapshots & Backup](./snapshots-backup.md)
374

375
## Core Types
376

377
```python { .api }
378
class Distance(str, Enum):
379
    COSINE = "Cosine"
380
    EUCLID = "Euclid" 
381
    DOT = "Dot"
382
    MANHATTAN = "Manhattan"
383

384
class VectorParams(BaseModel):
385
    size: int
386
    distance: Distance
387
    hnsw_config: Optional[HnswConfig] = None
388
    quantization_config: Optional[QuantizationConfig] = None
389
    on_disk: Optional[bool] = None
390

391
class PointStruct(BaseModel):
392
    id: PointId
393
    vector: Union[VectorStruct, Dict[str, VectorStruct]]
394
    payload: Optional[Payload] = None
395

396
class Filter(BaseModel):
397
    must: Optional[List[Condition]] = None
398
    must_not: Optional[List[Condition]] = None
399
    should: Optional[List[Condition]] = None
400
    min_should: Optional[MinShould] = None
401

402
class ScoredPoint(BaseModel):
403
    id: PointId
404
    version: int
405
    score: float
406
    payload: Optional[Payload] = None
407
    vector: Optional[Union[List[float], Dict[str, List[float]]]] = None
408
    shard_key: Optional[ShardKey] = None
409
    order_value: Optional[OrderValue] = None
410

411
# Type aliases
412
PointId = Union[str, int]
413
Payload = Dict[str, Any]
414
VectorStruct = List[float]
415
```