Qdrant is a vector similarity search engine and vector database. It provides a production-ready service with a convenient API to store, search, and manage points—vectors with an additional payload Qdrant is tailored to extended filtering support. It makes it useful for all sorts of neural-network or semantic-based matching, faceted search, and other applications.
While Upsun does not provide an official service image for Qdrant, the database can be configured as a standalone application in a multi-applications project. This still gives you full control over the Qdrant configuration and allows for persistent storage across deployments.
Configuration
Create a qdrant application in your .upsun/config.yaml:
The example above is using a HIGH_MEMORY container. You can refer to the Container profiles documentation for more information.
Available versions
In order to run Qdrant as a standalone application without building it from source, the configuration relies on the Composable image. Each Nix release (channel) comes with specific package versions. You can check which Qdrant version is available on a specific release on the Nix packages search.This is especially important as Qdrant client librairies must use the same minor version (x.y.*) as the server.2. Add the required Qdrant configuration
Qdrant relies on its own config.yaml configuration file in order to start instead of command-line arguments.
Add a new file named qdrant/config.yaml in your project. Note that the qdrant/ directory matches the root: "qdrant" configuration in your .upsun/config.yaml.
You can find the default configuration adapted for Upsun below:
log_level: ERROR
storage:
# Where to store all the data. This is using the mount we declared earlier.
storage_path: ./storage
# Where to store snapshots. This is using the mount we declared earlier.
snapshots_path: ./snapshots
snapshots_config:
snapshots_storage: local
temp_path: null
on_disk_payload: true
update_concurrency: null
wal:
wal_capacity_mb: 32
wal_segments_ahead: 0
node_type: "Normal"
performance:
max_search_threads: 0
optimizer_cpu_budget: 0
update_rate_limit: null
optimizers:
deleted_threshold: 0.2
vacuum_min_vector_number: 1000
default_segment_number: 0
max_segment_size_kb: null
indexing_threshold_kb: 10000
flush_interval_sec: 5
max_optimization_threads: null
hnsw_index:
m: 16
ef_construct: 100
full_scan_threshold_kb: 10000
max_indexing_threads: 0
on_disk: false
payload_m: null
shard_transfer_method: null
collection:
replication_factor: 1
write_consistency_factor: 1
vectors:
on_disk: null
quantization: null
strict_mode:
enabled: false
max_query_limit: null
max_timeout: null
unindexed_filtering_retrieve: null
unindexed_filtering_update: null
search_max_hnsw_ef: null
search_allow_exact: null
search_max_oversampling: null
max_collections: null
service:
max_request_size_mb: 32
max_workers: 0
# Host to bind the service on
host: 0.0.0.0
# HTTP(S) port to bind the service on. We are using Upsun's default 8888. It is unfortunately not possible to use an environment variable here.
http_port: 8888
grpc_port: null
enable_cors: true
enable_tls: false
verify_https_client_certificate: false
# Set an api-key.
# api_key: your_secret_api_key_here
# Set an api-key for read-only operations.
# read_only_api_key: your_secret_read_only_api_key_here
cluster:
# Use `enabled: true` to run Qdrant in distributed deployment mode
enabled: false
telemetry_disabled: true
3. Connect from your application
To connect to Qdrant from another application in your project, add a relationship in that application configuration block:
applications:
myapp:
source:
root: "myapp"
type: "python:3.12"
relationships:
qdrant: "qdrant:http"
qdrant as the relationship name, your application will have access to QDRANT environments variables.
4. Use the relationship in your application
Connect to Qdrant using the relationship configuration:
import os
from qdrant_client import QdrantClient
def get_qdrant_client():
"""Create Qdrant client based on environment variables."""
# Check for remote Qdrant configuration
qdrant_host = os.getenv("QDRANT_HOST")
qdrant_port = os.getenv("QDRANT_PORT", "6333")
qdrant_api_key = os.getenv("QDRANT_API_KEY")
if qdrant_host:
# Remote Qdrant instance
return QdrantClient(
host=qdrant_host,
port=int(qdrant_port),
api_key=qdrant_api_key
)
else:
# Local Qdrant instance (in-memory for testing)
return QdrantClient(":memory:")
import { QdrantClient } from '@qdrant/js-client-rest';
function getQdrantClient(): QdrantClient {
const qdrantHost = process.env.QDRANT_HOST;
const qdrantPort = parseInt(process.env.QDRANT_PORT || '6333');
const qdrantApiKey = process.env.QDRANT_API_KEY;
if (qdrantHost) {
return new QdrantClient({
url: `http://${qdrantHost}:${qdrantPort}`,
apiKey: qdrantApiKey
});
} else {
// For local development, connect to localhost
return new QdrantClient({
url: 'http://localhost:6333'
});
}
}
Persistent storage
The configuration includes persistent storage through mounts:
storage: Stores the main Qdrant database filessnapshots: Stores Qdrant snapshots
These mounts ensure that your vector data persists between deployments and application restarts.
Access Qdrant
Qdrant runs as an internal application without external HTTP access. Other applications in your project connect to it using the qdrant.internal hostname through relationships.
For development and debugging, you can use port forwarding to access your Qdrant instance locally:
This creates a secure tunnel to your Qdrant application, allowing you to connect local tools and clients during development.
Exposing Qdrant on the public internet
If you are willing to make the Qdrant database publicly accessible, add a new route to the application in the .upsun/config.yaml file:
routes:
"https://qdrant.{default}/":
type: upstream
upstream: "qdrant:http"
Exposing Qdrant
Be mindful that exposing Qdrant publicly can be sensitive from a security standpoint.
Exporting Data
Qdrant stores vector collections on disk inside the service container.
The recommended export method is the Qdrant Snapshot API.
- Open an SSH tunnel to your Qdrant service:
upsun tunnel:single --relationship <RELATIONSHIP_NAME>
6333.
- Create a snapshot for a specific collection:
curl -X POST "http://127.0.0.1:6333/collections/<COLLECTION_NAME>/snapshots"
<COLLECTION_NAME>-<TIMESTAMP>.snapshot).
- Download the snapshot:
curl -o <COLLECTION_NAME>.snapshot \
"http://127.0.0.1:6333/collections/<COLLECTION_NAME>/snapshots/<SNAPSHOT_NAME>"
- To list all collections and snapshot all of them:
# List collections
curl http://127.0.0.1:6333/collections
# Loop and snapshot each one
for COLLECTION in $(curl -s http://127.0.0.1:6333/collections | jq -r '.result.collections[].name'); do
curl -X POST "http://127.0.0.1:6333/collections/${COLLECTION}/snapshots"
done
.snapshot files can be restored into any Qdrant instance using the
snapshot recovery endpoint.
Other resources
