Getting Started with Qdrant

This section documents the current Qdrant 1.x line (latest 1.19.1), written and verified against the official Qdrant documentation. No specific patch version is pinned. Some capabilities (Qdrant Cloud-only features and the full breadth of client-library APIs beyond Python and Java) are linked, not documented in depth.

This content was generated with the assistance of AI and should be verified against the official documentation before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

Qdrant is an open-source vector similarity search engine, written in Rust. It stores high-dimensional vectors alongside arbitrary JSON payloads and answers nearest-neighbor queries — "find the points closest to this one" — rather than the exact-match and range queries a relational or document database is built around. This page covers how to run it, its two APIs, its official clients, and a first end-to-end walkthrough.

Running Qdrant

The fastest way to get a server running locally is the official Docker image, which exposes both of Qdrant’s APIs and persists data to a mounted volume:

docker run -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  qdrant/qdrant:latest

That single command is enough to follow the walkthrough below (its flags are explained in Running Containers). For every other way to install and run Qdrant — a plain binary, a Helm chart for Kubernetes, or building from source — see Installation in the official documentation, and Quickstart for the equivalent first steps taken there.

For a managed option with no server to operate, Qdrant Cloud runs the same engine as a hosted service: you create a cluster through the web console or its API, choose a region and size, and get back a URL and an API key instead of a container to maintain. It adds horizontal scaling, backups, and monitoring on top of the same REST/gRPC surface described below, so everything in this reference applies unchanged once a cluster is provisioned.

The REST and gRPC APIs

Qdrant exposes every operation through two wire protocols, both covered end to end in Interfaces:

  • REST, on port 6333 by default — a JSON-over-HTTP API, with its own interactive OpenAPI/Swagger UI at ui.qdrant.tech, plus a separate Web UI (a collection browser and query console) served at http://localhost:6333/dashboard. The REST API is the simplest way to script against Qdrant with nothing but curl, as the walkthrough below shows.

  • gRPC, on port 6334 by default — a binary protocol built from the same schema as the REST API, used by the official clients internally for lower latency and lower overhead on high-throughput workloads.

Both ports are already published by the docker run command above, so either API is reachable as soon as the container is up.

Official clients

Qdrant maintains client libraries for several languages; the two most relevant here are:

  • Python — the qdrant-client package, installed with pip install qdrant-client. It wraps both the REST and gRPC APIs behind one Python interface and is the client used in the walkthrough below.

  • Java/Kotlin — the io.qdrant:client artifact, published on Maven Central:

    <dependency>
  <groupId>io.qdrant</groupId>
  <artifactId>client</artifactId>
  <version>1.14.1</version>
</dependency>

    It talks to Qdrant over gRPC and exposes the same collection, point, and search operations used from Python and curl in this reference.

Walkthrough: a first collection, a few points, and a search

This section creates a collection, inserts ("upserts") a handful of points, and searches them — once as raw REST calls, once with qdrant-client. The example uses toy 4-dimensional vectors so it fits on the page; a real embedding model typically produces vectors hundreds or thousands of dimensions wide, but the API calls are identical either way.

Create a collection

A collection fixes the size and distance metric every point in it will use:

curl -X PUT 'http://localhost:6333/collections/demo' \
  -H 'Content-Type: application/json' \
  -d '{
    "vectors": {
      "size": 4,
      "distance": "Cosine"
    }
  }'
from qdrant_client import QdrantClient
from qdrant_client.models import Distance, VectorParams

client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="demo",
    vectors_config=VectorParams(size=4, distance=Distance.COSINE),
)

Upsert a few points

Each point carries an ID, a vector, and an optional JSON payload:

curl -X PUT 'http://localhost:6333/collections/demo/points' \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      { "id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": { "city": "Berlin" } },
      { "id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": { "city": "London" } },
      { "id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": { "city": "Moscow" } }
    ]
  }'
from qdrant_client.models import PointStruct

client.upsert(
    collection_name="demo",
    points=[
        PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
        PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": "London"}),
        PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": "Moscow"}),
    ],
)

Search

A search takes a query vector and returns the closest points, ranked by the collection’s distance metric:

curl -X POST 'http://localhost:6333/collections/demo/points/query' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": [0.2, 0.1, 0.9, 0.7],
    "limit": 2
  }'
results = client.query_points(
    collection_name="demo",
    query=[0.2, 0.1, 0.9, 0.7],
    limit=2,
).points

for hit in results:
    print(hit.id, hit.score, hit.payload)

Both calls return the same two nearest points, each with its similarity score and payload — the search result a real application would rank recommendations or retrieved documents by.

Where to go next