Creating a Qdrant data service

Qdrant is a vector database. It stores embeddings and their payloads and exposes an HTTP API for similarity search, filtering and collection management. This tutorial shows you how to create an Ametnes-managed Qdrant service and connect to it over HTTPS with an API key.

Vector search suits semantic search and retrieval-augmented generation (RAG) over private data.

Ametnes currently offers one release series, service/qdrant:1.18 (Qdrant v1.18.2). Starter is a single node; Small and above are three-node distributed clusters. Tiers differ by CPU, memory, per-node storage and ACU.

Prerequisites

1. A service location (see Service Location).

Networking is automatic by default

Creating a network access resource is optional. If you do not create one, Ametnes manages network access for the location and the service attaches automatically. Create your own only if you want to control exposure (see Network Access Resources).

Connections

Qdrant publishes one HTTPS connection:

Connection	Default port	Purpose
https	443	Qdrant HTTP API and dashboard

The host is the service's DNS name on your zone. Use port 443 and HTTPS; the endpoint publishes only the Qdrant HTTP API. On Small and above the endpoint serves the whole three-node cluster.

The API key is sent in the api-key header. Qdrant does not ship a default key: the value you set at create time is the only key for the service.

Create the Qdrant service

ConsoleTerraform

1. Navigate to the Services left menu and click New Service.
2. Enter Name (for example QdrantService).
3. Select Kind: Qdrant Service (service/qdrant:1.18).
4. Select the Location: your data service location. Leave Network unset to let Ametnes manage it.
5. Select the Setup Architecture: Starter for evaluation, Small and above for production.
6. Enter the API Key. The field is required and no key is generated for you.
7. Leave Public unset for a private endpoint, or enable it to make the endpoint reachable from the internet.
8. Click Create Service and wait for the status ready.

resource "ametnes_service" "qdrant" {
  name     = "QdrantService"
  project  = data.ametnes_project.project.id
  location = data.ametnes_location.location.id
  kind     = "qdrant:1.18"
  capacity {
    storage = 10
  }
  config = {
    "architecture"   = "Starter"
    "admin.password" = "<api-key>"
  }
}

output "connections" {
  value = ametnes_service.qdrant.connections
}

Store the API key immediately

The API key is stored as a per-resource Secret and is shown at create time. Store it in a secrets manager before leaving the create screen; clients cannot retrieve it from the service later.

Connect

Use the host from the service's connection and the API key you supplied. Check that the service is healthy:

curl --request GET \
  --url "https://<host>/readyz" \
  --header "api-key: <api-key>"

List collections:

curl --request GET \
  --url "https://<host>/collections" \
  --header "api-key: <api-key>"

Open the Qdrant dashboard at https://<host>/dashboard in a browser and enter the API key when prompted.

From Python, install the client and connect over HTTPS:

pip install qdrant-client

from qdrant_client import QdrantClient

client = QdrantClient(url="https://<host>", api_key="<api-key>")
print(client.get_collections())

Create a collection and search

The following example creates a collection for 768-dimensional embeddings, inserts a point and runs a nearest-neighbour query. Replace the vectors with embeddings produced by your model provider.

from qdrant_client import QdrantClient
from qdrant_client.models import Distance, PointStruct, VectorParams

client = QdrantClient(url="https://<host>", api_key="<api-key>")

client.create_collection(
    collection_name="docs",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE),
)

client.upsert(
    collection_name="docs",
    points=[
        PointStruct(
            id=1,
            vector=[0.0] * 768,
            payload={"source": "handbook", "title": "Getting started"},
        ),
    ],
)

hits = client.query_points(
    collection_name="docs",
    query=[0.0] * 768,
    limit=5,
    with_payload=True,
).points

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

The equivalent REST calls use PUT /collections/docs to create the collection, PUT /collections/docs/points?wait=true to upsert points and POST /collections/docs/points/query to search.

On a three-node cluster, create collections with a shard count that is a multiple of three and keep replicas for availability:

client.create_collection(
    collection_name="docs",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE),
    shard_number=6,
    replication_factor=2,
)

Architectures

Starter is a single node with one data volume. Small and above are three-node distributed clusters with one data volume per node. Requests are half of the limits.

Architecture	Nodes	CPU / memory	Storage per node	ACU
Starter	1	1 CPU / 2Gi	10Gi	2
Small	3	2 CPU / 4Gi	25Gi	12
Basic	3	2 CPU / 4Gi	50Gi	12
Medium	3	4 CPU / 8Gi	100Gi	24
Large	3	8 CPU / 16Gi	250Gi	48
XLarge	3	16 CPU / 32Gi	500Gi	96
2XLarge	3	24 CPU / 64Gi	1000Gi	192
3XLarge	3	32 CPU / 96Gi	2000Gi	288
4XLarge	3	48 CPU / 128Gi	4000Gi	384

Replication is a collection setting

Small and above run three nodes, but new collections default to replication_factor: 1. Set replication_factor to 2 or 3 when creating a collection to keep copies on multiple nodes. Replication multiplies storage use, so size the per-node storage accordingly.

Scale

Use Modify Resource in the console to move to a larger architecture. Starter is a single node; Small and above are three-node clusters. Moving between Small and larger tiers keeps three nodes and resizes CPU and memory. The data volume keeps its current size unless you change the service's storage value.

Existing collections do not rebalance automatically

Existing collections are not redistributed when you move from Starter to a larger tier. Create new collections with a shard_number that fits the cluster and a replication_factor of 2 or 3, or migrate existing data by restoring snapshots into the new collections.

Validation checklist

• Qdrant resource status is ready in Ametnes Platform.
• GET https://<host>/readyz succeeds with the api-key header.
• The dashboard opens at https://<host>/dashboard and accepts the key.
• You can create a collection and query it with the Python client.

Next

• Service Location - choose where the service runs.
• Network Access Resources - control how the service is exposed.
• Resource Reference - resource kinds, capacities and connection data.