typesense/typesense-go

typesense-go

Go client for the Typesense API: https://github.com/typesense/typesense

Installation

go get github.com/typesense/typesense-go/v4/typesense

Usage

Import the the package into your code :

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

Create new client:

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

New client with advanced configuration options (see godoc):

client := typesense.NewClient(
		typesense.WithServer("http://localhost:8108"),
		typesense.WithAPIKey("<API_KEY>"),
		typesense.WithConnectionTimeout(5*time.Second),
		typesense.WithCircuitBreakerMaxRequests(50),
		typesense.WithCircuitBreakerInterval(2*time.Minute),
		typesense.WithCircuitBreakerTimeout(1*time.Minute),
	)

New client with multi-node configuration options:

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),
	)

You can also find some examples in integration tests.

Create a collection

	schema := &api.CollectionSchema{
		Name: "companies",
		Fields: []api.Field{
			{
				Name: "company_name",
				Type: "string",
			},
			{
				Name: "num_employees",
				Type: "int32",
			},
			{
				Name:  "country",
				Type:  "string",
				Facet: true,
			},
		},
		DefaultSortingField: pointer.String("num_employees"),
	}

	client.Collections().Create(context.Background(), schema)

Typed document operations

In v2.0.0+, the client allows you to define a document struct to be used type for some of the document operations.

To do that, you've to use typesense.GenericCollection:

type companyDocument struct {
    ID           string `json:"id"`
    CompanyName  string `json:"company_name"`
    NumEmployees int    `json:"num_employees"`
    Country      string `json:"country"`
}

// doc is a typed document
doc, err := typesense.GenericCollection[*companyDocument](typesenseClient, collectionName).Document("123").Retrieve(context.Background())

Index a document

	document := struct {
		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)

Upserting a document

	newDocument := struct {
		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)

Search a collection

	searchParameters := &api.SearchCollectionParams{
		Q:        pointer.String("stark"),
		QueryBy:  pointer.String("company_name"),
		FilterBy: pointer.String("num_employees:>100"),
		SortBy:   &([]string{"num_employees:desc"}),
	}

	client.Collection("companies").Documents().Search(context.Background(), searchParameters)

for the supporting multiple QueryBy params, you can add , after each field

	searchParameters := &api.SearchCollectionParams{
		Q:        pointer.String("stark"),
		QueryBy:  pointer.String("company_name, country"),
		FilterBy: pointer.String("num_employees:>100"),
		SortBy:   &([]string{"num_employees:desc"}),
	}

	client.Collection("companies").Documents().Search(context.Background(), searchParameters)

Retrieve a document

client.Collection("companies").Document("123").Retrieve(context.Background())

Update a document

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

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

Delete an individual document

client.Collection("companies").Document("123").Delete(context.Background())

Delete a bunch of documents

filter := &api.DeleteDocumentsParams{FilterBy: "num_employees:>100", BatchSize: 100}
client.Collection("companies").Documents().Delete(context.Background(), filter)

Retrieve a collection

client.Collection("companies").Retrieve(context.Background())

Export documents from a collection

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

Import documents into a collection

The documents to be imported can be either an array of document objects or be formatted as a newline delimited JSON string (see JSONL).

Import an array of documents:

	documents := []interface{}{
		struct {
			ID           string `json:"id"`
			CompanyName  string `json:"companyName"`
			NumEmployees int    `json:"numEmployees"`
			Country      string `json:"country"`
		}{
			ID:           "123",
			CompanyName:  "Stark Industries",
			NumEmployees: 5215,
			Country:      "USA",
		},
	}
	params := &api.ImportDocumentsParams{
		Action:    pointer.String("create"),
		BatchSize: pointer.Int(40),
	}

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

Import a JSONL file:

	params := &api.ImportDocumentsParams{
		Action:    pointer.String("create"),
		BatchSize: pointer.Int(40),
	}
	importBody, err := os.Open("documents.jsonl")
	// defer close, error handling ...

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

List all collections

client.Collections().Retrieve(context.Background())

Drop a collection

client.Collection("companies").Delete(context.Background())

Create an API Key

	keySchema := &api.ApiKeySchema{
		Description: "Search-only key.",
		Actions:     []string{"documents:search"},
		Collections: []string{"companies"},
		ExpiresAt:   time.Now().AddDate(0, 6, 0).Unix(),
	}

	client.Keys().Create(context.Background(), keySchema)

Retrieve an API Key

client.Key(1).Retrieve(context.Background())

List all keys

client.Keys().Retrieve(context.Background())

Delete API Key

client.Key(1).Delete(context.Background())

Create or update an override

	override := &api.SearchOverrideSchema{
		Rule: api.SearchOverrideRule{
			Query: "apple",
			Match: "exact",
		},
		Includes: []api.SearchOverrideInclude{
			{
				Id:       "422",
				Position: 1,
			},
			{
				Id:       "54",
				Position: 2,
			},
		},
		Excludes: []api.SearchOverrideExclude{
			{
				Id: "287",
			},
		},
	}

	client.Collection("companies").Overrides().Upsert(context.Background(), "customize-apple", override)

List all overrides

client.Collection("companies").Overrides().Retrieve(context.Background())

Delete an override

client.Collection("companies").Override("customize-apple").Delete(context.Background())

Create or Update an alias

	body := &api.CollectionAliasSchema{CollectionName: "companies_june11"}
	client.Aliases().Upsert("companies", body)

Retrieve an alias

client.Alias("companies").Retrieve(context.Background())

List all aliases

client.Aliases().Retrieve(context.Background())

Delete an alias

client.Alias("companies").Delete(context.Background())

Create or update a multi-way synonym

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

Create or update a one-way synonym

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

Retrieve a synonym

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

List all synonyms

client.Collection("products").Synonyms().Retrieve(context.Background())

Delete a synonym

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

Create or update a stopwords set

	stopwords := &api.StopwordsSetUpsertSchema{
		Locale:    pointer.String("en"),
		Stopwords: []string{"Germany", "France", "Italy", "United States"},
	}
	client.Stopwords().Upsert(context.Background(), "stopword_set1", stopwords)

Retrieve a stopwords set

client.Stopword("stopword_set1").Retrieve(context.Background())

List all stopwords sets

client.Stopwords().Retrieve(context.Background())

Delete a stopwords set

client.Stopword("stopword_set1").Delete(context.Background())

Create or update a preset

preset := &api.PresetUpsertSchema{}
preset.Value.FromMultiSearchSearchesParameter(api.MultiSearchSearchesParameter{
		Searches: []api.MultiSearchCollectionParameters{
			{
				Collection: "books",
			},
		},
	})
// or: preset.Value.FromSearchParameters(api.SearchParameters{Q: "Books"})

client.Presets().Upsert(context.Background(), "listing-view-preset", preset)

Retrieve a preset

client.Preset("listing-view-preset").Retrieve(context.Background())

List all presets

client.Presets().Retrieve(context.Background())

Delete a preset

client.Preset("listing-view-preset").Delete(context.Background())

Create snapshot (for backups)

client.Operations().Snapshot(context.Background(), "/tmp/typesense-data-snapshot")

Re-elect Leader

client.Operations().Vote(context.Background())

Cluster Metrics

client.Metrics().Retrieve(context.Background())

API Stats

client.Stats().Retrieve(context.Background())

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/typesense/typesense-go.

Development Workflow Setup

Install dependencies,

go mod download

Update the generated files,

go generate ./...

Run all tests

# In Windows Powershell
# $env:TYPESENSE_API_KEY="xyz"
# $env:TYPESENSE_URL="http://localhost:8108"

export TYPESENSE_URL="http://localhost:8108"
export TYPESENSE_API_KEY="xyz"

go test ./... -tags=integration -v

License

typesense-go is distributed under the Apache 2 license.