home / skills / vm0-ai / vm0-skills / qdrant

qdrant skill

safe

This skill helps you store, search, and manage vector embeddings with Qdrant REST API for efficient RAG and semantic search.

npx playbooks add skill vm0-ai/vm0-skills --skill qdrant

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

7.1 KB

---
name: qdrant
description: Qdrant vector database REST API via curl. Use this skill to store, search, and manage vector embeddings.
vm0_secrets:
  - QDRANT_API_KEY
vm0_vars:
  - QDRANT_URL
---

# Qdrant API

Use the Qdrant REST API via direct `curl` calls to **store and search vector embeddings** for RAG, semantic search, and recommendations.

> Official docs: `https://qdrant.tech/documentation/`

---

## When to Use

Use this skill when you need to:

- **Store vector embeddings** for semantic search
- **Search for similar vectors** using cosine, dot product, or euclidean distance
- **Build RAG applications** with retrieval from vector store
- **Implement recommendations** based on similarity
- **Filter search results** by metadata/payload

---

## Prerequisites

### Option 1: Qdrant Cloud (Recommended)

1. Sign up at [Qdrant Cloud](https://cloud.qdrant.io/)
2. Create a cluster and get your URL and API key
3. Store credentials in environment variables

```bash
export QDRANT_URL="https://xyz-example.aws.cloud.qdrant.io:6333"
export QDRANT_API_KEY="your-api-key"
```

### Option 2: Self-hosted

Run Qdrant locally with Docker:

```bash
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
```

```bash
export QDRANT_URL="http://localhost:6333"
export QDRANT_API_KEY="" # Optional for local
```

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

## How to Use

All examples below assume you have `QDRANT_URL` and `QDRANT_API_KEY` set.

---

### 1. Check Server Status

Verify connection to Qdrant:

```bash
bash -c 'curl -s -X GET "${QDRANT_URL}" --header "api-key: ${QDRANT_API_KEY}"'
```

---

### 2. List Collections

Get all collections:

```bash
bash -c 'curl -s -X GET "${QDRANT_URL}/collections" --header "api-key: ${QDRANT_API_KEY}"'
```

---

### 3. Create a Collection

Create a collection for storing vectors:

Write to `/tmp/qdrant_request.json`:

```json
{
  "vectors": {
    "size": 1536,
    "distance": "Cosine"
  }
}
```

Then run:

```bash
bash -c 'curl -s -X PUT "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

**Distance metrics:**
- `Cosine` - Cosine similarity (recommended for normalized vectors)
- `Dot` - Dot product
- `Euclid` - Euclidean distance
- `Manhattan` - Manhattan distance

**Common vector sizes:**
- OpenAI `text-embedding-3-small`: 1536
- OpenAI `text-embedding-3-large`: 3072
- Cohere: 1024

---

### 4. Get Collection Info

Get details about a collection:

```bash
bash -c 'curl -s -X GET "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}"'
```

---

### 5. Upsert Points (Insert/Update Vectors)

Add vectors with payload (metadata):

Write to `/tmp/qdrant_request.json`:

```json
{
  "points": [
    {
      "id": 1,
      "vector": [0.05, 0.61, 0.76, 0.74],
      "payload": {"text": "Hello world", "source": "doc1"}
    },
    {
      "id": 2,
      "vector": [0.19, 0.81, 0.75, 0.11],
      "payload": {"text": "Goodbye world", "source": "doc2"}
    }
  ]
}
```

Then run:

```bash
bash -c 'curl -s -X PUT "${QDRANT_URL}/collections/my_collection/points" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

---

### 6. Search Similar Vectors

Find vectors similar to a query vector:

Write to `/tmp/qdrant_request.json`:

```json
{
  "query": [0.05, 0.61, 0.76, 0.74],
  "limit": 5,
  "with_payload": true
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/query" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

**Response:**
```json
{
  "result": {
  "points": [
  {"id": 1, "score": 0.99, "payload": {"text": "Hello world"}}
  ]
  }
}
```

---

### 7. Search with Filters

Filter results by payload fields:

Write to `/tmp/qdrant_request.json`:

```json
{
  "query": [0.05, 0.61, 0.76, 0.74],
  "limit": 5,
  "filter": {
    "must": [
      {"key": "source", "match": {"value": "doc1"}}
    ]
  },
  "with_payload": true
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/query" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

**Filter operators:**
- `must` - All conditions must match (AND)
- `should` - At least one must match (OR)
- `must_not` - None should match (NOT)

---

### 8. Get Points by ID

Retrieve specific points:

Write to `/tmp/qdrant_request.json`:

```json
{
  "ids": [1, 2],
  "with_payload": true,
  "with_vector": true
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

---

### 9. Delete Points

Delete by IDs:

Write to `/tmp/qdrant_request.json`:

```json
{
  "points": [1, 2]
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/delete" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

Delete by filter:

Write to `/tmp/qdrant_request.json`:

```json
{
  "filter": {
    "must": [
      {"key": "source", "match": {"value": "doc1"}}
    ]
  }
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/delete" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

---

### 10. Delete Collection

Remove a collection entirely:

```bash
bash -c 'curl -s -X DELETE "${QDRANT_URL}/collections/my_collection" --header "api-key: ${QDRANT_API_KEY}"'
```

---

### 11. Count Points

Get total count or filtered count:

Write to `/tmp/qdrant_request.json`:

```json
{
  "exact": true
}
```

Then run:

```bash
bash -c 'curl -s -X POST "${QDRANT_URL}/collections/my_collection/points/count" --header "api-key: ${QDRANT_API_KEY}" --header "Content-Type: application/json" -d @/tmp/qdrant_request.json'
```

---

## Filter Syntax

Common filter conditions:

```json
{
  "filter": {
  "must": [
  {"key": "city", "match": {"value": "London"}},
  {"key": "price", "range": {"gte": 100, "lte": 500}},
  {"key": "tags", "match": {"any": ["electronics", "sale"]}}
  ]
  }
}
```

**Match types:**
- `match.value` - Exact match
- `match.any` - Match any in list
- `match.except` - Match none in list
- `range` - Numeric range (gt, gte, lt, lte)

---

## Guidelines

1. **Match vector size**: Collection vector size must match your embedding model output
2. **Use Cosine for normalized vectors**: Most embedding models output normalized vectors
3. **Add payload for filtering**: Store metadata with vectors for filtered searches
4. **Batch upserts**: Insert multiple points in one request for efficiency
5. **Use score_threshold**: Filter out low-similarity results in search

Overview

This skill provides direct curl-based access to the Qdrant vector database REST API to store, search, and manage vector embeddings. It focuses on practical commands for creating collections, upserting vectors with payload, performing similarity searches, applying filters, and managing lifecycle operations. Use it when you want a lightweight, shell-friendly way to integrate a vector store into retrieval-augmented generation (RAG), semantic search, or recommendation workflows. Examples assume QDRANT_URL and QDRANT_API_KEY are set in the environment.

How this skill works

The skill issues curl requests against Qdrant endpoints to perform collection management, point upserts, queries, deletes, and counts. It uses JSON request files for payloads and supports distance metrics (Cosine, Dot, Euclid, Manhattan), filters by payload, and options to return vectors and metadata. Commands are wrapped with bash -c to preserve environment variables when piping. Basic responses include matching point IDs, scores, and payload fields.

When to use it

Store embedding vectors and metadata for semantic retrieval or analytics.
Search for nearest neighbors using cosine, dot product, or euclidean distance.
Build RAG systems that retrieve documents or passages by vector similarity.
Implement content- or user-based recommendations via vector similarity.
Apply payload filters to restrict search results by metadata.

Best practices

Match the collection vector size to your embedding model output (e.g., 1536 for many OpenAI embeddings).
Use Cosine distance for normalized embeddings; choose Dot or Euclid when appropriate.
Include useful payload fields (text, source, tags) to enable filtered searches and retrieval context.
Batch upserts to reduce request overhead and improve ingestion throughput.
Use score_threshold or limit on queries to exclude low-similarity results.

Example use cases

Create a collection and upsert document embeddings with text and source payload for a RAG pipeline.
Run a similarity query to find top-5 nearest passages for a user query vector.
Filter search results to a specific document source or tag for targeted retrieval.
Delete stale vectors by ID or by filter when documents are removed or updated.
Count points in a collection or count only those matching a filter (e.g., by source or tag).

FAQ

Do I need a Qdrant Cloud account?

No — you can use Qdrant Cloud with a URL and API key or self-host Qdrant locally (e.g., Docker). Local instances may not require an API key.

How do I choose a distance metric?

Use Cosine for normalized vectors (common for modern embeddings). Use Dot for unnormalized similarity or Euclid/Manhattan for spatial distance depending on your model and use case.