Search Points

Learn how to perform vector similarity search in Qdrant using the search API with various parameters and filters.

Search is the core operation in Qdrant. It finds the nearest neighbors to a given query vector based on the configured distance metric.

API Endpoint

POST /collections/{collection_name}/points/search

Basic Vector Search

Find points most similar to your query vector.

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "limit": 10
  }'

Search Parameters

vector · array · required

Query vector to search for. Must match the collection’s vector dimensions.

limit · integer · default: "10"

Maximum number of results to return.

offset · integer · default: "0"

Skip first N results. Useful for pagination.

score_threshold · number

Minimum score threshold. Only return results with score above this value.

with_payload · boolean | array

Include payload in the results. Can be true, false, or an array of specific fields.

with_vector · boolean | array

Include vectors in the results. Can be true, false, or an array of specific vector names.

filter · object

Filter conditions to apply. See the filtering guide for details.

Search with Score Threshold

Only return results that meet a minimum similarity score.

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "limit": 10,
    "score_threshold": 0.8
  }'

The score threshold interpretation depends on the distance metric:

• Cosine: 0 to 1 (higher is more similar)
• Dot: -∞ to +∞ (higher is more similar)
• Euclid: 0 to +∞ (lower is more similar)

Control Payload and Vector Returns

Return Specific Payload Fields

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "limit": 5,
    "with_payload": ["city", "country"]
  }'

Include/Exclude Vectors

Include vectors

{
  "vector": [0.2, 0.1, 0.9, 0.7],
  "limit": 5,
  "with_vector": true
}

Exclude vectors

{
  "vector": [0.2, 0.1, 0.9, 0.7],
  "limit": 5,
  "with_vector": false
}

Specific named vectors

{
  "vector": [0.2, 0.1, 0.9, 0.7],
  "limit": 5,
  "with_vector": ["text", "image"]
}

Search with Named Vectors

For collections with multiple named vectors, specify which vector to search.

REST API

curl -X POST http://localhost:6333/collections/multi_vector_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": {
      "name": "text",
      "vector": [0.2, 0.1, 0.9, 0.7]
    },
    "limit": 10
  }'

Search with Filters

Combine vector similarity with payload filtering.

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "filter": {
      "must": [
        {
          "key": "country",
          "match": {
            "value": "Germany"
          }
        }
      ]
    },
    "limit": 5
  }'

Advanced Search Parameters

Search Params

Fine-tune the search algorithm for better performance or accuracy.

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.2, 0.1, 0.9, 0.7],
    "limit": 10,
    "params": {
      "hnsw_ef": 128,
      "exact": false
    }
  }'

params.hnsw_ef · integer · default: "dynamic"

Size of the dynamic candidate list for HNSW index. Higher values improve accuracy but reduce speed.

params.exact · boolean · default: "false"

If true, perform exact search (brute force) instead of approximate search.

params.indexed_only · boolean · default: "false"

If true, only search indexed vectors, skip unindexed segments.

Batch Search

Perform multiple searches in a single request for better efficiency.

REST API

curl -X POST http://localhost:6333/collections/my_collection/points/search/batch \
  -H 'Content-Type: application/json' \
  -d '{
    "searches": [
      {
        "vector": [0.2, 0.1, 0.9, 0.7],
        "limit": 3
      },
      {
        "vector": [0.5, 0.3, 0.2, 0.8],
        "limit": 3
      }
    ]
  }'

Response Format

result · array

Array of scored points.

result[].id · integer | string

Point ID.

result[].version · integer

Point version.

result[].score · number

Similarity score.

result[].payload · object

Point payload (if requested).

result[].vector · array | object

Point vector(s) (if requested).

Response Example

{
  "result": [
    {
      "id": 1,
      "version": 3,
      "score": 0.95,
      "payload": {
        "city": "Berlin",
        "country": "Germany"
      },
      "vector": [0.2, 0.15, 0.88, 0.72]
    },
    {
      "id": 5,
      "version": 2,
      "score": 0.87,
      "payload": {
        "city": "Munich",
        "country": "Germany"
      }
    }
  ],
  "status": "ok",
  "time": 0.001234
}

Query Parameters

consistency · string

Read consistency level:

• majority - Wait for majority of replicas
• quorum - Wait for quorum of replicas
• all - Wait for all replicas

timeout · integer

Operation timeout in seconds.

Large limit values (>1000) may impact performance. Consider pagination for large result sets.

Best Practices

1. Limit Size: Keep limit values reasonable (10-100) for best performance
2. Score Threshold: Use score thresholds to filter out low-quality results
3. Payload Selection: Only request needed payload fields to reduce response size
4. Batch Requests: Use batch search when performing multiple searches
5. HNSW EF: Increase hnsw_ef for better accuracy at the cost of speed