0
# Search & Query
1

2
Vector similarity search, recommendations, discovery, and hybrid search capabilities with filtering and result ranking.
3

4
## Capabilities
5

6
### Vector Similarity Search
7

8
Perform similarity search using query vectors with filtering and scoring options.
9

10
```python { .api }
11
def query_points(
12
    self,
13
    collection_name: str,
14
    query: Union[QueryRequest, NumpyArray, QueryResponse, Document, str, List[float]],
15
    query_filter: Optional[Filter] = None,
16
    search_params: Optional[SearchParams] = None,
17
    limit: int = 10,
18
    offset: Optional[int] = None,
19
    with_payload: Union[bool, List[str], PayloadSelector] = True,
20
    with_vectors: Union[bool, List[str]] = False,
21
    score_threshold: Optional[float] = None,
22
    using: Optional[str] = None,
23
    timeout: Optional[int] = None,
24
    shard_key_selector: Optional[ShardKeySelector] = None,
25
    **kwargs
26
) -> QueryResponse:
27
    """
28
    Search for similar vectors.
29

30
    Parameters:
31
    - collection_name: Name of the collection
32
    - query: Query vector, text, or search request
33
    - query_filter: Filter conditions for search results
34
    - search_params: Search algorithm parameters
35
    - limit: Maximum number of results to return
36
    - offset: Offset for pagination
37
    - with_payload: Include payload in results
38
    - with_vectors: Include vectors in results
39
    - score_threshold: Minimum score threshold
40
    - using: Vector name for multi-vector collections
41
    - timeout: Request timeout
42
    - shard_key_selector: Shard key for routing
43

44
    Returns:
45
        QueryResponse: Search results with scores
46
    """
47

48
def search(
49
    self,
50
    collection_name: str,
51
    query_vector: Union[List[float], NumpyArray, Tuple[str, List[float]]],
52
    query_filter: Optional[Filter] = None,
53
    search_params: Optional[SearchParams] = None,
54
    limit: int = 10,
55
    offset: int = 0,
56
    with_payload: Union[bool, List[str], PayloadSelector] = True,
57
    with_vectors: Union[bool, List[str]] = False,
58
    score_threshold: Optional[float] = None,
59
    append_payload: bool = True,
60
    consistency: Optional[ReadConsistency] = None,
61
    shard_key_selector: Optional[ShardKeySelector] = None,
62
    timeout: Optional[int] = None,
63
    **kwargs
64
) -> List[ScoredPoint]:
65
    """
66
    Search for similar vectors (legacy method, use query_points instead).
67

68
    Parameters:
69
    - collection_name: Name of the collection
70
    - query_vector: Query vector or named vector tuple
71
    - query_filter: Filter conditions for search results
72
    - search_params: Search algorithm parameters
73
    - limit: Maximum number of results to return
74
    - offset: Offset for pagination
75
    - with_payload: Include payload in results
76
    - with_vectors: Include vectors in results
77
    - score_threshold: Minimum score threshold
78
    - append_payload: Append payload to results
79
    - consistency: Read consistency level
80
    - shard_key_selector: Shard key for routing
81
    - timeout: Request timeout
82

83
    Returns:
84
        List[ScoredPoint]: Search results with scores
85
    """
86
```
87

88
Usage examples:
89

90
```python
91
import numpy as np
92
from qdrant_client import models
93

94
# Simple vector search
95
query_vector = np.random.rand(384).tolist()
96
results = client.query_points(
97
    collection_name="my_collection",
98
    query=query_vector,
99
    limit=10
100
)
101

102
# Search with filtering
103
results = client.query_points(
104
    collection_name="my_collection",
105
    query=query_vector,
106
    query_filter=models.Filter(
107
        must=[
108
            models.FieldCondition(
109
                key="category",
110
                match=models.MatchValue(value="important")
111
            )
112
        ]
113
    ),
114
    limit=5,
115
    score_threshold=0.7
116
)
117

118
# Multi-vector search
119
results = client.query_points(
120
    collection_name="multi_vector_collection",
121
    query=query_vector,
122
    using="text_vector",  # Specify which vector to use
123
    limit=10
124
)
125
```
126

127
### Batch Search
128

129
Perform multiple searches in a single request.
130

131
```python { .api }
132
def query_batch_points(
133
    self,
134
    collection_name: str,
135
    requests: List[QueryRequest],
136
    consistency: Optional[ReadConsistency] = None,
137
    timeout: Optional[int] = None,
138
    shard_key_selector: Optional[ShardKeySelector] = None,
139
    **kwargs
140
) -> List[QueryResponse]:
141
    """
142
    Perform batch search queries.
143

144
    Parameters:
145
    - collection_name: Name of the collection
146
    - requests: List of query requests
147
    - consistency: Read consistency level
148
    - timeout: Request timeout
149
    - shard_key_selector: Shard key for routing
150

151
    Returns:
152
        List[QueryResponse]: Batch search results
153
    """
154

155
def search_batch(
156
    self,
157
    collection_name: str,
158
    requests: List[SearchRequest],
159
    consistency: Optional[ReadConsistency] = None,
160
    timeout: Optional[int] = None,
161
    shard_key_selector: Optional[ShardKeySelector] = None,
162
    **kwargs
163
) -> List[List[ScoredPoint]]:
164
    """
165
    Perform batch search requests (legacy method).
166

167
    Parameters:
168
    - collection_name: Name of the collection
169
    - requests: List of search requests
170
    - consistency: Read consistency level
171
    - timeout: Request timeout
172
    - shard_key_selector: Shard key for routing
173

174
    Returns:
175
        List[List[ScoredPoint]]: Batch search results
176
    """
177
```
178

179
### Recommendation Search
180

181
Find points similar to positive examples and dissimilar to negative examples.
182

183
```python { .api }
184
def recommend(
185
    self,
186
    collection_name: str,
187
    positive: Optional[List[PointId]] = None,
188
    negative: Optional[List[PointId]] = None,
189
    query_filter: Optional[Filter] = None,
190
    search_params: Optional[SearchParams] = None,
191
    limit: int = 10,
192
    offset: int = 0,
193
    with_payload: Union[bool, List[str], PayloadSelector] = True,
194
    with_vectors: Union[bool, List[str]] = False,
195
    score_threshold: Optional[float] = None,
196
    using: Optional[str] = None,
197
    lookup_from: Optional[LookupLocation] = None,
198
    timeout: Optional[int] = None,
199
    shard_key_selector: Optional[ShardKeySelector] = None,
200
    **kwargs
201
) -> List[ScoredPoint]:
202
    """
203
    Recommend points based on positive and negative examples.
204

205
    Parameters:
206
    - collection_name: Name of the collection
207
    - positive: List of positive example point IDs
208
    - negative: List of negative example point IDs
209
    - query_filter: Filter conditions for results
210
    - search_params: Search algorithm parameters
211
    - limit: Maximum number of results to return
212
    - offset: Offset for pagination
213
    - with_payload: Include payload in results
214
    - with_vectors: Include vectors in results
215
    - score_threshold: Minimum score threshold
216
    - using: Vector name for multi-vector collections
217
    - lookup_from: Collection to lookup examples from
218
    - timeout: Request timeout
219
    - shard_key_selector: Shard key for routing
220

221
    Returns:
222
        List[ScoredPoint]: Recommendation results
223
    """
224

225
def recommend_batch(
226
    self,
227
    collection_name: str,
228
    requests: List[RecommendRequest],
229
    consistency: Optional[ReadConsistency] = None,
230
    timeout: Optional[int] = None,
231
    shard_key_selector: Optional[ShardKeySelector] = None,
232
    **kwargs
233
) -> List[List[ScoredPoint]]:
234
    """
235
    Perform batch recommendation requests.
236

237
    Parameters:
238
    - collection_name: Name of the collection
239
    - requests: List of recommendation requests
240
    - consistency: Read consistency level
241
    - timeout: Request timeout
242
    - shard_key_selector: Shard key for routing
243

244
    Returns:
245
        List[List[ScoredPoint]]: Batch recommendation results
246
    """
247
```
248

249
### Discovery Search
250

251
Discover points that are similar to a target but different from provided context.
252

253
```python { .api }
254
def discover(
255
    self,
256
    collection_name: str,
257
    target: Optional[PointId] = None,
258
    context: Optional[List[ContextExamplePair]] = None,
259
    query_filter: Optional[Filter] = None,
260
    search_params: Optional[SearchParams] = None,
261
    limit: int = 10,
262
    offset: int = 0,
263
    with_payload: Union[bool, List[str], PayloadSelector] = True,
264
    with_vectors: Union[bool, List[str]] = False,
265
    using: Optional[str] = None,
266
    lookup_from: Optional[LookupLocation] = None,
267
    timeout: Optional[int] = None,
268
    shard_key_selector: Optional[ShardKeySelector] = None,
269
    **kwargs
270
) -> List[ScoredPoint]:
271
    """
272
    Discover points similar to target but distinct from context.
273

274
    Parameters:
275
    - collection_name: Name of the collection
276
    - target: Target point ID for discovery
277
    - context: Context example pairs
278
    - query_filter: Filter conditions for results
279
    - search_params: Search algorithm parameters
280
    - limit: Maximum number of results to return
281
    - offset: Offset for pagination
282
    - with_payload: Include payload in results
283
    - with_vectors: Include vectors in results
284
    - using: Vector name for multi-vector collections
285
    - lookup_from: Collection to lookup examples from
286
    - timeout: Request timeout
287
    - shard_key_selector: Shard key for routing
288

289
    Returns:
290
        List[ScoredPoint]: Discovery results
291
    """
292

293
def discover_batch(
294
    self,
295
    collection_name: str,
296
    requests: List[DiscoverRequest],
297
    consistency: Optional[ReadConsistency] = None,
298
    timeout: Optional[int] = None,
299
    shard_key_selector: Optional[ShardKeySelector] = None,
300
    **kwargs
301
) -> List[List[ScoredPoint]]:
302
    """
303
    Perform batch discovery requests.
304

305
    Parameters:
306
    - collection_name: Name of the collection
307
    - requests: List of discovery requests
308
    - consistency: Read consistency level
309
    - timeout: Request timeout
310
    - shard_key_selector: Shard key for routing
311

312
    Returns:
313
        List[List[ScoredPoint]]: Batch discovery results
314
    """
315
```
316

317
## Search Configuration
318

319
### Search Parameters
320

321
```python { .api }
322
class SearchParams(BaseModel):
323
    hnsw_ef: Optional[int] = None  # Size of the dynamic candidate list
324
    exact: bool = False  # Whether to use exact search
325
    quantization: Optional[QuantizationSearchParams] = None
326
    indexed_only: bool = False  # Search only indexed vectors
327

328
class QuantizationSearchParams(BaseModel):
329
    ignore: bool = False  # Ignore quantization during search
330
    rescore: Optional[bool] = None  # Rescore with original vectors
331
    oversampling: Optional[float] = None  # Oversampling factor
332
```
333

334
### Filter Conditions
335

336
```python { .api }
337
class Filter(BaseModel):
338
    must: Optional[List[Condition]] = None  # All conditions must match
339
    must_not: Optional[List[Condition]] = None  # None of conditions must match
340
    should: Optional[List[Condition]] = None  # At least one condition should match
341
    min_should: Optional[MinShould] = None  # Minimum should conditions to match
342

343
class FieldCondition(BaseModel):
344
    key: str  # Payload field name
345
    match: Optional[MatchCondition] = None
346
    range: Optional[RangeCondition] = None  
347
    geo_bounding_box: Optional[GeoBoundingBox] = None
348
    geo_radius: Optional[GeoRadius] = None
349
    geo_polygon: Optional[GeoPolygon] = None
350
    values_count: Optional[ValuesCount] = None
351

352
class MatchCondition(BaseModel):
353
    value: Union[str, int, bool]  # Exact match value
354
    any: Optional[List[Union[str, int, bool]]] = None  # Match any of these values
355
    except_: Optional[List[Union[str, int, bool]]] = None  # Match except these values
356
    text: Optional[str] = None  # Full-text search
357

358
class RangeCondition(BaseModel):
359
    lt: Optional[float] = None  # Less than
360
    gt: Optional[float] = None  # Greater than
361
    gte: Optional[float] = None  # Greater than or equal
362
    lte: Optional[float] = None  # Less than or equal
363
```
364

365
### Geographic Filters
366

367
```python { .api }
368
class GeoRadius(BaseModel):
369
    center: GeoPoint  # Center point
370
    radius: float  # Radius in meters
371

372
class GeoBoundingBox(BaseModel):
373
    top_left: GeoPoint  # Top-left corner
374
    bottom_right: GeoPoint  # Bottom-right corner
375

376
class GeoPolygon(BaseModel):
377
    exterior: GeoLineString  # Exterior boundary
378
    interiors: Optional[List[GeoLineString]] = None  # Interior holes
379

380
class GeoPoint(BaseModel):
381
    lon: float  # Longitude
382
    lat: float  # Latitude
383
```
384

385
## Search Results
386

387
### Result Types
388

389
```python { .api }
390
class ScoredPoint(BaseModel):
391
    id: PointId
392
    version: int
393
    score: float
394
    payload: Optional[Payload] = None
395
    vector: Optional[Union[List[float], Dict[str, List[float]]]] = None
396
    shard_key: Optional[ShardKey] = None
397
    order_value: Optional[OrderValue] = None
398

399
class QueryResponse(BaseModel):
400
    points: List[ScoredPoint]
401

402
class RecommendRequest(BaseModel):
403
    positive: Optional[List[PointId]] = None
404
    negative: Optional[List[PointId]] = None
405
    filter: Optional[Filter] = None
406
    params: Optional[SearchParams] = None
407
    limit: int = 10
408
    offset: int = 0
409
    with_payload: Optional[WithPayload] = None
410
    with_vector: Optional[WithVector] = None
411
    score_threshold: Optional[float] = None
412
    using: Optional[str] = None
413
    lookup_from: Optional[LookupLocation] = None
414

415
class DiscoverRequest(BaseModel):
416
    target: Optional[PointId] = None
417
    context: Optional[List[ContextExamplePair]] = None
418
    filter: Optional[Filter] = None
419
    params: Optional[SearchParams] = None
420
    limit: int = 10
421
    offset: int = 0
422
    with_payload: Optional[WithPayload] = None
423
    with_vector: Optional[WithVector] = None
424
    using: Optional[str] = None
425
    lookup_from: Optional[LookupLocation] = None
426

427
class ContextExamplePair(BaseModel):
428
    positive: PointId
429
    negative: PointId
430
```
431

432
### Consistency Options
433

434
```python { .api }
435
class ReadConsistency(BaseModel):
436
    type: ReadConsistencyType
437
    factor: Optional[int] = None
438

439
class ReadConsistencyType(str, Enum):
440
    ALL = "all"      # Read from all replicas
441
    MAJORITY = "majority"  # Read from majority of replicas
442
    QUORUM = "quorum"     # Read from quorum of replicas
443
```