0
# Vector Operations
1

2
Point insertion, updating, deletion, and retrieval operations including batch processing and bulk upload utilities.
3

4
## Capabilities
5

6
### Point Insertion and Updates
7

8
Insert or update individual points and batches of points.
9

10
```python { .api }
11
def upsert(
12
    self,
13
    collection_name: str,
14
    points: Iterable[PointStruct],
15
    wait: bool = True,
16
    ordering: Optional[WriteOrdering] = None,
17
    shard_key_selector: Optional[ShardKeySelector] = None,
18
    **kwargs
19
) -> UpdateResult:
20
    """
21
    Insert or update points in collection.
22

23
    Parameters:
24
    - collection_name: Name of the collection
25
    - points: Iterable of points to upsert
26
    - wait: Wait for operation to complete
27
    - ordering: Write ordering guarantees
28
    - shard_key_selector: Shard key for routing
29

30
    Returns:
31
        UpdateResult: Result of the operation
32
    """
33

34
def upload_points(
35
    self,
36
    collection_name: str,
37
    points: Iterable[PointStruct],
38
    batch_size: int = 100,
39
    parallel: int = 1,
40
    max_retries: int = 3,
41
    wait: bool = True,
42
    shard_key_selector: Optional[ShardKeySelector] = None,
43
) -> None:
44
    """
45
    Upload points in batches with automatic retry.
46

47
    Parameters:
48
    - collection_name: Name of the collection
49
    - points: Iterable of points to upload
50
    - batch_size: Number of points per batch
51
    - parallel: Number of parallel upload threads
52
    - max_retries: Maximum retry attempts
53
    - wait: Wait for operation to complete
54
    - shard_key_selector: Shard key for routing
55
    """
56

57
def batch_update_points(
58
    self,
59
    collection_name: str,
60
    update_operations: List[PointsUpdateOperation],
61
    wait: bool = True,
62
    ordering: Optional[WriteOrdering] = None,
63
    **kwargs
64
) -> List[UpdateResult]:
65
    """
66
    Perform batch update of points.
67

68
    Parameters:
69
    - collection_name: Name of the collection
70
    - update_operations: List of update operations
71
    - wait: Wait for operation to complete
72
    - ordering: Write ordering guarantees
73

74
    Returns:
75
        List[UpdateResult]: Results of operations
76
    """
77
```
78

79
Usage examples:
80

81
```python
82
import numpy as np
83
from qdrant_client import models
84

85
# Single point upsert
86
point = models.PointStruct(
87
    id=1,
88
    vector=np.random.rand(100).tolist(),
89
    payload={"category": "test", "value": 42}
90
)
91
client.upsert(collection_name="test_collection", points=[point])
92

93
# Batch upsert
94
points = [
95
    models.PointStruct(
96
        id=i,
97
        vector=np.random.rand(100).tolist(),
98
        payload={"index": i, "category": f"cat_{i % 5}"}
99
    )
100
    for i in range(1000)
101
]
102
client.upsert(collection_name="test_collection", points=points)
103

104
# Large-scale upload with batching
105
client.upload_points(
106
    collection_name="test_collection",
107
    points=points,
108
    batch_size=50,
109
    parallel=4
110
)
111
```
112

113
### Point Retrieval
114

115
Retrieve points by ID or scroll through all points.
116

117
```python { .api }
118
def retrieve(
119
    self,
120
    collection_name: str,
121
    ids: List[PointId],
122
    with_payload: Union[bool, List[str], PayloadSelector] = True,
123
    with_vectors: Union[bool, List[str]] = False,
124
    shard_key_selector: Optional[ShardKeySelector] = None,
125
    **kwargs
126
) -> List[Record]:
127
    """
128
    Retrieve points by their IDs.
129

130
    Parameters:
131
    - collection_name: Name of the collection
132
    - ids: List of point IDs to retrieve
133
    - with_payload: Include payload in response
134
    - with_vectors: Include vectors in response
135
    - shard_key_selector: Shard key for routing
136

137
    Returns:
138
        List[Record]: Retrieved points
139
    """
140

141
def scroll(
142
    self,
143
    collection_name: str,
144
    scroll_filter: Optional[Filter] = None,
145
    limit: Optional[int] = None,
146
    offset: Optional[PointId] = None,
147
    with_payload: Union[bool, List[str], PayloadSelector] = True,
148
    with_vectors: Union[bool, List[str]] = False,
149
    order_by: Optional[OrderBy] = None,
150
    shard_key_selector: Optional[ShardKeySelector] = None,
151
    **kwargs
152
) -> Tuple[List[Record], Optional[PointId]]:
153
    """
154
    Scroll through points in collection.
155

156
    Parameters:
157
    - collection_name: Name of the collection
158
    - scroll_filter: Filter for points to scroll through
159
    - limit: Maximum number of points to return
160
    - offset: Starting point ID for pagination
161
    - with_payload: Include payload in response
162
    - with_vectors: Include vectors in response
163
    - order_by: Sort order for results
164
    - shard_key_selector: Shard key for routing
165

166
    Returns:
167
        Tuple[List[Record], Optional[PointId]]: Points and next offset
168
    """
169
```
170

171
### Point Deletion
172

173
Delete points by ID or filter criteria.
174

175
```python { .api }
176
def delete(
177
    self,
178
    collection_name: str,
179
    points_selector: Union[PointIdsList, FilterSelector],
180
    wait: bool = True,
181
    ordering: Optional[WriteOrdering] = None,
182
    shard_key_selector: Optional[ShardKeySelector] = None,
183
    **kwargs
184
) -> UpdateResult:
185
    """
186
    Delete points from collection.
187

188
    Parameters:
189
    - collection_name: Name of the collection
190
    - points_selector: Points to delete (by ID or filter)
191
    - wait: Wait for operation to complete
192
    - ordering: Write ordering guarantees
193
    - shard_key_selector: Shard key for routing
194

195
    Returns:
196
        UpdateResult: Result of the operation
197
    """
198
```
199

200
Usage examples:
201

202
```python
203
# Delete by IDs
204
client.delete(
205
    collection_name="test_collection",
206
    points_selector=models.PointIdsList(points=[1, 2, 3, 4])
207
)
208

209
# Delete by filter
210
client.delete(
211
    collection_name="test_collection",
212
    points_selector=models.FilterSelector(
213
        filter=models.Filter(
214
            must=[
215
                models.FieldCondition(
216
                    key="category",
217
                    match=models.MatchValue(value="outdated")
218
                )
219
            ]
220
        )
221
    )
222
)
223
```
224

225
### Payload Operations
226

227
Update and delete payload fields without affecting vectors.
228

229
```python { .api }
230
def set_payload(
231
    self,
232
    collection_name: str,
233
    payload: Payload,
234
    points: Union[List[PointId], Filter, None] = None,
235
    wait: bool = True,
236
    ordering: Optional[WriteOrdering] = None,
237
    shard_key_selector: Optional[ShardKeySelector] = None,
238
    **kwargs
239
) -> UpdateResult:
240
    """
241
    Set payload for specified points.
242

243
    Parameters:
244
    - collection_name: Name of the collection
245
    - payload: Payload to set
246
    - points: Points to update (IDs or filter)
247
    - wait: Wait for operation to complete
248
    - ordering: Write ordering guarantees
249
    - shard_key_selector: Shard key for routing
250

251
    Returns:
252
        UpdateResult: Result of the operation
253
    """
254

255
def overwrite_payload(
256
    self,
257
    collection_name: str,
258
    payload: Payload,
259
    points: Union[List[PointId], Filter, None] = None,
260
    wait: bool = True,
261
    ordering: Optional[WriteOrdering] = None,
262
    shard_key_selector: Optional[ShardKeySelector] = None,
263
    **kwargs
264
) -> UpdateResult:
265
    """
266
    Overwrite payload for specified points.
267

268
    Parameters:
269
    - collection_name: Name of the collection
270
    - payload: New payload (replaces existing)
271
    - points: Points to update (IDs or filter)
272
    - wait: Wait for operation to complete
273
    - ordering: Write ordering guarantees
274
    - shard_key_selector: Shard key for routing
275

276
    Returns:
277
        UpdateResult: Result of the operation
278
    """
279

280
def delete_payload(
281
    self,
282
    collection_name: str,
283
    keys: List[str],
284
    points: Union[List[PointId], Filter, None] = None,
285
    wait: bool = True,
286
    ordering: Optional[WriteOrdering] = None,
287
    shard_key_selector: Optional[ShardKeySelector] = None,
288
    **kwargs
289
) -> UpdateResult:
290
    """
291
    Delete payload keys from specified points.
292

293
    Parameters:
294
    - collection_name: Name of the collection
295
    - keys: Payload keys to delete
296
    - points: Points to update (IDs or filter)
297
    - wait: Wait for operation to complete
298
    - ordering: Write ordering guarantees
299
    - shard_key_selector: Shard key for routing
300

301
    Returns:
302
        UpdateResult: Result of the operation
303
    """
304

305
def clear_payload(
306
    self,
307
    collection_name: str,
308
    points_selector: Union[PointIdsList, FilterSelector],
309
    wait: bool = True,
310
    ordering: Optional[WriteOrdering] = None,
311
    shard_key_selector: Optional[ShardKeySelector] = None,
312
    **kwargs
313
) -> UpdateResult:
314
    """
315
    Clear all payload from specified points.
316

317
    Parameters:
318
    - collection_name: Name of the collection
319
    - points_selector: Points to clear (by ID or filter)
320
    - wait: Wait for operation to complete
321
    - ordering: Write ordering guarantees
322
    - shard_key_selector: Shard key for routing
323

324
    Returns:
325
        UpdateResult: Result of the operation
326
    """
327
```
328

329
### Point Counting
330

331
Count points in collection with optional filtering.
332

333
```python { .api }
334
def count(
335
    self,
336
    collection_name: str,
337
    count_filter: Optional[Filter] = None,
338
    exact: bool = True,
339
    shard_key_selector: Optional[ShardKeySelector] = None,
340
    **kwargs
341
) -> CountResult:
342
    """
343
    Count points in collection.
344

345
    Parameters:
346
    - collection_name: Name of the collection
347
    - count_filter: Filter for points to count
348
    - exact: Whether to return exact count
349
    - shard_key_selector: Shard key for routing
350

351
    Returns:
352
        CountResult: Point count
353
    """
354
```
355

356
## Data Types
357

358
### Point Structures
359

360
```python { .api }
361
class PointStruct(BaseModel):
362
    id: PointId  # Point identifier
363
    vector: Union[VectorStruct, Dict[str, VectorStruct]]  # Vector data
364
    payload: Optional[Payload] = None  # Associated metadata
365

366
class Record(BaseModel):
367
    id: PointId
368
    payload: Optional[Payload] = None
369
    vector: Optional[Union[VectorStruct, Dict[str, VectorStruct]]] = None
370
    shard_key: Optional[ShardKey] = None
371

372
# Type aliases
373
PointId = Union[str, int]
374
VectorStruct = List[float]
375
Payload = Dict[str, Any]
376
```
377

378
### Selection and Filtering
379

380
```python { .api }
381
class PointIdsList(BaseModel):
382
    points: List[PointId]
383

384
class FilterSelector(BaseModel):
385
    filter: Filter
386

387
class PayloadSelector(BaseModel):
388
    include: Optional[List[str]] = None  # Include specific payload keys
389
    exclude: Optional[List[str]] = None  # Exclude specific payload keys
390
```
391

392
### Update Operations
393

394
```python { .api }
395
class UpdateResult(BaseModel):
396
    operation_id: Optional[int] = None
397
    status: UpdateStatus
398

399
class UpdateStatus(str, Enum):
400
    ACKNOWLEDGED = "acknowledged"
401
    COMPLETED = "completed"
402

403
class WriteOrdering(str, Enum):
404
    WEAK = "weak"      # No ordering guarantees
405
    MEDIUM = "medium"  # Updates applied in order
406
    STRONG = "strong"  # Consistent ordering across all operations
407

408
class CountResult(BaseModel):
409
    count: int
410
```
411

412
### Batch Operations
413

414
```python { .api }
415
class PointsUpdateOperation(BaseModel):
416
    upsert: Optional[PointsList] = None
417
    delete: Optional[PointsSelector] = None
418
    set_payload: Optional[SetPayload] = None
419
    overwrite_payload: Optional[SetPayload] = None
420
    delete_payload: Optional[DeletePayload] = None
421
    clear_payload: Optional[PointsSelector] = None
422

423
class PointsList(BaseModel):
424
    points: List[PointStruct]
425
    shard_key: Optional[ShardKey] = None
426

427
class PointsSelector(BaseModel):
428
    points: Union[PointIdsList, FilterSelector]
429
    shard_key: Optional[ShardKey] = None
430
```