Typesense Go Client (v4)

Import the package and use typesense.NewClient to create a client. You can provide various configuration options using functional options.

Basic Client

import "github.com/typesense/typesense-go/v4/typesense"

client := typesense.NewClient(
    typesense.WithServer("http://localhost:8108"),
    typesense.WithAPIKey("<API_KEY>"),
)

Advanced Configuration

Use options like WithConnectionTimeout, WithCircuitBreakerMaxRequests, WithCircuitBreakerInterval, and WithCircuitBreakerTimeout for fine-grained control.

Multi-node Configuration

For high availability, configure multiple nodes using WithNearestNode and WithNodes:

client := typesense.NewClient(
    typesense.WithNearestNode("https://xxx.a1.typesense.net:443"),
    typesense.WithNodes([]string{
        "https://xxx-1.a1.typesense.net:443",
        "https://xxx-2.a1.typesense.net:443",
        "https://xxx-3.a1.typesense.net:443",
    }),
    typesense.WithAPIKey("<API_KEY>"),
    typesense.WithNumRetries(5),
    typesense.WithRetryInterval(1*time.Second),
    typesense.WithHealthcheckInterval(2*time.Minute),
)

Use NewClient to create a new Typesense client. You can configure the client using functional options to set the server URL, API key, connection timeouts, retries, and circuit breaker settings.

Common configuration options include:

• WithServer(url string): Sets the primary API server URL.
• WithAPIKey(key string): Sets the API token for authentication.
• WithNodes(urls []string): Sets multiple hostnames for load balancing reads and writes.
• WithNearestNode(url string): Sets a specific load-balanced endpoint.
• WithConnectionTimeout(duration time.Duration): Sets the HTTP client connection timeout (default 5s).
• WithNumRetries(num int): Sets the number of retries per request.
• WithCustomHTTPClient(client *http.Client): Provides a custom HTTP client.

import "github.com/typesense/typesense-go/v4/typesense"

client := typesense.NewClient(
    typesense.WithServer("http://localhost:8108"),
    typesense.WithAPIKey("xyz"),
    typesense.WithConnectionTimeout(10 * time.Second),
)

Efficiently move data in and out of collections.

Import an array of documents

params := &api.ImportDocumentsParams{
    Action:    pointer.String("create"),
    BatchSize: pointer.Int(40),
}

client.Collection("companies").Documents().Import(context.Background(), documents, params)

Import a JSONL file

    Action:    pointer.String("create"),
    BatchSize: pointer.Int(40),
}
importBody, err := os.Open("documents.jsonl")
// ... handle error and defer close

client.Collection("companies").Documents().ImportJsonl(context.Background(), importBody, params)

Export documents

client.Collection("companies").Documents().Export(context.Background())

// Import array
client.Collection("companies").Documents().Import(context.Background(), documents, params)

// Import JSONL
client.Collection("companies").Documents().ImportJsonl(context.Background(), importBody, params)

// Export
client.Collection("companies
).Documents().Export(context.Background())

Perform standard CRUD operations on documents within a collection.

Index a document (Create)

		ID           string `json:"id"`
		CompanyName  string `json:"company_name"`
		NumEmployees int    `json:"num_employees"`
		Country      string `json:"country"`
	}{
		ID:           "123",
		CompanyName:  "Stark Industries",
		NumEmployees: 5215,
		Country:      "USA",
	}

client.Collection("companies").Documents().Create(context.Background(), document)

Upsert a document

		ID           string `json:"id"`
		CompanyName  string `json:"company_name"`
		NumEmployees int    `json:"num_employees"`
		Country      string `json:"country"`
	}{
		ID:           "123",
		CompanyName:  "Stark Industries",
		NumEmployees: 5215,
		Country:      "USA",
	}

client.Collection("companies").Documents().Upsert(context.Background(), newDocument)

Update a document

		CompanyName  string `json:"company_name"`
		NumEmployees int    `json:"num_employees"`
	}{
		CompanyName:  "Stark Industries",
		NumEmployees: 5500,
	}

client.Collection("companies").Document("123").Update(context.Background(), document)

// Index
client.Collection("companies").Documents().Create(context.Background(), document)

// Upsert
client.Collection("companies").Documents().Upsert(context.Background(), newDocument)

// Update
client.Collection("companies").Document("123").Update(context.Background(), document)

Configure how search terms relate to each other using multi-way or one-way synonyms.

Multi-way Synonyms

All terms in the list are treated as synonyms for each other.

synonym := &api.SearchSynonymSchema{
    Synonyms: []string{"blazer", "coat", "jacket"},
}
client.Collection("products").Synonyms().Upsert(context.Background(), "coat-synonyms", synonym)

One-way Synonyms

Specifies a Root term that maps to a list of synonyms.

synonym := &api.SearchSynonymSchema{
    Root:     "blazer",
    Synonyms: []string{"blazer", "coat", "jacket"},
}
client.Collection("products").Synonyms().Upsert(context.Background(), "coat-synonyms", synonym)

Retrieve, List, and Delete

// Retrieve
client.Collection("products").Synonym("coat-synonyms").Retrieve(context.Background())

// List all
client.Collection("products").Synonyms().Retrieve(context.Background())

// Delete
client.Collection("products").Synonym("coat-synonyms").Delete(context.Background())

// Multi-way
synonym := &api.SearchSynonymSchema{
    Synonyms: []string{"blazer", "coat", "jacket"},
}
client.Collection("products").Synonyms().Upsert(context.Background(), "coat-synonyms", synonym)

// One-way
synonym := &api.SearchSynonymSchema{
    Root:     "blazer",
    Synonyms: []string{"blazer", "coat", "jacket"},
}
client.Collection("products").Synonyms().Upsert(context.Background(), "coat-synonyms", synonym)