Qdrant Getting Started: Setup and First Request (2026)

Getting started overview

To begin working with Qdrant, developers can choose between two primary deployment methods: Qdrant Cloud, a managed service, or a self-hosted instance using the open-source distribution. The Qdrant Cloud option provides a quicker setup for development and production workloads, offering a free tier for initial exploration Qdrant Cloud pricing details. For self-hosting, Qdrant can be deployed via Docker, Kubernetes, or directly from source on various operating systems Qdrant installation guide. Regardless of the deployment choice, the fundamental steps involve setting up an instance, obtaining necessary credentials, defining a collection, indexing vector data, and performing search queries.

This guide focuses on getting started with Qdrant Cloud for its streamlined setup, followed by a local Docker deployment as an alternative. Subsequent steps detail credential management and executing a first API request. Developers can choose from several client libraries for languages like Python, Go, Rust, and TypeScript, or interact directly with the HTTP API Qdrant HTTP API reference.

Here is a quick reference for the getting started process:

Create an account and get keys

Qdrant Cloud Account Setup

To use Qdrant Cloud, navigate to the Qdrant website and sign up for an account Qdrant Cloud sign-up. The registration process typically involves providing an email address and setting a password. Upon successful registration, you will be directed to the Qdrant Cloud Console.

Inside the console, you can create your first cluster. The free tier includes 1GB of storage, support for 10 million vectors, and 10 queries per second (QPS). When creating a cluster, you'll need to select a region and provide a name. Once the cluster is provisioned, you will be able to retrieve its URL and an API key. The API key is essential for authenticating all programmatic requests to your Qdrant cluster.

To locate your API key and cluster URL:

1. Log in to the Qdrant Cloud Console.
2. Navigate to the settings or overview section of your cluster.
3. The API key (often labeled as API Key or Service Key) and the cluster URL (e.g., https://<cluster-id>.qdrant.tech) will be displayed. Copy both securely.

The API key functions as a bearer token for HTTP requests, or it is passed directly to the client library's initialization method.

Self-Hosted Qdrant (Docker)

For a self-hosted setup, the most common and recommended approach for local development is using Docker. Ensure Docker Desktop is installed and running on your system Docker installation guide. Once Docker is ready, you can pull and run a Qdrant instance with a single command:

docker pull qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant

This command pulls the latest Qdrant Docker image and starts a container, mapping port 6333 for HTTP API access and port 6334 for gRPC. For a self-hosted instance, no API key is generated by default; authentication can be enabled and configured if required Qdrant security documentation.

The cluster URL for a local Docker instance will typically be http://localhost:6333.

Your first request

This example demonstrates how to create a collection, insert data, and perform a search using the Python client library with Qdrant Cloud. Adjust the QDRANT_HOST and QDRANT_API_KEY according to your specific Qdrant Cloud cluster details. For a local Docker instance, omit the api_key parameter and use http://localhost:6333 for the host.

Prerequisites

Install the Qdrant client for Python:

pip install qdrant-client

Python Example: Connect, Create Collection, Insert, and Search

from qdrant_client import QdrantClient, models
import os

# --- Configuration (replace with your actual values) ---
# For Qdrant Cloud:
QDRANT_HOST = os.getenv("QDRANT_HOST", "YOUR_QDRANT_CLOUD_URL") # e.g., "https://your-cluster-id.qdrant.tech"
QDRANT_API_KEY = os.getenv("QDRANT_API_KEY", "YOUR_API_KEY") # Your API key from Qdrant Cloud

# For local Docker instance:
# QDRANT_HOST = "http://localhost:6333"
# QDRANT_API_KEY = None # No API key needed for default local Docker setup

COLLECTION_NAME = "my_first_collection"
VECTOR_SIZE = 4 # Example vector size

# --- Initialize Client ---
print(f"Connecting to Qdrant at {QDRANT_HOST}...")
client = QdrantClient(host=QDRANT_HOST, api_key=QDRANT_API_KEY)

# --- Create Collection ---
print(f"Creating collection '{COLLECTION_NAME}'...")
try:
    client.recreate_collection(
        collection_name=COLLECTION_NAME,
        vectors_config=models.VectorParams(size=VECTOR_SIZE, distance=models.Distance.COSINE)
    )
    print(f"Collection '{COLLECTION_NAME}' created successfully.")
except Exception as e:
    print(f"Error creating collection: {e}")
    # If collection already exists, you might want to use client.get_collection or client.delete_collection

# --- Insert Data Points ---
print("Inserting data points...")
points = [
    models.PointStruct(id=1, vector=[0.1, 0.2, 0.3, 0.4], payload={"city": "London", "population": 8982000}),
    models.PointStruct(id=2, vector=[0.5, 0.6, 0.7, 0.8], payload={"city": "Paris", "population": 2141000}),
    models.PointStruct(id=3, vector=[0.9, 1.0, 1.1, 1.2], payload={"city": "Berlin", "population": 3769000})
]

operation_info = client.upsert(
    collection_name=COLLECTION_NAME,
    wait=True,
    points=points,
)
print(f"Data points upserted: {operation_info}")

# --- Perform a Search Query ---
print("Performing a search query...")
search_vector = [0.15, 0.25, 0.35, 0.45] # Example query vector

search_result = client.search(
    collection_name=COLLECTION_NAME,
    query_vector=search_vector,
    limit=2 # Retrieve top 2 results
)

print("Search Results:")
for hit in search_result:
    print(f"  ID: {hit.id}, Score: {hit.score}, Payload: {hit.payload}")

# --- Clean up (optional) ---
# print(f"Deleting collection '{COLLECTION_NAME}'...")
# client.delete_collection(collection_name=COLLECTION_NAME)
# print(f"Collection '{COLLECTION_NAME}' deleted.")

This script first initializes the Qdrant client using your host and API key. It then creates a new collection named my_first_collection with a specified vector size and distance metric (cosine similarity is common for semantic search). Three example data points, each with a vector and a JSON payload, are then inserted into the collection. Finally, a search query is executed using an example vector, retrieving the two most similar results. The payload associated with each point is returned in the search results, demonstrating Qdrant's ability to store and retrieve metadata alongside vectors.

Common next steps

After successfully executing your first request, consider these common next steps to further explore Qdrant's capabilities:

• Advanced Filtering: Implement filters based on payload values to refine search results. Qdrant supports complex boolean queries on structured data stored in the payload Qdrant filtering concepts.
• Indexing Strategies: Experiment with different indexing configurations, such as HNSW (Hierarchical Navigable Small World), to optimize search performance for large datasets. Understanding indexing parameters is crucial for balancing speed and recall Qdrant indexing documentation.
• Batch Operations: For larger datasets, learn how to perform batch insertions and updates efficiently. Qdrant's client libraries provide methods for bulk operations to improve ingestion throughput.
• Data Management: Explore operations like updating points, deleting points, and managing aliases for collections. Effective data lifecycle management is important for production systems.
• Integrations: Integrate Qdrant with other tools in your stack, such as embedding models (e.g., from Hugging Face or OpenAI) to generate vectors from text or images.
• Monitoring and Scaling: For Qdrant Cloud, monitor your cluster's performance and explore scaling options. For self-hosted deployments, investigate monitoring tools and strategies for horizontal scaling Qdrant distributed deployment guide.
• Security: Review Qdrant's security features, including API key management, access control, and data encryption, especially when deploying in production environments.
• Explore gRPC API: While the HTTP API is widely used, the gRPC API can offer performance benefits, particularly for high-throughput applications. Client libraries often provide gRPC interfaces Qdrant gRPC API reference.

Troubleshooting the first call

Encountering issues during your initial Qdrant setup or first API call is common. Here are some troubleshooting tips:

• Incorrect API Key or Host (Qdrant Cloud): Double-check that your QDRANT_API_KEY and QDRANT_HOST values exactly match those provided in your Qdrant Cloud Console. An incorrect character or leading/trailing space will cause authentication failures.
• Network Connectivity: Ensure your development environment has network access to the Qdrant Cloud endpoint (port 443 for HTTPS) or to localhost:6333 for a local Docker instance. Firewall rules or VPN configurations might block access.
• Docker Container Not Running: If using a local Docker instance, verify that the Qdrant container is actively running. Use docker ps in your terminal to see active containers. If it's stopped, restart it with docker start <container_id> or rerun the docker run command.
• Collection Already Exists: If you try to recreate_collection and it fails, it might be because the collection already exists. You can either delete it first (client.delete_collection(collection_name=COLLECTION_NAME)) or use client.get_collection(collection_name=COLLECTION_NAME) to check its status, or simply omit the recreate_collection call if you intend to add to an existing collection.
• Vector Dimension Mismatch: The vector_size specified when creating the collection must match the dimensionality of the vectors you insert and use for queries. A mismatch will result in an error.
• Client Library Version: Ensure you are using a compatible version of the Qdrant client library with your Qdrant instance. Refer to the Qdrant documentation for version compatibility details.
• Error Messages: Carefully read the error messages returned by the client library or the Qdrant API. They often provide specific clues about what went wrong. For HTTP API errors, common status codes include 401 Unauthorized (API key issue), 404 Not Found (incorrect URL or collection name), and 400 Bad Request (malformed request body or data).
• Logs: Check the Qdrant instance logs for more detailed error information. For Docker, use docker logs <container_id>.
• Environment Variables: If you are loading credentials from environment variables (as in the Python example), ensure they are correctly set in your shell before running the script.