Qdrant Client

Relevant source files

The following files were used as context for generating this wiki page:

• internal/qdrant/client.go
• internal/search/service.go
• cmd/app/main.go
• internal/embeddings/ollama.go
• internal/embeddings/openai.go
• setup-ollama.md

The Qdrant Client is a Go module responsible for all communication with a Qdrant vector database instance. It provides a simplified, high-level interface for core Qdrant operations by abstracting the underlying REST API calls. Its primary functions within the MauQNotes project are to manage collections, ingest vectorized notes (upserting points), and perform semantic searches based on query vectors.

This client is a crucial component of the search service, enabling it to store and retrieve notes based on their semantic meaning rather than just keywords. It handles the construction of HTTP requests, serialization/deserialization of JSON payloads, and management of API credentials.

Architecture and Initialization

The client is designed as a struct that holds the necessary configuration to connect to a specific Qdrant collection. It is instantiated via the New() constructor, which populates the configuration from environment variables.

Sources: internal/qdrant/client.go:70-77

Client Structure

The Client struct contains the connection details for the Qdrant instance.

// internal/qdrant/client.go:63-67
type Client struct {
	BaseUrl    string
	APIKey     string
	Collection string
}

Sources: internal/qdrant/client.go:63-67

Initialization

The New() function creates a new instance of the Client. It loads environment variables using godotenv.Load() and populates the client's fields.

// internal/qdrant/client.go:70-77
func New() *Client {
	_ = godotenv.Load()
	return &Client{
		BaseUrl:    os.Getenv("QDRANT_URL"),
		APIKey:     os.Getenv("QDRANT_API_KEY"),
		Collection: os.Getenv("QDRANT_COLLECTION"),
	}
}

Sources: internal/qdrant/client.go:70-77

Before executing any operation, a validate() method is called internally to ensure that essential configuration values like QDRANT_URL and QDRANT_COLLECTION are not empty and that the URL is correctly formatted.

Sources: internal/qdrant/client.go:79-89

Configuration

The client is configured using the following environment variables, typically defined in a .env file.

Variable	Description	Example Value
QDRANT_URL	The base URL of the Qdrant instance.	http://localhost:6333
QDRANT_API_KEY	The API key for authenticating with Qdrant.	your-secret-api-key
QDRANT_COLLECTION	The name of the collection to interact with.	my-notes

Sources: internal/qdrant/client.go:73-75

Core Operations

The client exposes methods that map directly to Qdrant's primary REST API endpoints for collection management, data upsertion, and searching.

Creating a Collection

The CreateCollectionIfNotExists method sends a PUT request to create a new collection. It is idempotent; if the collection already exists (indicated by a 409 Conflict HTTP status), the operation succeeds without error. The vector size and distance metric are required parameters.

The following diagram shows the sequence for creating a collection.

This diagram illustrates the CreateCollectionIfNotExists flow, where the client gracefully handles both successful creation and pre-existing collections.

Sources: internal/qdrant/client.go:97-116, internal/search/service.go:42-44

Upserting Points

The Upsert method is used to add or update data points in the collection. A "point" consists of a unique ID, a vector embedding, and an optional JSON payload. This method batches multiple points into a single PUT request to the /points endpoint with wait=true to ensure the operation is complete before returning.

The search.IngestNotes function demonstrates this flow: it generates embeddings for each note using a model (e.g., from Ollama) and then calls client.Upsert to store them.

The diagram below shows the data ingestion process.

This sequence shows how a note is converted into a vector and then upserted into Qdrant.

Sources: internal/qdrant/client.go:118-139, internal/search/service.go:39-59, internal/embeddings/ollama.go:21-72, cmd/app/main.go:15-17

Searching for Points

The Search method performs a semantic search by sending a query vector to Qdrant. It uses a POST request to the /points/search endpoint. The client requests a specified number of nearest neighbors (limit) and always includes the payload in the results (WithPayload: true) while excluding the vector itself (WithVector: false).

The search.Query function first generates an embedding for the user's query string and then passes this vector to client.Search.

The following diagram illustrates the search workflow.

This sequence demonstrates how a text query is vectorized and used to find similar documents in Qdrant.

Sources: internal/qdrant/client.go:141-176, internal/search/service.go:61-69, cmd/app/main.go:21-23

Data Structures

The client defines several Go structs that map directly to the JSON request and response bodies of the Qdrant API.

The relationship between these structures is shown below.

This diagram shows the main Client class and the data structures it uses for requests and responses.

Sources: internal/qdrant/client.go:17-61

Struct	File	Description
Point	internal/qdrant/client.go:26-30	Represents a single data point with an ID, vector, and payload.
createCollectionRequest	internal/qdrant/client.go:17-22	Defines the request body for creating a new collection.
upsertRequest	internal/qdrant/client.go:32-34	Defines the request body for upserting points.
searchRequest	internal/qdrant/client.go:37-43	Defines the request body for a search query.
searchResult	internal/qdrant/client.go:45-52	Defines the structure for parsing the search API response.

End-to-End Data Flow

The Qdrant client is the final step in the data processing pipeline for both ingestion and querying. The overall flow involves generating a vector embedding and then using the client to communicate with the Qdrant database.

This diagram shows the complete data flow for a search query.

This flowchart illustrates how a user query is processed through the search service, vectorized by Ollama, and finally sent to the Qdrant DB via the Qdrant Client.

Sources: cmd/app/main.go, internal/search/service.go, internal/embeddings/ollama.go, internal/qdrant/client.go

Summary

The qdrant.Client is a well-defined and essential module in the MauQNotes application. It successfully abstracts the complexities of direct REST API interaction with the Qdrant vector database. By providing clear, purpose-built methods for collection creation, data upsertion, and semantic searching, it enables the higher-level search service to focus on application logic rather than on the specifics of database communication. Its reliance on environment variables for configuration makes it flexible and easy to deploy in different environments.