How to beginner · 3 min read

How to upsert vectors to Qdrant

Q: How to upsert vectors to Qdrant

Use the official qdrant-client Python SDK to upsert vectors by connecting to your Qdrant instance, then call upsert on the collection with vector points. Each point requires an id and a vector field in the payload.

Quick answer

Use the official qdrant-client Python SDK to upsert vectors by connecting to your Qdrant instance, then call upsert on the collection with vector points. Each point requires an id and a vector field in the payload.

PREREQUISITES

Python 3.8+
Qdrant server running locally or remotely
pip install qdrant-client
Access to Qdrant API endpoint (host and port)

Setup

Install the official qdrant-client Python package and ensure your Qdrant server is running locally or remotely. Set environment variables for connection if needed.

bash

pip install qdrant-client

Step by step

This example shows how to connect to a local Qdrant instance, create a collection if it doesn't exist, and upsert vectors with IDs.

python

import os
from qdrant_client import QdrantClient
from qdrant_client.http.models import PointStruct

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

collection_name = "my_collection"

# Create collection if not exists
if collection_name not in [col.name for col in client.get_collections().collections]:
    client.recreate_collection(
        collection_name=collection_name,
        vector_size=4,  # dimension of your vectors
        distance="Cosine"
    )

# Prepare points to upsert
points = [
    PointStruct(id=1, vector=[0.1, 0.2, 0.3, 0.4]),
    PointStruct(id=2, vector=[0.5, 0.6, 0.7, 0.8])
]

# Upsert points
upsert_response = client.upsert(collection_name=collection_name, points=points)
print(f"Upserted points: {upsert_response}")

output

Upserted points: UpsertResult(upserted_count=2)

Common variations

Use QdrantClient(url="https://your-qdrant-host") for remote HTTPS connection.
Include payload metadata by adding payload={'key': 'value'} in PointStruct.
Use async client AsyncQdrantClient for asynchronous operations.

python

from qdrant_client.http.models import PointStruct

# Point with payload metadata
point_with_payload = PointStruct(
    id=3,
    vector=[0.9, 0.8, 0.7, 0.6],
    payload={"category": "example"}
)

# Upsert with payload
client.upsert(collection_name=collection_name, points=[point_with_payload])

Troubleshooting

If you get connection errors, verify Qdrant server is running and host/port are correct.
Ensure vector size matches the collection's vector dimension.
Use client.get_collections() to check existing collections and their configurations.

✅

Key Takeaways

Use the official qdrant-client Python SDK for reliable vector upserts.
Always match vector dimensions with the collection's configuration to avoid errors.
You can add metadata payloads to points for richer search capabilities.
Check your Qdrant server connection and collection existence before upserting.

Verified 2026-04

Verify ↗