Vector Search with the Go Client

Tip	The source code for this tutorial is available on GitHub.

This tutorial demonstrates how to perform kNN vector search and hybrid queries with the Go Hot Rod client.

Prerequisites

A running Infinispan server.
Go 1.25 or later.

Running the Example

go run ./vector-search

Code Walkthrough

Schema and Code Generation

The example uses a proto/beer.proto file to generate a Go Beer struct at build time with protoc. The same schema — with Infinispan indexing annotations — is registered on the server.

/* @Indexed */
message Beer {
  /* @Keyword(projectable = true, sortable = true) */
  string name = 1;
  /* @Vector(dimension = 3, similarity = COSINE) */
  repeated float descriptionEmbedding = 7;
}

Creating a Typed Cache

TypedCache handles serialization using the generated protobuf type.

cache := hotrod.NewTypedCache[string, *pb.Beer](client, "beers").Build()

kNN Vector Search (Typed)

Use the <→ operator to find the k nearest neighbors to a query vector. Query() returns typed *pb.Beer values.

results, err := cache.Query(ctx,
    "from quickstart.Beer b where b.descriptionEmbedding <-> [:v]~:k",
    hotrod.WithQueryParam("v", []float32{0.9, 0.1, 0.1}),
    hotrod.WithQueryParam("k", int32(3)),
)
for _, b := range results {
    fmt.Printf("  %s %s\n", b.Name, b.Style)
}

Score Projection

Use score(b) to include the similarity score in projections. Projection queries use QueryProjection() which returns raw column values.

result, err := cache.QueryProjection(ctx,
    "select b.name, b.style, score(b) from quickstart.Beer b where b.descriptionEmbedding <-> [:v]~:k",
    hotrod.WithQueryParam("v", []float32{0.05, 0.9, 0.1}),
    hotrod.WithQueryParam("k", int32(3)),
)

Hybrid Queries

Combine vector search with metadata filters using the filtering clause.

result, err := cache.QueryProjection(ctx,
    "select score(b), b.name, b.style, b.abv from quickstart.Beer b "+
    "where b.descriptionEmbedding <-> [:v]~:k "+
    "filtering (b.style = 'Lager' and b.abv < 5.0)",
    hotrod.WithQueryParam("v", []float32{0.05, 0.95, 0.05}),
    hotrod.WithQueryParam("k", int32(3)),
)

Combine vector search with full-text filters.

result, err := cache.QueryProjection(ctx,
    "select score(b), b.name from quickstart.Beer b "+
    "where b.descriptionEmbedding <-> [:v]~:k "+
    "filtering b.description : 'citrus'",
    hotrod.WithQueryParam("v", []float32{0.1, 0.1, 0.95}),
    hotrod.WithQueryParam("k", int32(5)),
)

Expected Output

The example runs 8 query demonstrations including full-text search, keyword and range filters, projections with sorting, kNN vector search, score projection, and three hybrid query variants.