How qdrant/qdrant-client works
Main components
• Client API Layer: Two main flavors are offered – the synchronous API (QdrantClient) and asynchronous API (AsyncQdrantClient). Both interfaces expose similar functionality.
• API Communication Modules:
• HTTP API: Located under the “qdrant_client/http” directory with modules for API endpoints (collections, points, snapshots, service API, etc.), models, and exceptions.
• gRPC API: The “qdrant_client/grpc” directory holds the auto-generated gRPC modules, including service definitions and protocol buffers.
• Local Mode: Implemented in “qdrant_client/local” to simulate or run Qdrant API operations without requiring an external server. This module includes everything needed for persistence to disk or in-memory (":memory:") storage.
• Embedding Functionality: The “qdrant_client/embed” and “qdrant_client/fastembed_common.py” modules support FastEmbed which uses ONNX Runtime for CPU (or GPU) based vector embeddings.
• Authentication & Authorization: Modules in “qdrant_client/auth”, particularly for bearer authentication.
• Conversions and common utilities: Found in “qdrant_client/conversions” and “qdrant_client/common”.
• Tools & Code Generation: Located in the “tools” directory, these scripts help generate async clients, REST/gRPC clients, documentation, and also work with an inspection cache for embedding purposes.
• Tests and Continuous Integration: There is an extensive “tests” directory along with CI/CD configuration (GitHub workflows, pre-commit hooks, mypy, etc.) that ensures high test coverage and quality.
Relationships and interactions
• The client library (both sync and async) acts as a mediator between the user’s application and the Qdrant server (via HTTP or gRPC connections) or the local mode.
• A client instantiation may interact with authentication modules and connection modules to establish a session.
• When executing operations (create collection, upsert, query, etc.), the client calls the corresponding HTTP or gRPC API component.
• The FastEmbed integration is used when generating vector representations; this forms another sub-component fed into the upload and query paths.
• The conversion utilities help translate between Python objects and the protocol formats required for both HTTP and gRPC.
• The “tools” as well as documentation generators interact indirectly with the core modules to provide both client code generation and developer guidance.
Architectural patterns and design principles
• Modularity: The project is neatly organized into modules such as “http”, “grpc”, “local”, “auth”, and “conversions”, which helps in separating concerns.
• Dual Architecture: Both synchronous and asynchronous patterns are supported, implying a design that maximizes reuse of internal logic while providing two interface layers.
• Abstraction: The client abstracts underlying protocols (HTTP and gRPC) so that users can choose the desired mode seamlessly.
• Extensibility: With folder structures such as “embed”, “tools”, and “grpc” handling auto-generated code, the design anticipates further extension and integration with other services.
Final checklist for the principal software engineer
• Clearly delineate each major component (client APIs, communication protocols, embedding modules, local mode, tools).
• Be detailed – include auxiliary components like authentication, conversion, testing, and documentation generation tools.
• Both synchronous and asynchronous flows, showing how each mode interacts with HTTP/gRPC and local persistence.