Qdrant Vector Database Tools
Relevant source files
The following files were used as context for generating this wiki page:
KamehaDB provides a comprehensive suite of tools for interacting with Qdrant, a high-performance vector database. This module enables users to connect to Qdrant instances, browse collections, manage points and payloads, perform semantic and similarity searches, and visualize high-dimensional embeddings through 3D projections. The integration is divided between a React-based desktop frontend and a Node.js sidecar that manages the underlying Qdrant client connections.
The tools are designed to facilitate vector operations within the KamehaDB ecosystem, allowing for seamless transitions between structured data browsing and vector-based analysis. Key capabilities include collection statistics tracking, advanced payload filtering, and interactive vector mapping.
Sources: README.md, CHANGELOG.md, apps/desktop/src/components/qdrant-view.tsx
Architecture and Data Flow
The Qdrant integration follows the project's standard architecture: the desktop frontend communicates with a Hono-based sidecar server, which utilizes the @qdrant/js-client-rest library to perform operations against the Qdrant database.
System Interaction Flow
The following diagram illustrates the flow of a vector search request from the user interface through the sidecar to the Qdrant instance:
Core Components
Qdrant Adapter
The QdrantAdapter is the backend contract responsible for abstracting Qdrant-specific operations. It handles connection testing, collection listing, point scrolling, searching, and recommendation.
| Feature | Description |
|---|---|
| Named Vector Support | Supports collections with multiple named vectors by using the using parameter in search and recommendation requests. |
| Point Scrolling | Implements a cursor-based pagination system using opaque offsets provided by Qdrant. |
| Similarity Recommendation | Finds points similar to a specific pointId using Qdrant's recommendation API. |
Sources: apps/sidecar/src/adapters/qdrant.ts:18-20, packages/shared/src/index.ts:397-405
Data Models
KamehaDB uses standardized types to represent Qdrant entities across the frontend and backend.
export type QdrantPoint = {
id: string | number;
payload?: Record<string, unknown>;
vector?: number[] | Record<string, number[]>;
};
export type QdrantStats = {
name: string;
status: string;
pointsCount: number;
vectorsCount?: number;
indexedVectorsCount?: number;
segmentsCount?: number;
vectorSize?: number;
distance?: string;
};
Sources: packages/shared/src/index.ts:347-351, packages/shared/src/index.ts:385-394
Search Capabilities
The QdrantQuery component provides three distinct search modes to accommodate different use cases:
- Text Search: Uses a local hash-based embedding (simple constant-dimension projection) to convert strings into vectors for semantic search without requiring an external AI provider.
- Find Similar: Utilizes the recommendation engine to find points near a specific existing Point ID.
- Advanced (Raw): Allows users to input raw JSON vector arrays (e.g.,
[0.1, 0.2, 0.3]) for precise querying.
Sources: apps/desktop/src/components/qdrant-query.tsx:32-36, apps/desktop/src/components/qdrant-query.tsx:94-131
Local Embedding Logic
The system includes a simpleEmbed function that projects text into a fixed-size vector based on word hashing. This allows for basic text search even when AI provider configurations are missing.
Visualization and Analytics
3D Vector Map
The QdrantVectorMap component renders a 3D point cloud of collection embeddings using Three.js. It employs Principal Component Analysis (PCA) to project high-dimensional vectors (e.g., 128 or 768 dimensions) into a 3D coordinate system.
- PCA Projection: The
pca3dfunction calculates the top three principal components to maximize variance in the 3D space. - Interaction: Users can rotate, zoom, and pan the map. Hovering over a point displays its payload, and clicking a point triggers a "find similar" search.
- Dynamic Coloring: Points can be colored based on specific payload fields, facilitating visual cluster analysis.
Sources: apps/desktop/src/components/qdrant-vector-map.tsx:35-77, apps/desktop/src/components/qdrant-vector-map.tsx:210-230
Collection Statistics
The tools provide a dedicated stats view displaying technical metadata about collections.
| Parameter | Source Field | Description |
|---|---|---|
| Points | points_count | Total number of points in the collection. |
| Vectors | vectorsCount | Total vectors, falling back to indexed_vectors_count. |
| Dimensions | vectorSize | The size/length of the vector embeddings. |
| Distance | distance | The distance metric used (e.g., Cosine, Euclidean). |
Sources: apps/sidecar/src/adapters/qdrant.ts:130-143, apps/desktop/src/components/qdrant-stats.tsx:25-34
Pagination and Filtering
Qdrant uses an opaque cursor for pagination rather than traditional page numbers. KamehaDB manages this via an offsetStack in the UI, allowing users to walk forward through "scroll" results and backtrack through previously visited pages.
Filtering System:
The QdrantFilterBuilder allows users to construct complex payload filters.
- Field Suggestions: Discovers payload keys from the currently loaded page to offer autocomplete suggestions.
- Persistence: Filters are integrated into search, recommendation, and scroll requests to limit result sets at the database level.
Sources: apps/desktop/src/components/qdrant-view.tsx:16-19, apps/desktop/src/components/qdrant-view.tsx:44-48, apps/sidecar/src/routes/qdrant.ts:54-63
Summary
The Qdrant Vector Database Tools in KamehaDB provide a robust interface for vector data management. By combining standard administrative tasks (browsing, stats, filtering) with advanced features like 3D PCA visualization and multi-modal search (text, similar, raw), it serves as a comprehensive tool for developers working with vector search and AI-driven applications. The architecture ensures data privacy by processing all requests through a local sidecar before reaching the Qdrant instance.