{"id":168042,"date":"2026-05-29T14:00:00","date_gmt":"2026-05-29T11:00:00","guid":{"rendered":"https:\/\/computingforgeeks.com\/?p=168042"},"modified":"2026-05-27T00:35:30","modified_gmt":"2026-05-26T21:35:30","slug":"qdrant-collections-guide","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/qdrant-collections-guide\/","title":{"rendered":"Qdrant Collections: Create, Configure, and Manage Vectors"},"content":{"rendered":"\n

A Qdrant collection is the box that holds your vectors, your payloads, and the indexes that make filtered search fast. Get the collection shape right and the rest of the application falls out of it. Get it wrong and you will pay for it twice, once in memory at runtime and again when you migrate. If you are coming from Postgres and weighing the trade-offs, our pgvector install guide<\/a> is the place to see what a single-table approach gives up.<\/p>\n\n\n\n

This guide walks every collection-level setting you actually need to know, with a working Python script for each pattern and the matching JSON view from the Qdrant Web UI. You will see how to mix dense and sparse vectors in one collection, when to flip the storage to disk, how to enable multi-tenancy without spinning up a second cluster, and how to swap a collection out from under a running app with a single atomic alias update.<\/p>\n\n\n\n

Tested May 2026 on Ubuntu 24.04.4 LTS with Qdrant 1.18.1 and qdrant-client 1.18.0. All 11 collection patterns below were created and inspected on a real Docker cluster; the Web UI screenshots are from the running server, not mock-ups.<\/em><\/p>\n\n\n\n

Anatomy of a Qdrant collection<\/h2>\n\n\n\n

A collection holds points. Each point has three parts: a unique ID, one or more vectors, and an optional payload (a JSON object). The collection itself layers on top of that with HNSW graph config, optimizer thresholds, a write-ahead log, optional quantization, and any payload indexes you create.<\/p>\n\n\n\n

The companion code for this article lives at github.com\/c4geeks\/qdrant\/tree\/main\/collections<\/a>. Spin up a local instance first with the install Qdrant on Ubuntu<\/strong>, install Qdrant on Rocky Linux<\/strong>, or install Qdrant on Debian<\/strong> guide, then follow the steps below against your own cluster.<\/p>\n\n\n\n

Install the Python client and connect to the cluster:<\/p>\n\n\n\n

python3 -m venv venv\nsource venv\/bin\/activate\npip install \"qdrant-client[fastembed]\"<\/code><\/pre>\n\n\n\n
Every script in this guide starts with the same two lines:<\/p>\n\n\n\n
from qdrant_client import QdrantClient, models\nclient = QdrantClient(url=\"http:\/\/localhost:6333\")<\/code><\/pre>\n\n\n\n
Authenticated clusters pass api_key="..."<\/code> as a second argument. For TLS, use https:\/\/<\/code> and set prefer_grpc=True<\/code> if you want the binary protocol on port 6334.<\/p>\n\n\n\n
Vector params: size and the four distance metrics<\/h2>\n\n\n\n
Every dense vector collection takes two mandatory params: size<\/code> (the dimensionality, which must match your embedding model) and distance<\/code> (how Qdrant measures similarity). The simplest case is one dense vector per point:<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"basic_docs\",\n    vectors_config=models.VectorParams(\n        size=384,\n        distance=models.Distance.COSINE,\n    ),\n)<\/code><\/pre>\n\n\n\n
The size<\/code> must match the model that produced your vectors exactly. Use 384 for all-MiniLM-L6-v2<\/code>, 768 for BGE-base<\/code>, 1536 for OpenAI text-embedding-3-small<\/code>, 3072 for text-embedding-3-large<\/code>. If the size in your collection and the size of your vectors disagree by even one, upserts fail with a clear error and the points never land.<\/p>\n\n\n\n
Qdrant supports four distance metrics. Each one suits a different family of embedding models:<\/p>\n\n\n\n
Metric<\/th>Python enum<\/th>Best for<\/th><\/tr><\/thead>
Cosine<\/td>Distance.COSINE<\/code><\/td>Sentence transformers, MiniLM, BGE, MPNet, most text embedding models<\/td><\/tr>
Dot product<\/td>Distance.DOT<\/code><\/td>Models that produce un-normalised output or when magnitude carries meaning<\/td><\/tr>
Euclidean<\/td>Distance.EUCLID<\/code><\/td>Image features (older CNN-style), geographic vectors, when scale matters<\/td><\/tr>
Manhattan<\/td>Distance.MANHATTAN<\/code><\/td>Sparse high-dimensional features, taxicab-style metrics, hashing schemes<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Cosine is the default if you do not know. If you trained or are using a model with a stated similarity metric, follow what the model card says. Switching metrics later means re-indexing every vector.<\/p>\n\n\n\n
A loop that builds one collection per metric is useful for testing:<\/p>\n\n\n\n
for dist in [models.Distance.COSINE, models.Distance.DOT,\n             models.Distance.EUCLID, models.Distance.MANHATTAN]:\n    name = f\"dist_{dist.value.lower()}\"\n    client.create_collection(\n        collection_name=name,\n        vectors_config=models.VectorParams(size=128, distance=dist),\n    )<\/code><\/pre>\n\n\n\n
Each collection is a separate index. They are isolated from one another and you cannot search across them in a single call.<\/p>\n\n\n\n
Named vectors: one collection, multiple vector spaces<\/h2>\n\n\n\n
Real production setups rarely have just one vector per item. A product needs a text embedding for the title and description, an image embedding for the photo, and possibly a sparse keyword vector. Qdrant lets you attach all three to the same point with named vectors. The collection stores them in separate indexes but keeps them lined up via the shared point ID.<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"named_vectors\",\n    vectors_config={\n        \"text\":  models.VectorParams(size=384, distance=models.Distance.COSINE),\n        \"image\": models.VectorParams(size=512, distance=models.Distance.COSINE),\n    },\n)<\/code><\/pre>\n\n\n\n
The Info tab in the Web UI shows the resulting config as a nested map of named spaces with independent size<\/code> and distance<\/code> per entry:<\/p>\n\n\n\n
\"Qdrant<\/figure>\n\n\n\n
When you upsert points, supply each vector by name:<\/p>\n\n\n\n
client.upsert(\n    collection_name=\"named_vectors\",\n    points=[\n        models.PointStruct(\n            id=1,\n            vector={\n                \"text\":  [0.1] * 384,\n                \"image\": [0.2] * 512,\n            },\n            payload={\"sku\": \"ABC-123\"},\n        ),\n    ],\n)<\/code><\/pre>\n\n\n\n
Searches specify which named vector to use via the using<\/code> param:<\/p>\n\n\n\n
client.query_points(\n    collection_name=\"named_vectors\",\n    query=[0.1] * 384,\n    using=\"text\",\n    limit=10,\n)<\/code><\/pre>\n\n\n\n
The pattern keeps memory accounting honest: storing the image vector is opt-in per query, and you can drop a named vector you no longer need without rebuilding the rest of the collection.<\/p>\n\n\n\n
Sparse vectors for keyword-style retrieval<\/h2>\n\n\n\n
Sparse vectors are the production-ready alternative to TF-IDF. Each sparse vector is a list of (index, value) pairs covering only the tokens that actually appear, which makes them very large in theory (50,000 dimensions for BERT vocab) but cheap to store in practice. Qdrant indexes them with an inverted index and can run them alongside dense vectors in the same collection.<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"sparse_demo\",\n    vectors_config={\n        \"dense\": models.VectorParams(\n            size=384, distance=models.Distance.COSINE,\n        ),\n    },\n    sparse_vectors_config={\n        \"sparse_idx\": models.SparseVectorParams(\n            index=models.SparseIndexParams(on_disk=False),\n        ),\n    },\n)<\/code><\/pre>\n\n\n\n
The Info tab reports the two vector spaces independently:<\/p>\n\n\n\n
\"Qdrant<\/figure>\n\n\n\n
Sparse upserts use a different payload shape:<\/p>\n\n\n\n
client.upsert(\n    collection_name=\"sparse_demo\",\n    points=[\n        models.PointStruct(\n            id=1,\n            vector={\n                \"dense\": [0.1] * 384,\n                \"sparse_idx\": models.SparseVector(\n                    indices=[42, 1024, 5000],\n                    values=[0.7, 0.3, 0.9],\n                ),\n            },\n            payload={\"title\": \"Rust vector database\"},\n        ),\n    ],\n)<\/code><\/pre>\n\n\n\n
Typical generators for the sparse side are SPLADE, BM25 (via fastembed's Qdrant\/bm25<\/code> model), or a custom TF-IDF pipeline. Hybrid search combines a dense and sparse result list with reciprocal rank fusion or a similar merger; filters and complex queries<\/strong> later in this series covers the full hybrid-search pattern.<\/p>\n\n\n\n
Payload schema and the seven index types<\/h2>\n\n\n\n
A payload index turns a JSON field into a B-tree (or inverted index, or geo grid) that the query planner can use to pre-filter points before running the vector search. Without it, a filter is a linear scan over the whole collection. With it, you get sub-millisecond filtered queries on 100M-point collections.<\/p>\n\n\n\n
Qdrant ships seven payload schemas. Create one index per field you plan to filter on:<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"payload_indexed\",\n    vectors_config=models.VectorParams(size=64, distance=models.Distance.COSINE),\n)\n\nschemas = {\n    \"category\":     models.PayloadSchemaType.KEYWORD,\n    \"view_count\":   models.PayloadSchemaType.INTEGER,\n    \"rating\":       models.PayloadSchemaType.FLOAT,\n    \"is_published\": models.PayloadSchemaType.BOOL,\n    \"location\":     models.PayloadSchemaType.GEO,\n    \"published_at\": models.PayloadSchemaType.DATETIME,\n}\nfor field, kind in schemas.items():\n    client.create_payload_index(\n        \"payload_indexed\", field_name=field, field_schema=kind,\n    )\n\n# Text index needs explicit tokenizer params\nclient.create_payload_index(\n    \"payload_indexed\", field_name=\"body\",\n    field_schema=models.TextIndexParams(\n        type=\"text\",\n        tokenizer=models.TokenizerType.WORD,\n        min_token_len=2, max_token_len=20, lowercase=True,\n    ),\n)<\/code><\/pre>\n\n\n\n
The Web UI Info tab confirms each index lands with its declared data type. Annotated JSON makes it easy to verify the result without writing a separate get_collection<\/code> script:<\/p>\n\n\n\n
\"Qdrant<\/figure>\n\n\n\n
Use the right schema per field. The wrong choice is silently inefficient:<\/p>\n\n\n\n
Schema<\/th>When to use<\/th>Filter type<\/th><\/tr><\/thead>
KEYWORD<\/code><\/td>Categorical strings: tags, SKUs, country codes<\/td>Exact match<\/code>, any<\/code>, except<\/code><\/td><\/tr>
INTEGER<\/code><\/td>Counts, IDs from external systems<\/td>range<\/code>, exact match<\/td><\/tr>
FLOAT<\/code><\/td>Scores, prices, decimal weights<\/td>range<\/code><\/td><\/tr>
BOOL<\/code><\/td>Toggles: is_published, is_archived<\/td>Exact match<\/td><\/tr>
GEO<\/code><\/td>Lon\/lat pairs (in that order)<\/td>geo_radius<\/code>, geo_bounding_box<\/code>, geo_polygon<\/code><\/td><\/tr>
TEXT<\/code><\/td>Full-text search on a payload string field<\/td>match_text<\/code> with tokenizer-aware terms<\/td><\/tr>
DATETIME<\/code><\/td>ISO-8601 timestamps<\/td>Time-range range<\/code><\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
With the indexes in place, filtered queries are fast and predictable. A 1000-point smoke run takes a few milliseconds for any of the seven types:<\/p>\n\n\n\n
upserted 1000 points\n\nfiltered query (category=doc AND is_published=true) returned 3 in 4.6 ms\ngeo_radius (5000 km of (0,0)) returned 3 in 2.4 ms\nfull-text match (body~='sparse') returned 5 in 2.5 ms<\/code><\/pre>\n\n\n\n
Skip the index and the same queries become full collection scans. The cost is invisible at 1000 points and brutal at 10 million.<\/p>\n\n\n\n
On-disk vectors and payload for memory savings<\/h2>\n\n\n\n
By default Qdrant keeps vectors and HNSW graphs in RAM. That gives you fast search but it caps collection size at whatever fits in physical memory. For a billion-point collection of 1536-dim OpenAI vectors you would need roughly 6 GB just for raw vectors, plus the HNSW overhead on top.<\/p>\n\n\n\n
Push it to disk with three flags:<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"on_disk_collection\",\n    vectors_config=models.VectorParams(\n        size=1536,\n        distance=models.Distance.COSINE,\n        on_disk=True,                       # vectors on disk (memory-mapped)\n    ),\n    on_disk_payload=True,                   # payload on disk\n    hnsw_config=models.HnswConfigDiff(\n        on_disk=True,                       # HNSW graph on disk\n    ),\n)<\/code><\/pre>\n\n\n\n
The Web UI Info tab shows all three flags lit at once, so a quick glance confirms every layer is mmap-backed:<\/p>\n\n\n\n
\"Qdrant<\/figure>\n\n\n\n
Each flag changes a different layer. on_disk=True<\/code> on the vector params writes the raw vectors to mmap files; the OS page cache pulls them into RAM on demand. on_disk_payload=True<\/code> keeps payloads on disk too, which matters when each point has a large blob (raw HTML, image metadata, transcripts). hnsw_config.on_disk=True<\/code> lifts the HNSW graph itself off the heap.<\/p>\n\n\n\n
You give up some search latency for the memory headroom. On the Prefix Cache sample (163k points, 384-dim) the on-disk recall path is around 30% slower than the in-memory path, which is the trade-off you accept to fit 100M points on a single 64 GB machine.<\/p>\n\n\n\n
Multi-tenancy via the tenant payload index<\/h2>\n\n\n\n
Running 1000 small tenants in 1000 separate collections is expensive. Each collection has its own HNSW graph, its own segments, its own optimizer. The recommended pattern is one collection plus a tenant-aware payload index that Qdrant uses to physically isolate each tenant's vectors at the storage layer.<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"tenants\",\n    vectors_config=models.VectorParams(\n        size=384, distance=models.Distance.COSINE,\n    ),\n)\n\nclient.create_payload_index(\n    \"tenants\", field_name=\"tenant_id\",\n    field_schema=models.KeywordIndexParams(\n        type=\"keyword\",\n        is_tenant=True,        # the key flag\n    ),\n)<\/code><\/pre>\n\n\n\n
With is_tenant=True<\/code> set, Qdrant partitions storage by the value of the indexed field. A filter that pins tenant_id<\/code> hits only the points for that tenant, and the per-tenant performance stays flat as the cluster grows other tenants alongside.<\/p>\n\n\n\n
Always include the tenant filter on every search:<\/p>\n\n\n\n
client.query_points(\n    collection_name=\"tenants\",\n    query=[0.1] * 384,\n    query_filter=models.Filter(\n        must=[\n            models.FieldCondition(\n                key=\"tenant_id\",\n                match=models.MatchValue(value=\"acme-corp\"),\n            ),\n        ],\n    ),\n    limit=10,\n)<\/code><\/pre>\n\n\n\n
Without the filter, the search ranges over every tenant's data. With it, the search is partition-aware and the latency curve flattens. JWT-signed tokens (covered in the API key and JWT security<\/strong> guide later in this series) can hardwire the tenant value into the token claims so the application code does not have to enforce it.<\/p>\n\n\n\n
Optimizer config: segments, indexing, mmap<\/h2>\n\n\n\n
The optimizer thread runs in the background, merging segments and building the HNSW index. Its defaults are tuned for general use; you tune them when you have a specific workload shape (heavy ingest, big collections, low-RAM hosts).<\/p>\n\n\n\n
client.create_collection(\n    collection_name=\"tuned\",\n    vectors_config=models.VectorParams(size=384, distance=models.Distance.COSINE),\n    optimizers_config=models.OptimizersConfigDiff(\n        default_segment_number=4,\n        indexing_threshold=20000,\n        memmap_threshold=200000,\n        max_optimization_threads=2,\n    ),\n)<\/code><\/pre>\n\n\n\n
Confirm the tune landed in the dashboard's Info tab:<\/p>\n\n\n\n
\"Qdrant<\/figure>\n\n\n\n
Each knob has a specific effect:<\/p>\n\n\n\n