{"skill":{"slug":"qdrant-advanced","displayName":"Qdrant Advanced","summary":"Advanced Qdrant vector database operations for AI agents. Semantic search, contextual document ingestion with chunking, collection management, snapshots, and...","description":"---\nname: qdrant-advanced\nversion: 1.0.0\ndescription: \"Advanced Qdrant vector database operations for AI agents. Semantic search, contextual document ingestion with chunking, collection management, snapshots, and migration tools. Production-ready scripts for the complete Qdrant lifecycle. Use when: (1) Implementing semantic search across collections, (2) Ingesting documents with intelligent chunking, (3) Managing collections programmatically, (4) Creating backups and migrations.\"\nmetadata:\n  openclaw:\n    requires:\n      bins: [\"curl\", \"python3\", \"bash\"]\n      env: [\"QDRANT_HOST\", \"QDRANT_PORT\", \"OPENAI_API_KEY\"]\n      config: []\n    user-invocable: true\n  homepage: https://github.com/yoder-bawt\n  author: yoder-bawt\n---\n\n# Qdrant Advanced\n\nProduction-ready Qdrant vector database operations for AI agents. Complete toolkit for semantic search, document ingestion, collection management, backups, and migrations.\n\n## Quick Start\n\n```bash\n# Set environment variables\nexport QDRANT_HOST=\"localhost\"\nexport QDRANT_PORT=\"6333\"\nexport OPENAI_API_KEY=\"sk-...\"\n\n# List collections\nbash manage.sh list\n\n# Create a collection\nbash manage.sh create my_collection 1536 cosine\n\n# Ingest a document\nbash ingest.sh /path/to/document.txt my_collection paragraph\n\n# Search\nbash search.sh \"my search query\" my_collection 5\n```\n\n## Scripts Overview\n\n| Script | Purpose | Key Features |\n|--------|---------|--------------|\n| `search.sh` | Semantic search | Multi-collection, filters, score thresholds |\n| `ingest.sh` | Document ingestion | Contextual chunking, batch upload, progress |\n| `manage.sh` | Collection management | Create, delete, list, info, optimize |\n| `backup.sh` | Snapshots | Full collection snapshots, restore, list |\n| `migrate.sh` | Migrations | Collection-to-collection, embedding model upgrades |\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `QDRANT_HOST` | No | `localhost` | Qdrant server hostname |\n| `QDRANT_PORT` | No | `6333` | Qdrant server port |\n| `OPENAI_API_KEY` | Yes* | - | OpenAI API key for embeddings |\n| `QDRANT_API_KEY` | No | - | Qdrant API key (if auth enabled) |\n\n*Required for ingest and search operations\n\n## Detailed Usage\n\n### Semantic Search\n\n```bash\nbash search.sh <query> <collection> [limit] [filter_json]\n```\n\n**Examples:**\n\n```bash\n# Basic search\nbash search.sh \"machine learning tutorials\" my_docs 10\n\n# With metadata filter\nbash search.sh \"deployment guide\" my_docs 5 '{\"must\": [{\"key\": \"category\", \"match\": {\"value\": \"devops\"}}]}'\n\n# Score threshold\nbash search.sh \"error handling\" my_docs 10 \"\" 0.8\n```\n\n**Output:**\n```json\n{\n  \"results\": [\n    {\n      \"id\": \"doc-001\",\n      \"score\": 0.92,\n      \"text\": \"When handling errors in production...\",\n      \"metadata\": {\"source\": \"docs/error-handling.md\"}\n    }\n  ]\n}\n```\n\n### Document Ingestion\n\n```bash\nbash ingest.sh <file_path> <collection> [chunk_strategy] [metadata_json]\n```\n\n**Chunk Strategies:**\n\n| Strategy | Description | Best For |\n|----------|-------------|----------|\n| `paragraph` | Split by paragraphs (\\n\\n) | Articles, docs |\n| `sentence` | Split by sentences | Short content |\n| `fixed` | Fixed 1000 char chunks | Code, logs |\n| `semantic` | Semantic boundaries | Long documents |\n\n**Examples:**\n\n```bash\n# Ingest with paragraph chunking\nbash ingest.sh article.md my_collection paragraph\n\n# With custom metadata\nbash ingest.sh api.md my_collection paragraph '{\"category\": \"api\", \"version\": \"2.0\"}'\n\n# Ingest multiple files\nfor f in docs/*.md; do\n    bash ingest.sh \"$f\" my_collection paragraph\ndone\n```\n\n### Collection Management\n\n```bash\nbash manage.sh <command> [args...]\n```\n\n**Commands:**\n\n| Command | Arguments | Description |\n|---------|-----------|-------------|\n| `list` | - | List all collections |\n| `create` | `name dim distance` | Create new collection |\n| `delete` | `name` | Delete collection |\n| `info` | `name` | Get collection info |\n| `optimize` | `name` | Optimize collection |\n\n**Examples:**\n\n```bash\nbash manage.sh list\nbash manage.sh create my_vectors 1536 cosine\nbash manage.sh create my_vectors 768 euclid\nbash manage.sh info my_vectors\nbash manage.sh optimize my_vectors\nbash manage.sh delete my_vectors\n```\n\n### Backup & Restore\n\n```bash\nbash backup.sh <command> [args...]\n```\n\n**Commands:**\n\n| Command | Arguments | Description |\n|---------|-----------|-------------|\n| `snapshot` | `collection [snapshot_name]` | Create snapshot |\n| `restore` | `collection snapshot_name` | Restore from snapshot |\n| `list` | `collection` | List snapshots |\n| `delete` | `collection snapshot_name` | Delete snapshot |\n\n**Examples:**\n\n```bash\n# Create snapshot\nbash backup.sh snapshot my_collection\nbash backup.sh snapshot my_collection backup_2026_02_10\n\n# List snapshots\nbash backup.sh list my_collection\n\n# Restore\nbash backup.sh restore my_collection backup_2026_02_10\n\n# Delete old snapshot\nbash backup.sh delete my_collection old_backup\n```\n\n### Migration\n\n```bash\nbash migrate.sh <source_collection> <target_collection> [options]\n```\n\n**Migration Types:**\n\n1. **Copy Collection:** Same embedding model, different name\n2. **Model Upgrade:** Upgrade to new embedding model (re-embeds)\n3. **Filter Migration:** Migrate subset with filter\n\n**Examples:**\n\n```bash\n# Simple copy\nbash migrate.sh old_collection new_collection\n\n# With model upgrade (re-embeds all content)\nbash migrate.sh old_collection new_collection --upgrade-model\n\n# Filtered migration\nbash migrate.sh old_collection new_collection --filter '{\"category\": \"public\"}'\n\n# Batch size for large collections\nbash migrate.sh old_collection new_collection --batch-size 50\n```\n\n## Chunking Deep Dive\n\nThe ingest script provides intelligent chunking to preserve context:\n\n### Paragraph Chunking\n- Splits on double newlines\n- Preserves paragraph structure\n- Adds overlap of 2 sentences between chunks\n- Best for: Articles, documentation, blogs\n\n### Sentence Chunking\n- Splits on sentence boundaries\n- Minimal overlap\n- Best for: Short content, tweets, quotes\n\n### Fixed Chunking\n- Fixed 1000 character chunks\n- 200 character overlap\n- Best for: Code files, logs, unstructured text\n\n### Semantic Chunking\n- Uses paragraph + header detection\n- Preserves document structure\n- Best for: Long documents with headers\n\n## API Reference\n\nAll scripts use Qdrant REST API:\n\n```\nGET    /collections              # List collections\nPUT    /collections/{name}       # Create collection\nDELETE /collections/{name}       # Delete collection\nGET    /collections/{name}       # Collection info\nPOST   /collections/{name}/points/search     # Search\nPUT    /collections/{name}/points           # Upsert points\nPOST   /snapshots                # Create snapshot\nGET    /collections/{name}/snapshots         # List snapshots\n```\n\nFull docs: https://qdrant.tech/documentation/\n\n## Performance Tips\n\n1. **Batch uploads:** ingest.sh automatically batches uploads (default 100)\n2. **Optimize after bulk insert:** `bash manage.sh optimize my_collection`\n3. **Use filters:** Narrow search scope with metadata filters\n4. **Set score thresholds:** Filter low-quality matches\n5. **Index metadata:** Add payload indexes for faster filtering\n\n## Troubleshooting\n\n### \"Connection refused\"\n- Check Qdrant is running: `curl http://$QDRANT_HOST:$QDRANT_PORT/healthz`\n- Verify host/port environment variables\n\n### \"Collection not found\"\n- List collections: `bash manage.sh list`\n- Check collection name spelling\n\n### \"No search results\"\n- Verify documents were ingested: `bash manage.sh info my_collection`\n- Check vector dimensions match (e.g., 1536 for text-embedding-3-small)\n- Try lowering score threshold\n\n### Embedding errors\n- Verify OPENAI_API_KEY is set\n- Check API key has quota available\n- Verify network access to OpenAI API\n\n### Snapshot fails\n- Check disk space available\n- Verify Qdrant has snapshot permissions\n- For large collections, try during low-traffic periods\n\n## Requirements\n\n- Qdrant server v1.0+\n- curl, python3, bash\n- OpenAI API key (for embeddings)\n- Network access to Qdrant and OpenAI\n\n## See Also\n\n- Qdrant Docs: https://qdrant.tech/documentation/\n- OpenAI Embeddings: https://platform.openai.com/docs/guides/embeddings\n- Vector Search Guide: https://qdrant.tech/documentation/concepts/search/\n","topics":["Database","Document"],"tags":{"embeddings":"1.0.0","latest":"1.0.0","qdrant":"1.0.0","semantic-search":"1.0.0","vector-database":"1.0.0"},"stats":{"comments":0,"downloads":1298,"installsAllTime":48,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1771434913641,"updatedAt":1779077133712},"latestVersion":{"version":"1.0.0","createdAt":1771434913641,"changelog":"Initial release of qdrant-advanced: a comprehensive toolkit for advanced Qdrant operations.\n\n- Semantic search across multiple collections with flexible filters and thresholds.\n- Intelligent document ingestion using customizable chunking strategies.\n- Scripts for end-to-end collection management: create, list, info, optimize, and delete.\n- Integrated snapshot tools for backup and restore.\n- Migration utilities supporting collection copy, model upgrades, and filtered migrations.\n- Production-ready Bash & Python scripts designed for real-world AI agent workflows.","license":null},"metadata":{"setup":[{"key":"QDRANT_HOST","required":true},{"key":"QDRANT_PORT","required":true},{"key":"OPENAI_API_KEY","required":true}],"os":null,"systems":null},"owner":{"handle":"yoder-bawt","userId":"s170re0cxhj45s27ah5h37tc59885epn","displayName":"yoder-bawt","image":"https://avatars.githubusercontent.com/u/259239279?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779922427856}}