{"id":167989,"date":"2026-06-02T14:00:00","date_gmt":"2026-06-02T11:00:00","guid":{"rendered":"https:\/\/computingforgeeks.com\/?p=167989"},"modified":"2026-05-27T00:35:45","modified_gmt":"2026-05-26T21:35:45","slug":"qdrant-cheat-sheet","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/qdrant-cheat-sheet\/","title":{"rendered":"Qdrant Commands and API Cheat Sheet"},"content":{"rendered":"\n

This Qdrant cheat sheet is the one-page reference we reach for when running the vector database in real workloads. It covers the commands, REST and gRPC API calls, filter shapes, snapshots, cluster operations, and the configuration env var pattern in one scannable layout. Pin it next to your terminal. For the LLM side of a RAG stack, our Ollama commands cheat sheet<\/a> is the companion reference.<\/p>\n\n\n\n

Every command below was tested against Qdrant v1.18.x<\/strong>. Where you see ${QDRANT_VERSION}<\/code> in a script, detect the latest with curl -s https:\/\/api.github.com\/repos\/qdrant\/qdrant\/releases\/latest | jq -r .tag_name<\/code>. For the full series, start with our Qdrant vector database guide<\/strong>. The official reference lives in the Qdrant documentation<\/a>.<\/p>\n\n\n\n

Ports, defaults, and key URLs<\/h2>\n\n\n\n
Port \/ Path<\/th>Purpose<\/th><\/tr><\/thead>
6333<\/code><\/td>REST API and Web UI<\/td><\/tr>
6334<\/code><\/td>gRPC API<\/td><\/tr>
6335<\/code><\/td>P2P \/ raft consensus (cluster only)<\/td><\/tr>
\/dashboard<\/code><\/td>Built in Web UI<\/td><\/tr>
\/healthz<\/code><\/td>Liveness check<\/td><\/tr>
\/readyz<\/code><\/td>Readiness check<\/td><\/tr>
\/metrics<\/code><\/td>Prometheus \/ OpenMetrics<\/td><\/tr>
\/sys_metrics<\/code><\/td>System level metrics (host CPU, RAM, disk)<\/td><\/tr>
\/cluster<\/code><\/td>Cluster status<\/td><\/tr>
\/collections<\/code><\/td>Collection list<\/td><\/tr>
\/qdrant\/storage<\/code><\/td>Default storage path inside the container<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n

Run Qdrant with Docker<\/h2>\n\n\n\n

The fastest way to a working Qdrant. Persistent storage, both ports exposed, container restarts itself.<\/p>\n\n\n\n

docker run -d --name qdrant \\\n  -p 6333:6333 -p 6334:6334 \\\n  -v \"$(pwd)\/qdrant_storage:\/qdrant\/storage:z\" \\\n  --restart unless-stopped \\\n  qdrant\/qdrant<\/code><\/pre>\n\n\n\n
With an API key set via env var (recommended for anything reachable beyond localhost):<\/p>\n\n\n\n
docker run -d --name qdrant \\\n  -p 6333:6333 -p 6334:6334 \\\n  -v \"$(pwd)\/qdrant_storage:\/qdrant\/storage:z\" \\\n  -e QDRANT__SERVICE__API_KEY=\"$(openssl rand -base64 32)\" \\\n  --restart unless-stopped \\\n  qdrant\/qdrant<\/code><\/pre>\n\n\n\n
GPU enabled image (Qdrant 1.13+, used by the indexing path):<\/p>\n\n\n\n
docker run -d --name qdrant \\\n  --gpus all \\\n  -p 6333:6333 -p 6334:6334 \\\n  -v \"$(pwd)\/qdrant_storage:\/qdrant\/storage:z\" \\\n  qdrant\/qdrant:${QDRANT_VERSION}-gpu-nvidia<\/code><\/pre>\n\n\n\n
Docker Compose snippet<\/h2>\n\n\n\n
A reusable Compose file with persistent storage, an API key from env, and a memory limit for production:<\/p>\n\n\n\n
services:\n  qdrant:\n    image: qdrant\/qdrant:${QDRANT_VERSION}  # https:\/\/github.com\/qdrant\/qdrant\/releases\n    container_name: qdrant\n    restart: unless-stopped\n    ports:\n      - \"6333:6333\"\n      - \"6334:6334\"\n    volumes:\n      - .\/qdrant_storage:\/qdrant\/storage:z\n      - .\/qdrant_snapshots:\/qdrant\/snapshots:z\n    environment:\n      QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}\n    deploy:\n      resources:\n        limits:\n          memory: 4G<\/code><\/pre>\n\n\n\n
Native install one-liners<\/h2>\n\n\n\n
OS<\/th>Install<\/th><\/tr><\/thead>
Ubuntu \/ Debian<\/td>wget https:\/\/github.com\/qdrant\/qdrant\/releases\/download\/${QDRANT_VERSION}\/qdrant_${QDRANT_VERSION#v}_amd64.deb && sudo apt install .\/qdrant_*_amd64.deb<\/code><\/td><\/tr>
Rocky \/ RHEL<\/td>Use the Docker or Podman path. Native RPM is not officially published; build from source with cargo if you really need it.<\/td><\/tr>
Build from source<\/td>cargo install --git https:\/\/github.com\/qdrant\/qdrant --tag ${QDRANT_VERSION}<\/code> (requires Rust toolchain and protoc)<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
systemd service for a native install<\/h2>\n\n\n\n
Drop this unit file at \/etc\/qdrant\/qdrant.service<\/code> for a native (non-Docker) install:<\/p>\n\n\n\n
# \/etc\/systemd\/system\/qdrant.service\n[Unit]\nDescription=Qdrant Vector Database\nAfter=network.target\n\n[Service]\nType=simple\nUser=qdrant\nGroup=qdrant\nExecStart=\/usr\/bin\/qdrant --config-path \/etc\/qdrant\/config.yaml\nRestart=on-failure\nRestartSec=5\nLimitNOFILE=65536\n\n[Install]\nWantedBy=multi-user.target<\/code><\/pre>\n\n\n\n
Create the user, the storage directories, and enable the unit:<\/p>\n\n\n\n
sudo useradd -r -s \/sbin\/nologin qdrant\nsudo mkdir -p \/var\/lib\/qdrant\/storage \/etc\/qdrant\nsudo chown -R qdrant:qdrant \/var\/lib\/qdrant\nsudo systemctl daemon-reload\nsudo systemctl enable --now qdrant\nsudo systemctl status qdrant<\/code><\/pre>\n\n\n\n
Health and readiness<\/h2>\n\n\n\n
Three endpoints cover liveness, readiness, and version reporting:<\/p>\n\n\n\n
# Liveness\ncurl -s http:\/\/localhost:6333\/healthz\n\n# Readiness (returns 200 only when collections are loaded)\ncurl -s http:\/\/localhost:6333\/readyz\n\n# Telemetry \/ version\ncurl -s http:\/\/localhost:6333\/telemetry | jq '.app.version'<\/code><\/pre>\n\n\n\n
Collections: create, list, delete<\/h2>\n\n\n\n
Collections are the top level container. Create, list, inspect, and delete with these calls:<\/p>\n\n\n\n
# Create a collection (768-dim, cosine distance)\ncurl -X PUT http:\/\/localhost:6333\/collections\/articles \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"vectors\": {\n      \"size\": 768,\n      \"distance\": \"Cosine\"\n    }\n  }'\n\n# List\ncurl -s http:\/\/localhost:6333\/collections -H \"api-key: $QDRANT_API_KEY\"\n\n# Get config and stats\ncurl -s http:\/\/localhost:6333\/collections\/articles -H \"api-key: $QDRANT_API_KEY\"\n\n# Delete\ncurl -X DELETE http:\/\/localhost:6333\/collections\/articles -H \"api-key: $QDRANT_API_KEY\"<\/code><\/pre>\n\n\n\n
Collection with named vectors (dense + sparse for hybrid search):<\/p>\n\n\n\n
curl -X PUT http:\/\/localhost:6333\/collections\/articles \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"vectors\": {\n      \"dense\": {\"size\": 768, \"distance\": \"Cosine\"}\n    },\n    \"sparse_vectors\": {\n      \"bm25\": {}\n    }\n  }'<\/code><\/pre>\n\n\n\n
Points: upsert, get, delete, scroll<\/h2>\n\n\n\n
Upserts, deletes, scroll, and count all live under the collection's points path:<\/p>\n\n\n\n
# Upsert with payload\ncurl -X PUT http:\/\/localhost:6333\/collections\/articles\/points \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"points\": [\n      {\n        \"id\": 1,\n        \"vector\": [0.1, 0.2, 0.3, \"...\"],\n        \"payload\": {\"title\": \"Qdrant Guide\", \"tags\": [\"ai\", \"vector\"]}\n      }\n    ]\n  }'\n\n# Get by ID\ncurl -s http:\/\/localhost:6333\/collections\/articles\/points\/1 -H \"api-key: $QDRANT_API_KEY\"\n\n# Delete by ID\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/delete \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"points\": [1, 2, 3]}'\n\n# Scroll (paginate through all points)\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/scroll \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"limit\": 100, \"with_payload\": true, \"with_vector\": false}'\n\n# Count\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/count \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"exact\": true}'<\/code><\/pre>\n\n\n\n
Search and the modern query API<\/h2>\n\n\n\n
The legacy \/search<\/code> endpoint still works, but new code should use \/query<\/code> which adds prefetch, hybrid retrieval, and rescoring:<\/p>\n\n\n\n
# Basic search\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/search \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"vector\": [0.1, 0.2, 0.3, \"...\"],\n    \"limit\": 10,\n    \"with_payload\": true\n  }'\n\n# Modern query_points (v1.10+) with prefetch + filter\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/query \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"query\": [0.1, 0.2, 0.3, \"...\"],\n    \"limit\": 10,\n    \"filter\": {\n      \"must\": [{\"key\": \"tags\", \"match\": {\"value\": \"ai\"}}]\n    }\n  }'\n\n# Recommend (positives and negatives)\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/points\/recommend \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"positive\": [1, 5],\n    \"negative\": [99],\n    \"limit\": 10\n  }'<\/code><\/pre>\n\n\n\n
Filter syntax cheat card<\/h2>\n\n\n\n
Clause<\/th>Example<\/th><\/tr><\/thead>
match<\/code><\/td>{\"key\":\"category\",\"match\":{\"value\":\"books\"}}<\/code><\/td><\/tr>
match any<\/code><\/td>{\"key\":\"tag\",\"match\":{\"any\":[\"ai\",\"ml\"]}}<\/code><\/td><\/tr>
range<\/code><\/td>{\"key\":\"price\",\"range\":{\"gte\":10,\"lt\":100}}<\/code><\/td><\/tr>
geo_bounding_box<\/code><\/td>{\"key\":\"loc\",\"geo_bounding_box\":{\"top_left\":{...},\"bottom_right\":{...}}}<\/code><\/td><\/tr>
geo_radius<\/code><\/td>{\"key\":\"loc\",\"geo_radius\":{\"center\":{...},\"radius\":5000}}<\/code><\/td><\/tr>
full text<\/code><\/td>{\"key\":\"body\",\"match\":{\"text\":\"vector search\"}}<\/code><\/td><\/tr>
is_null<\/code><\/td>{\"is_null\":{\"key\":\"deleted_at\"}}<\/code><\/td><\/tr>
nested<\/code><\/td>{\"key\":\"meta.tags[]\",\"match\":{\"value\":\"ai\"}}<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Compose with must<\/code>, should<\/code>, and must_not<\/code>. Always pair high cardinality keyword fields with a payload index for fast filtered search.<\/p>\n\n\n\n
# Create a payload index (one-time, per field)\ncurl -X PUT http:\/\/localhost:6333\/collections\/articles\/index \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"field_name\": \"tags\", \"field_schema\": \"keyword\"}'<\/code><\/pre>\n\n\n\n
Snapshots: create, list, restore<\/h2>\n\n\n\n
Snapshots are the simplest backup path. The same endpoints handle create, list, download, and restore:<\/p>\n\n\n\n
# Create a collection snapshot\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/snapshots \\\n  -H \"api-key: $QDRANT_API_KEY\"\n\n# List\ncurl -s http:\/\/localhost:6333\/collections\/articles\/snapshots -H \"api-key: $QDRANT_API_KEY\"\n\n# Download\ncurl -OJ http:\/\/localhost:6333\/collections\/articles\/snapshots\/<snapshot-name> \\\n  -H \"api-key: $QDRANT_API_KEY\"\n\n# Restore from URL\ncurl -X PUT http:\/\/localhost:6333\/collections\/articles\/snapshots\/recover \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\"location\": \"http:\/\/backups.example.com\/articles.snapshot\"}'\n\n# Restore from upload (multipart)\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/snapshots\/upload \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -F \"snapshot=@articles.snapshot\"\n\n# Full storage snapshot (single node only)\ncurl -X POST http:\/\/localhost:6333\/snapshots -H \"api-key: $QDRANT_API_KEY\"<\/code><\/pre>\n\n\n\n
S3 snapshot backend (since v1.10), configured in config.yaml<\/code>:<\/p>\n\n\n\n
storage:\n  snapshots_config:\n    snapshots_storage: s3\n    s3_config:\n      bucket: my-qdrant-snapshots\n      region: eu-central-1\n      access_key: AKIA...\n      secret_key: ...\n      endpoint_url: https:\/\/s3.eu-central-1.amazonaws.com<\/code><\/pre>\n\n\n\n
Cluster operations<\/h2>\n\n\n\n
Cluster mode adds raft consensus, sharding, and replication. Enable it in config.yaml<\/code>:<\/p>\n\n\n\n
# Enable cluster mode in config.yaml\ncluster:\n  enabled: true\n  p2p:\n    port: 6335\n  consensus:\n    tick_period_ms: 100<\/code><\/pre>\n\n\n\n
Bootstrap the first node, then join the rest with the --bootstrap<\/code> flag pointing at any existing peer:<\/p>\n\n\n\n
# Bootstrap node 1 (first in the cluster)\nqdrant --config-path \/etc\/qdrant\/config.yaml --uri http:\/\/node1:6335\n\n# Join nodes 2 and 3\nqdrant --config-path \/etc\/qdrant\/config.yaml \\\n  --bootstrap http:\/\/node1:6335 \\\n  --uri http:\/\/node2:6335\n\n# Cluster status\ncurl -s http:\/\/localhost:6333\/cluster -H \"api-key: $QDRANT_API_KEY\"\n\n# Create collection with sharding and replication\ncurl -X PUT http:\/\/localhost:6333\/collections\/articles \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"vectors\": {\"size\": 768, \"distance\": \"Cosine\"},\n    \"shard_number\": 6,\n    \"replication_factor\": 2,\n    \"write_consistency_factor\": 1\n  }'\n\n# Move a shard between peers\ncurl -X POST http:\/\/localhost:6333\/collections\/articles\/cluster \\\n  -H \"api-key: $QDRANT_API_KEY\" \\\n  -H \"Content-Type: application\/json\" \\\n  -d '{\n    \"move_shard\": {\n      \"shard_id\": 0,\n      \"from_peer_id\": 1,\n      \"to_peer_id\": 3\n    }\n  }'<\/code><\/pre>\n\n\n\n
Helm one-liners<\/h2>\n\n\n\n
The official Helm chart wraps a StatefulSet plus a PVC per pod. Add the repo and install with the right flags for your topology:<\/p>\n\n\n\n
helm repo add qdrant https:\/\/qdrant.github.io\/qdrant-helm\nhelm repo update\n\n# Single node\nhelm install qdrant qdrant\/qdrant \\\n  --namespace qdrant --create-namespace \\\n  --set apiKey=$(openssl rand -base64 32)\n\n# 3 node cluster with persistence\nhelm install qdrant qdrant\/qdrant \\\n  --namespace qdrant --create-namespace \\\n  --set replicaCount=3 \\\n  --set config.cluster.enabled=true \\\n  --set persistence.size=50Gi \\\n  --set apiKey=$(openssl rand -base64 32)\n\n# Upgrade\nhelm upgrade qdrant qdrant\/qdrant -n qdrant -f values.yaml<\/code><\/pre>\n\n\n\n
Python client one-page<\/h2>\n\n\n\n
The qdrant-client<\/code> Python package mirrors the REST API one-to-one. A working starter:<\/p>\n\n\n\n
from qdrant_client import QdrantClient\nfrom qdrant_client.models import (\n    Distance, VectorParams, PointStruct,\n    Filter, FieldCondition, MatchValue, Range,\n)\n\nclient = QdrantClient(url=\"http:\/\/localhost:6333\", api_key=\"...\")\n\n# Create\nclient.create_collection(\n    collection_name=\"articles\",\n    vectors_config=VectorParams(size=768, distance=Distance.COSINE),\n)\n\n# Upsert\nclient.upsert(\n    collection_name=\"articles\",\n    points=[\n        PointStruct(id=1, vector=[0.1] * 768, payload={\"title\": \"Qdrant Guide\"}),\n    ],\n)\n\n# Search with filter\nhits = client.query_points(\n    collection_name=\"articles\",\n    query=[0.1] * 768,\n    query_filter=Filter(\n        must=[FieldCondition(key=\"title\", match=MatchValue(value=\"Qdrant Guide\"))]\n    ),\n    limit=10,\n    with_payload=True,\n).points\n\n# Create payload index\nclient.create_payload_index(\n    collection_name=\"articles\",\n    field_name=\"title\",\n    field_schema=\"keyword\",\n)\n\n# Snapshot\nclient.create_snapshot(collection_name=\"articles\")<\/code><\/pre>\n\n\n\n
Configuration env var pattern<\/h2>\n\n\n\n
Every key in config.yaml<\/code> can be overridden by an environment variable using QDRANT__SECTION__KEY<\/code>. Two underscores separate levels.<\/p>\n\n\n\n
Env var<\/th>Effect<\/th><\/tr><\/thead>
QDRANT__SERVICE__API_KEY<\/code><\/td>Static API key for all requests<\/td><\/tr>
QDRANT__SERVICE__JWT_RBAC<\/code><\/td>Enable JWT based RBAC (also needs API key)<\/td><\/tr>
QDRANT__SERVICE__HTTP_PORT<\/code><\/td>REST port (default 6333)<\/td><\/tr>
QDRANT__SERVICE__GRPC_PORT<\/code><\/td>gRPC port (default 6334)<\/td><\/tr>
QDRANT__SERVICE__ENABLE_TLS<\/code><\/td>Built in TLS (with tls.cert<\/code> + tls.key<\/code>)<\/td><\/tr>
QDRANT__STORAGE__STORAGE_PATH<\/code><\/td>Storage root (default .\/storage<\/code>)<\/td><\/tr>
QDRANT__STORAGE__SNAPSHOTS_PATH<\/code><\/td>Snapshots root (default .\/snapshots<\/code>)<\/td><\/tr>
QDRANT__LOG_LEVEL<\/code><\/td>debug<\/code>, info<\/code>, warn<\/code>, error<\/code><\/td><\/tr>
QDRANT__CLUSTER__ENABLED<\/code><\/td>Turn on cluster mode<\/td><\/tr>
QDRANT__TELEMETRY_DISABLED<\/code><\/td>Disable anonymous telemetry<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Web UI URLs<\/h2>\n\n\n\n
URL<\/th>What it shows<\/th><\/tr><\/thead>
\/dashboard<\/code><\/td>Main UI<\/td><\/tr>
\/dashboard#\/welcome<\/code><\/td>First time welcome page<\/td><\/tr>
\/dashboard#\/collections<\/code><\/td>Collections list<\/td><\/tr>
\/dashboard#\/console<\/code><\/td>Browser REST runner<\/td><\/tr>
\/dashboard#\/tutorial<\/code><\/td>Interactive tutorial<\/td><\/tr>
\/dashboard#\/datasets<\/code><\/td>Bundled sample datasets<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Common gotchas<\/h2>\n\n\n\n