Go client v6

Release candidate

The Go v6 client is a release candidate. The API can still change before the final release. v6 does not yet cover the whole Weaviate feature set. For example, it has no generative search or reranking. For production work, use the v5 client.

Go v6 client (SDK)

The latest Go v6 client is version v6.0.0-rc.0. The Go v6 code examples in the documentation are written for and tested against this release.

weaviate/weaviate-go-clientReference manual

This page covers the Weaviate Go client v6, a ground-up redesign of the Go client built around a collections-first API. For usage information that is not specific to the Go client, such as code examples, see the relevant pages in the How-to manuals & Guides.

Installation

go get github.com/weaviate/weaviate-go-client/v6@v6.0.0-rc.0

Pin the version. An unpinned go get picks up whatever pre-release or final release is newest, and its API can differ from the one these docs describe.

The client lives at the module root and its package is named weaviate:

import weaviate "github.com/weaviate/weaviate-go-client/v6"

Requirements: Go and Weaviate version compatibility & gRPC

Go version

The v6 client module requires Go 1.26.0 or higher. On an older Go with the default GOTOOLCHAIN=auto, go get downloads a Go 1.26 toolchain and raises the go line in your go.mod to 1.26.0 without asking. With GOTOOLCHAIN=local, it fails with requires go >= 1.26.0.

Weaviate version compatibility

The v6 client requires Weaviate 1.38.8 or higher. Earlier servers truncate leading zero bytes in the gRPC id_as_bytes field, so the client rejects the whole search response with invalid UUID (got 15 bytes). Around one object in 256 has an affected ID, and every search that returns that object fails until you upgrade. Generally, we encourage you to use the latest version of the Go client and the Weaviate Database.

gRPC

The v6 client uses remote procedure calls (RPCs) under the hood. It needs both the REST and the gRPC endpoint of your instance to be reachable, so a port for gRPC must be open to your Weaviate server. Creating the client and client.IsReady only check the REST endpoint. If the gRPC port is unreachable, the first data or query call fails with code = Unavailable.

docker-compose.yml example

If you are running Weaviate with Docker, you can map the default port (50051) by adding the following to your docker-compose.yml file:

ports:
  - 8080:8080
  - 50051:50051

Get started

Prerequisites

If you haven't yet, we recommend going through the Quickstart tutorial first to get the most out of this section.

The following code demonstrates how to:

1. Connect to a local Weaviate instance.
2. Create a new collection.
3. Import data and vectorize it.
4. Perform a vector search.

package main

import (
  "context"
  "fmt"

  weaviate "github.com/weaviate/weaviate-go-client/v6"
  "github.com/weaviate/weaviate-go-client/v6/collections"
  "github.com/weaviate/weaviate-go-client/v6/data"
  "github.com/weaviate/weaviate-go-client/v6/query"
)

// The client has no typed Ollama vectorizer yet, so this small custom module
// type names text2vec-ollama. Its JSON-tagged fields are the module settings.
type text2vecOllama struct {
  APIEndpoint string `json:"apiEndpoint,omitempty"`
  Model       string `json:"model,omitempty"`
}

func (text2vecOllama) Name() string { return "text2vec-ollama" }

func main() {
  ctx := context.Background()

  // Step 1: Connect to your local Weaviate instance.
  client, err := weaviate.NewLocal(ctx)
  if err != nil {
    // handle error
    panic(err)
  }
  defer client.Close()

  // Step 2: Create a collection vectorized by the Ollama embedding integration.
  if _, err := client.Collections.Create(ctx, collections.Collection{
    Name: "Question",
    Properties: []collections.Property{
      {Name: "question", DataType: collections.DataTypeText},
      {Name: "answer", DataType: collections.DataTypeText},
      {Name: "category", DataType: collections.DataTypeText},
    },
    Vectors: map[string]collections.VectorConfig{
      "default": {Vectorizer: text2vecOllama{
        APIEndpoint: "http://ollama:11434", // If using Docker you might need: http://host.docker.internal:11434
        Model:       "nomic-embed-text",
      }},
    },
  }); err != nil {
    // handle error
    panic(err)
  }

  // Step 3: Import a few objects. The server vectorizes each one on import.
  questions := client.Collections.Use("Question")
  if _, err := questions.Data.Insert(ctx,
    &data.Object{Properties: map[string]any{
      "question": "This organ removes excess glucose from the blood & stores it as glycogen",
      "answer":   "Liver",
      "category": "SCIENCE",
    }},
    &data.Object{Properties: map[string]any{
      "question": "It's the only living mammal in the order Proboseidea",
      "answer":   "Elephant",
      "category": "ANIMALS",
    }},
    &data.Object{Properties: map[string]any{
      "question": "The gavial looks very much like a crocodile except for this bodily feature",
      "answer":   "the nose or snout",
      "category": "ANIMALS",
    }},
  ); err != nil {
    // handle error
    panic(err)
  }

  // Step 4: Run a semantic (vector) search.
  response, err := questions.Query.NearText(ctx, query.NearText{
    Concepts: []string{"biology"},
    Limit:    2,
  })
  if err != nil {
    // handle error
    panic(err)
  }
  for _, obj := range response.Objects {
    fmt.Printf("%v\n", obj.Properties)
  }
}

For more code examples, check out the How-to manuals & Guides section. Where an operation is not yet available in the v6 client, the Go v6 tab shows a short "Coming soon" note.

Releases

Go to the GitHub releases page to see the history of the Go client library releases and change logs. Pre-releases of v6 are tagged there alongside the stable v5 releases.

The client and server compatibility table on the Go client page tracks the v5 client. For v6, see Installation.

Code examples & further resources

Usage information for various operations and features can be found throughout the Weaviate documentation.

How-to: Configure Weaviate

Configure compression, backups, authentication, authorization, data replication and more.

How-to: Manage collections

Manage collections (CRUD), configure vectorizers and index parameters, set up multi-tenancy, and perform migrations.

How-to: Manage objects

Adding new objects, fetching existing ones, modifying them, and removing them from collections.

How-to: Query & search

From basic vector and hybrid searches to specialized image queries and performing data aggregations.

The Weaviate API reference pages for search and REST may also be useful starting points.

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.