Qdrant Go Client

Before using the Go client, ensure a Qdrant vector database server is running. You can start a local instance using Docker with the following command, which exposes both the gRPC port (6334) and the HTTP port (6333).

docker run --rm -it -p 6334:6334 -p 6333:6333 qdrant/qdrant

Use go get to install the latest version of the Qdrant Go client library.

go get -u github.com/qdrant/go-client

The Client acts as a high-level manager for one or more GrpcClient instances.

• Single Connection: If Config.PoolSize is 1, the client manages a single connection.
• Connection Pool: If Config.PoolSize > 1, the client maintains a pool. Every time a service client is requested (e.g., via GetPointsClient()), the Client uses an atomic counter to select the next connection in a round-robin fashion. This helps distribute load across multiple gRPC connections.

For cloud instances or secured environments, configure qdrant.Config with APIKey and UseTLS: true. The client uses a default TLS configuration with a minimum version of 1.3 when UseTLS is enabled.

import "github.com/qdrant/go-client/qdrant"

client, err := qdrant.NewClient(&qdrant.Config{
	Host:   "xyz-example.eu-central.aws.cloud.qdrant.io",
	Port:   6334,
	APIKey: "<your-api-key>",
	UseTLS: true,
	// Additional options available:
	// PoolSize: 3,
	// KeepAliveTime: 10,
	// KeepAliveTimeout: 2,
	// TLSConfig: &tls.Config{...},
	// GrpcOptions: []grpc.DialOption{},
})

To build and execute the demonstration Go application, use the provided shell script.

bash -x build-and-run.sh

Use client.CreateCollection to initialize a new collection. You must provide a CollectionName and VectorsConfig which defines the vector size and the distance metric (e.g., qdrant.Distance_Cosine).

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client.CreateCollection(context.Background(), &qdrant.CreateCollection{
	CollectionName: "{collection_name}",
	VectorsConfig: qdrant.NewVectorsConfig(&qdrant.VectorParams{
		Size:     4,
		Distance: qdrant.Distance_Cosine,
	}),
})

Use client.Query to perform vector similarity searches. You can provide a Query vector and an optional Filter to restrict results based on payload conditions (e.g., using qdrant.NewMatch). Use WithPayload to specify if the payload should be returned in the results.

// Basic search
searchResult, err := client.Query(context.Background(), &qdrant.QueryPoints{
	CollectionName: "{collection_name}",
	Query:          qdrant.NewQuery(0.2, 0.1, 0.9, 0.7),
})

// Search with filtering
searchResult, err := client.Query(context.Background(), &qdrant.QueryPoints{
	CollectionName: "{collection_name}",
	Query:          qdrant.NewQuery(0.2, 0.1, 0.9, 0.7),
	Filter: &qdrant.Filter{
		Must: []*qdrant.Condition{
			qdrant.NewMatch("city", "London"),
		},
	},
	WithPayload: qdrant.NewWithPayload(true),
})

Use client.Upsert to insert or update points in a collection. Each point requires an Id, Vectors, and an optional Payload (a map of values).

operationInfo, err := client.Upsert(context.Background(), &qdrant.UpsertPoints{
	CollectionName: "{collection_name}",
	Points: []*qdrant.PointStruct{
		{
			Id:      qdrant.NewIDNum(1),
			Vectors: qdrant.NewVectors(0.05, 0.61, 0.76, 0.74),
			Payload: qdrant.NewValueMap(map[string]any{"city": "London"}),
		},
		{
			Id:      qdrant.NewIDNum(2),
			Vectors: qdrant.NewVectors(0.19, 0.81, 0.75, 0.11),
			Payload: qdrant.NewValueMap(map[string]any{"age": 32}),
		},
		{
			Id:      qdrant.NewIDNum(3),
			Vectors: qdrant.NewVectors(0.36, 0.55, 0.47, 0.94),
			Payload: qdrant.NewValueMap(map[string]any{"vegan": true}),
		},
	},
})

Instantiate a client using qdrant.NewClient with a *qdrant.Config. By default, it connects via gRPC. You can configure the host, port, API key for authentication, and TLS settings.

import "github.com/qdrant/go-client/qdrant"

client, err := qdrant.NewClient(&qdrant.Config{
  Host: "localhost",
  Port: 6334,
})

Use NewClient to create a high-level Qdrant client. You must provide a *Config object. The client manages a pool of gRPC connections based on the PoolSize specified in the configuration. If PoolSize is 0, it defaults to 3. When using a pool, requests are distributed across connections using a round-robin strategy.

import "github.com/qdrant/qdrant/go-client"

config := &qdrant.Config{
    // Set your configuration here
    PoolSize: 5,
}

client, err := qdrant.NewClient(config)
if err != nil {
    panic(err)
}
defer client.Close()

Use DefaultClient for a quick setup. It instantiates a client with default settings, connecting to localhost:6334 with TLS disabled.

import "github.com/qdrant/qdrant/go-client"

client, err := qdrant.DefaultClient()
if err != nil {
    panic(err)
}
defer client.Close()

Call Close() to tear down all underlying gRPC connections managed by the client. This method is safe to call multiple times (it uses sync.Once). If multiple connections fail to close, the method returns a joined error containing all failures.

err := client.Close()
if err != nil {
    // Handle joined errors
}