Qdrant (qdrant/qdrant)

Qdrant

https://github.com/qdrant/qdrant
Admin
Qdrant is a production-ready vector similarity search engine and vector database that provides an...

Tokens:20,756
Snippets:136
Trust Score:9.8
Update:2 weeks ago
Show doc for...
Context Summary (auto-generated)
Raw
# Qdrant - Vector Search Engine

Qdrant (read: "quadrant") is a high-performance vector similarity search engine and vector database written in Rust. It provides a production-ready service with a convenient REST and gRPC API to store, search, and manage points (vectors with additional payload). Qdrant is tailored for extended filtering support, making it useful for neural-network or semantic-based matching, faceted search, recommendations, and other AI applications.

The engine supports advanced features including hybrid search with sparse vectors, vector quantization for memory efficiency, distributed deployment with sharding and replication, and comprehensive payload filtering with support for keywords, full-text, numerical ranges, and geo-locations. Qdrant can be deployed as a Docker container, through Qdrant Cloud, or built from source, and provides official client libraries for Python, JavaScript/TypeScript, Go, Rust, .NET/C#, and Java.

## Running Qdrant with Docker

Start a local Qdrant instance using Docker for development and testing purposes.

```bash
# Pull and run the latest Qdrant image
docker run -p 6333:6333 qdrant/qdrant

# Run with persistent storage and custom configuration
docker run -p 6333:6333 \
    -v $(pwd)/path/to/data:/qdrant/storage \
    -v $(pwd)/path/to/snapshots:/qdrant/snapshots \
    -v $(pwd)/path/to/custom_config.yaml:/qdrant/config/production.yaml \
    qdrant/qdrant
```

## Get Server Information

Returns information about the running Qdrant instance including version and commit ID.

```bash
curl 'http://localhost:6333/'

# Expected response:
# {
#   "title": "qdrant - vector search engine",
#   "version": "1.17.0"
# }
```

## Create Collection

Create a new collection with specified vector configuration and distance metric. Collections store points (vectors with payloads) and support multiple distance metrics including Dot, Cosine, Euclidean, and Manhattan.

```bash
curl -X PUT 'http://localhost:6333/collections/my_collection' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "vectors": {
            "size": 384,
            "distance": "Cosine"
        },
        "optimizers_config": {
            "default_segment_number": 2
        },
        "replication_factor": 1
    }'

# Expected response:
# {
#   "result": true,
#   "status": "ok",
#   "time": 0.031095451
# }
```

## Get Collection Info

Retrieve detailed information about an existing collection including configuration, vector count, and status.

```bash
curl 'http://localhost:6333/collections/my_collection'

# Expected response:
# {
#   "result": {
#     "status": "green",
#     "vectors_count": 0,
#     "points_count": 0,
#     "segments_count": 2,
#     "config": {
#       "params": {
#         "vectors": { "size": 384, "distance": "Cosine" }
#       },
#       "hnsw_config": { "m": 16, "ef_construct": 100 },
#       "optimizer_config": { "deleted_threshold": 0.2 }
#     }
#   },
#   "status": "ok",
#   "time": 0.000021
# }
```

## List Collections

Get a list of all existing collections in the database.

```bash
curl 'http://localhost:6333/collections'

# Expected response:
# {
#   "result": {
#     "collections": [
#       { "name": "my_collection" },
#       { "name": "another_collection" }
#     ]
#   },
#   "status": "ok",
#   "time": 0.000015
# }
```

## Upsert Points

Insert or update points (vectors with optional payloads) in a collection. If a point with the given ID exists, it will be overwritten.

```bash
curl -X PUT 'http://localhost:6333/collections/my_collection/points?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "points": [
            {
                "id": 1,
                "vector": [0.05, 0.61, 0.76, 0.74],
                "payload": {"city": "Berlin", "country": "Germany"}
            },
            {
                "id": 2,
                "vector": [0.19, 0.81, 0.75, 0.11],
                "payload": {"city": "London", "country": "UK"}
            },
            {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "vector": [0.36, 0.55, 0.47, 0.94],
                "payload": {"city": "Moscow", "country": "Russia"}
            }
        ]
    }'

# Expected response:
# {
#   "result": {
#     "operation_id": 0,
#     "status": "completed"
#   },
#   "status": "ok",
#   "time": 0.000206
# }
```

## Search Points

Perform vector similarity search to find the nearest neighbors. Supports optional filtering by payload fields.

```bash
# Basic vector search
curl -X POST 'http://localhost:6333/collections/my_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "vector": [0.2, 0.1, 0.9, 0.7],
        "limit": 3,
        "with_payload": true,
        "with_vectors": false
    }'

# Expected response:
# {
#   "result": [
#     { "id": 1, "score": 0.95, "payload": {"city": "Berlin"} },
#     { "id": 2, "score": 0.87, "payload": {"city": "London"} }
#   ],
#   "status": "ok",
#   "time": 0.000055
# }
```

## Search with Filtering

Combine vector search with payload filters using must, should, and must_not conditions for precise result refinement.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/points/search' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "vector": [0.2, 0.1, 0.9, 0.7],
        "limit": 5,
        "filter": {
            "must": [
                {
                    "key": "country",
                    "match": { "value": "Germany" }
                }
            ],
            "should": [
                {
                    "key": "city",
                    "match": { "any": ["Berlin", "Munich"] }
                }
            ]
        },
        "with_payload": true
    }'

# Expected response:
# {
#   "result": [
#     { "id": 1, "score": 0.95, "payload": {"city": "Berlin", "country": "Germany"} }
#   ],
#   "status": "ok",
#   "time": 0.000093
# }
```

## Get Points by ID

Retrieve full information for specific points by their IDs, including vectors and payloads.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/points' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "ids": [1, 2, 3],
        "with_payload": true,
        "with_vector": true
    }'

# Expected response:
# {
#   "result": [
#     { "id": 1, "payload": {"city": "Berlin"}, "vector": [0.05, 0.61, 0.76, 0.74] },
#     { "id": 2, "payload": {"city": "London"}, "vector": [0.19, 0.81, 0.75, 0.11] }
#   ],
#   "status": "ok",
#   "time": 0.000032
# }
```

## Delete Points

Remove points from a collection by IDs or by filter conditions.

```bash
# Delete by IDs
curl -X POST 'http://localhost:6333/collections/my_collection/points/delete?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "points": [1, 2, 3]
    }'

# Delete by filter
curl -X POST 'http://localhost:6333/collections/my_collection/points/delete?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "filter": {
            "must": [
                { "key": "country", "match": { "value": "Germany" } }
            ]
        }
    }'

# Expected response:
# {
#   "result": { "operation_id": 1, "status": "completed" },
#   "status": "ok",
#   "time": 0.000145
# }
```

## Set Payload

Add or update payload fields for existing points without modifying their vectors.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/points/payload?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "payload": {
            "category": "travel",
            "rating": 4.5,
            "tags": ["vacation", "summer"]
        },
        "points": [1, 2, 3]
    }'

# Expected response:
# {
#   "result": { "operation_id": 2, "status": "completed" },
#   "status": "ok",
#   "time": 0.000089
# }
```

## Create Payload Index

Create an index on a payload field to speed up filtered searches. Supports keyword, integer, float, geo, text, and bool field types.

```bash
curl -X PUT 'http://localhost:6333/collections/my_collection/index?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "field_name": "city",
        "field_schema": "keyword"
    }'

# For text full-text search index
curl -X PUT 'http://localhost:6333/collections/my_collection/index?wait=true' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "field_name": "description",
        "field_schema": {
            "type": "text",
            "tokenizer": "word",
            "min_token_len": 2,
            "max_token_len": 15,
            "lowercase": true
        }
    }'

# Expected response:
# {
#   "result": { "operation_id": 3, "status": "completed" },
#   "status": "ok",
#   "time": 0.015234
# }
```

## Scroll Points

Iterate through all points in a collection with pagination support, useful for data export or batch processing.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/points/scroll' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "limit": 100,
        "offset": null,
        "with_payload": true,
        "with_vector": false,
        "filter": {
            "must": [
                { "key": "country", "match": { "value": "Germany" } }
            ]
        }
    }'

# Expected response with next_page_offset for pagination:
# {
#   "result": {
#     "points": [
#       { "id": 1, "payload": {"city": "Berlin"} }
#     ],
#     "next_page_offset": 1
#   },
#   "status": "ok",
#   "time": 0.000078
# }
```

## Recommend Points

Get recommendations based on positive and negative example points, useful for building recommendation systems.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/points/recommend' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "positive": [1, 2],
        "negative": [3],
        "limit": 5,
        "with_payload": true,
        "filter": {
            "must_not": [
                { "has_id": [1, 2, 3] }
            ]
        }
    }'

# Expected response:
# {
#   "result": [
#     { "id": 4, "score": 0.89, "payload": {"city": "Paris"} },
#     { "id": 5, "score": 0.85, "payload": {"city": "Rome"} }
#   ],
#   "status": "ok",
#   "time": 0.000123
# }
```

## Create Collection Snapshot

Create a backup snapshot of a collection that can be used for disaster recovery or migration.

```bash
curl -X POST 'http://localhost:6333/collections/my_collection/snapshots?wait=true'

# Expected response:
# {
#   "result": {
#     "name": "my_collection-1234567890-snapshot.snapshot",
#     "creation_time": "2024-01-15T10:30:00Z",
#     "size": 1048576
#   },
#   "status": "ok",
#   "time": 1.234567
# }
```

## Collection Aliases

Create and manage aliases for collections, enabling zero-downtime collection updates and A/B testing.

```bash
# Create an alias
curl -X POST 'http://localhost:6333/collections/aliases' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "actions": [
            {
                "create_alias": {
                    "alias_name": "production",
                    "collection_name": "my_collection"
                }
            }
        ]
    }'

# Switch alias to new collection (atomic operation)
curl -X POST 'http://localhost:6333/collections/aliases' \
    -H 'Content-Type: application/json' \
    --data-raw '{
        "actions": [
            { "delete_alias": { "alias_name": "production" } },
            { "create_alias": { "alias_name": "production", "collection_name": "my_collection_v2" } }
        ]
    }'

# Expected response:
# {
#   "result": true,
#   "status": "ok",
#   "time": 0.000234
# }
```

## Health Check Endpoints

Kubernetes-compatible health check endpoints for container orchestration and monitoring.

```bash
# Liveness probe
curl 'http://localhost:6333/livez'
# Response: "healthz check passed"

# Readiness probe
curl 'http://localhost:6333/readyz'
# Response: "healthz check passed"

# Health check
curl 'http://localhost:6333/healthz'
# Response: "healthz check passed"
```

## Prometheus Metrics

Collect metrics data in Prometheus format for monitoring and alerting.

```bash
curl 'http://localhost:6333/metrics'

# Response (Prometheus format):
# # HELP app_info information about qdrant server
# # TYPE app_info gauge
# app_info{name="qdrant",version="1.17.0"} 1
# # HELP collections_total number of collections
# # TYPE collections_total gauge
# collections_total 3
# # HELP vectors_total total number of vectors
# # TYPE vectors_total gauge
# vectors_total{collection="my_collection"} 10000
```

## Python Client Usage

The Python client provides a convenient interface for all Qdrant operations with both sync and async support.

```python
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams, PointStruct, Filter, FieldCondition, MatchValue

# Connect to Qdrant
client = QdrantClient("localhost", port=6333)

# Or use in-memory mode for testing
# client = QdrantClient(":memory:")

# Create collection
client.create_collection(
    collection_name="my_collection",
    vectors_config=VectorParams(size=384, distance=Distance.COSINE)
)

# Upsert points
client.upsert(
    collection_name="my_collection",
    points=[
        PointStruct(
            id=1,
            vector=[0.05, 0.61, 0.76, 0.74] * 96,  # 384 dimensions
            payload={"city": "Berlin", "country": "Germany"}
        ),
        PointStruct(
            id=2,
            vector=[0.19, 0.81, 0.75, 0.11] * 96,
            payload={"city": "London", "country": "UK"}
        )
    ]
)

# Search with filter
results = client.search(
    collection_name="my_collection",
    query_vector=[0.2, 0.1, 0.9, 0.7] * 96,
    query_filter=Filter(
        must=[FieldCondition(key="country", match=MatchValue(value="Germany"))]
    ),
    limit=5
)

for hit in results:
    print(f"ID: {hit.id}, Score: {hit.score}, Payload: {hit.payload}")
```

## Cluster Status

Get information about the cluster state when running in distributed mode.

```bash
curl 'http://localhost:6333/cluster'

# Expected response (distributed mode):
# {
#   "result": {
#     "status": "enabled",
#     "peer_id": 1234567890,
#     "peers": {
#       "1234567890": { "uri": "http://node1:6335" },
#       "2345678901": { "uri": "http://node2:6335" }
#     },
#     "raft_info": {
#       "term": 5,
#       "commit": 1234,
#       "leader": 1234567890
#     }
#   },
#   "status": "ok",
#   "time": 0.000034
# }
```

## Delete Collection

Remove a collection and all its associated data permanently.

```bash
curl -X DELETE 'http://localhost:6333/collections/my_collection?timeout=60'

# Expected response:
# {
#   "result": true,
#   "status": "ok",
#   "time": 0.156789
# }
```

## Summary

Qdrant excels in AI/ML applications requiring fast vector similarity search, including semantic text search, image similarity, recommendation engines, RAG (Retrieval Augmented Generation) systems, and anomaly detection. Its rich filtering capabilities make it ideal for applications combining vector search with structured metadata queries, such as e-commerce product search with category filters or document retrieval with access control.

Integration patterns typically involve embedding models (OpenAI, Cohere, Sentence Transformers) to generate vectors, which are then stored in Qdrant with associated metadata. The engine integrates seamlessly with popular frameworks like LangChain, LlamaIndex, and Haystack for building LLM-powered applications. For production deployments, Qdrant supports horizontal scaling through sharding, high availability through replication, and can be deployed on Kubernetes with provided Helm charts or through the managed Qdrant Cloud service.