{"id":19000437,"url":"https://github.com/typesense/typesense-go","last_synced_at":"2025-05-15T15:03:50.497Z","repository":{"id":36950169,"uuid":"322947344","full_name":"typesense/typesense-go","owner":"typesense","description":"Go client for Typesense: https://github.com/typesense/typesense","archived":false,"fork":false,"pushed_at":"2025-03-27T15:22:24.000Z","size":1050,"stargazers_count":245,"open_issues_count":25,"forks_count":61,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T20:05:31.696Z","etag":null,"topics":["go-client","search","typesense"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/typesense.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-19T22:13:47.000Z","updated_at":"2025-03-29T12:56:20.000Z","dependencies_parsed_at":"2024-01-02T12:22:30.966Z","dependency_job_id":"9a364ea6-2a03-4728-9d5d-753df5ecb9c5","html_url":"https://github.com/typesense/typesense-go","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Ftypesense-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Ftypesense-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Ftypesense-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/typesense%2Ftypesense-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/typesense","download_url":"https://codeload.github.com/typesense/typesense-go/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247730068,"owners_count":20986404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go-client","search","typesense"],"created_at":"2024-11-08T18:07:13.515Z","updated_at":"2025-04-07T21:09:39.748Z","avatar_url":"https://github.com/typesense.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# typesense-go\n\n[![Build Status](https://cloud.drone.io/api/badges/typesense/typesense-go/status.svg)](https://cloud.drone.io/typesense/typesense-go)\n[![GoReportCard Status](https://goreportcard.com/badge/github.com/typesense/typesense-go/v3)](https://goreportcard.com/report/github.com/typesense/typesense-go/v3)\n[![Go Reference](https://pkg.go.dev/badge/github.com/typesense/typesense-go/v3.svg)](https://pkg.go.dev/github.com/typesense/typesense-go/v3)\n[![GitHub release](https://img.shields.io/github/v/release/typesense/typesense-go)](https://github.com/typesense/typesense-go/releases/latest)\n[![Gitter](https://badges.gitter.im/typesense-go/community.svg)](https://gitter.im/typesense-go/community)\n\nGo client for the Typesense API: https://github.com/typesense/typesense\n\n## Installation\n\n```\ngo get github.com/typesense/typesense-go/v3/typesense\n```\n\n## Usage\n\nImport the the package into your code :\n\n```go\nimport \"github.com/typesense/typesense-go/v3/typesense\"\n```\n\nCreate new client:\n\n```go\nclient := typesense.NewClient(\n\t    typesense.WithServer(\"http://localhost:8108\"),\n\t    typesense.WithAPIKey(\"\u003cAPI_KEY\u003e\"))\n```\n\nNew client with advanced configuration options (see godoc):\n\n```go\nclient := typesense.NewClient(\n\t\ttypesense.WithServer(\"http://localhost:8108\"),\n\t\ttypesense.WithAPIKey(\"\u003cAPI_KEY\u003e\"),\n\t\ttypesense.WithConnectionTimeout(5*time.Second),\n\t\ttypesense.WithCircuitBreakerMaxRequests(50),\n\t\ttypesense.WithCircuitBreakerInterval(2*time.Minute),\n\t\ttypesense.WithCircuitBreakerTimeout(1*time.Minute),\n\t)\n```\n\nNew client with multi-node configuration options:\n\n```go\nclient := typesense.NewClient(\n\t\ttypesense.WithNearestNode(\"https://xxx.a1.typesense.net:443\"),\n\t\ttypesense.WithNodes([]string{\n\t\t\t\"https://xxx-1.a1.typesense.net:443\",\n\t\t\t\"https://xxx-2.a1.typesense.net:443\",\n\t\t\t\"https://xxx-3.a1.typesense.net:443\",\n\t\t}),\n\t\ttypesense.WithAPIKey(\"\u003cAPI_KEY\u003e\"),\n\t\ttypesense.WithNumRetries(5),\n\t\ttypesense.WithRetryInterval(1*time.Second),\n\t\ttypesense.WithHealthcheckInterval(2*time.Minute),\n\t)\n```\n\nYou can also find some examples in [integration tests](https://github.com/typesense/typesense-go/tree/master/typesense/test).\n\n### Create a collection\n\n```go\n\tschema := \u0026api.CollectionSchema{\n\t\tName: \"companies\",\n\t\tFields: []api.Field{\n\t\t\t{\n\t\t\t\tName: \"company_name\",\n\t\t\t\tType: \"string\",\n\t\t\t},\n\t\t\t{\n\t\t\t\tName: \"num_employees\",\n\t\t\t\tType: \"int32\",\n\t\t\t},\n\t\t\t{\n\t\t\t\tName:  \"country\",\n\t\t\t\tType:  \"string\",\n\t\t\t\tFacet: true,\n\t\t\t},\n\t\t},\n\t\tDefaultSortingField: pointer.String(\"num_employees\"),\n\t}\n\n\tclient.Collections().Create(context.Background(), schema)\n```\n\n### Typed document operations\n\nIn `v2.0.0`+, the client allows you to define a document struct to be used type for some of the document operations.\n\nTo do that, you've to use `typesense.GenericCollection`:\n\n```go\ntype companyDocument struct {\n    ID           string `json:\"id\"`\n    CompanyName  string `json:\"company_name\"`\n    NumEmployees int    `json:\"num_employees\"`\n    Country      string `json:\"country\"`\n}\n\n// doc is a typed document\ndoc, err := typesense.GenericCollection[*companyDocument](typesenseClient, collectionName).Document(\"123\").Retrieve(context.Background())\n```\n\n### Index a document\n\n```go\n\tdocument := struct {\n\t\tID           string `json:\"id\"`\n\t\tCompanyName  string `json:\"company_name\"`\n\t\tNumEmployees int    `json:\"num_employees\"`\n\t\tCountry      string `json:\"country\"`\n\t}{\n\t\tID:           \"123\",\n\t\tCompanyName:  \"Stark Industries\",\n\t\tNumEmployees: 5215,\n\t\tCountry:      \"USA\",\n\t}\n\n\tclient.Collection(\"companies\").Documents().Create(context.Background(), document)\n```\n\n### Upserting a document\n\n```go\n\tnewDocument := struct {\n\t\tID           string `json:\"id\"`\n\t\tCompanyName  string `json:\"company_name\"`\n\t\tNumEmployees int    `json:\"num_employees\"`\n\t\tCountry      string `json:\"country\"`\n\t}{\n\t\tID:           \"123\",\n\t\tCompanyName:  \"Stark Industries\",\n\t\tNumEmployees: 5215,\n\t\tCountry:      \"USA\",\n\t}\n\n\tclient.Collection(\"companies\").Documents().Upsert(context.Background(), newDocument)\n```\n\n### Search a collection\n\n```go\n\tsearchParameters := \u0026api.SearchCollectionParams{\n\t\tQ:        pointer.String(\"stark\"),\n\t\tQueryBy:  pointer.String(\"company_name\"),\n\t\tFilterBy: pointer.String(\"num_employees:\u003e100\"),\n\t\tSortBy:   \u0026([]string{\"num_employees:desc\"}),\n\t}\n\n\tclient.Collection(\"companies\").Documents().Search(context.Background(), searchParameters)\n```\n\nfor the supporting multiple `QueryBy` params, you can add `,` after each field\n\n```go\n\tsearchParameters := \u0026api.SearchCollectionParams{\n\t\tQ:        pointer.String(\"stark\"),\n\t\tQueryBy:  pointer.String(\"company_name, country\"),\n\t\tFilterBy: pointer.String(\"num_employees:\u003e100\"),\n\t\tSortBy:   \u0026([]string{\"num_employees:desc\"}),\n\t}\n\n\tclient.Collection(\"companies\").Documents().Search(context.Background(), searchParameters)\n```\n\n### Retrieve a document\n\n```go\nclient.Collection(\"companies\").Document(\"123\").Retrieve(context.Background())\n```\n\n### Update a document\n\n```go\n\tdocument := struct {\n\t\tCompanyName  string `json:\"company_name\"`\n\t\tNumEmployees int    `json:\"num_employees\"`\n\t}{\n\t\tCompanyName:  \"Stark Industries\",\n\t\tNumEmployees: 5500,\n\t}\n\n\tclient.Collection(\"companies\").Document(\"123\").Update(context.Background(), document)\n```\n\n### Delete an individual document\n\n```go\nclient.Collection(\"companies\").Document(\"123\").Delete(context.Background())\n```\n\n### Delete a bunch of documents\n\n```go\nfilter := \u0026api.DeleteDocumentsParams{FilterBy: \"num_employees:\u003e100\", BatchSize: 100}\nclient.Collection(\"companies\").Documents().Delete(context.Background(), filter)\n```\n\n### Retrieve a collection\n\n```go\nclient.Collection(\"companies\").Retrieve(context.Background())\n```\n\n### Export documents from a collection\n\n```go\nclient.Collection(\"companies\").Documents().Export(context.Background())\n```\n\n### Import documents into a collection\n\nThe documents to be imported can be either an array of document objects or be formatted as a newline delimited JSON string (see [JSONL](https://jsonlines.org)).\n\nImport an array of documents:\n\n```go\n\tdocuments := []interface{}{\n\t\tstruct {\n\t\t\tID           string `json:\"id\"`\n\t\t\tCompanyName  string `json:\"companyName\"`\n\t\t\tNumEmployees int    `json:\"numEmployees\"`\n\t\t\tCountry      string `json:\"country\"`\n\t\t}{\n\t\t\tID:           \"123\",\n\t\t\tCompanyName:  \"Stark Industries\",\n\t\t\tNumEmployees: 5215,\n\t\t\tCountry:      \"USA\",\n\t\t},\n\t}\n\tparams := \u0026api.ImportDocumentsParams{\n\t\tAction:    pointer.String(\"create\"),\n\t\tBatchSize: pointer.Int(40),\n\t}\n\n\tclient.Collection(\"companies\").Documents().Import(context.Background(), documents, params)\n```\n\nImport a JSONL file:\n\n```go\n\tparams := \u0026api.ImportDocumentsParams{\n\t\tAction:    pointer.String(\"create\"),\n\t\tBatchSize: pointer.Int(40),\n\t}\n\timportBody, err := os.Open(\"documents.jsonl\")\n\t// defer close, error handling ...\n\n\tclient.Collection(\"companies\").Documents().ImportJsonl(context.Background(), importBody, params)\n```\n\n### List all collections\n\n```go\nclient.Collections().Retrieve(context.Background())\n```\n\n### Drop a collection\n\n```go\nclient.Collection(\"companies\").Delete(context.Background())\n```\n\n### Create an API Key\n\n```go\n\tkeySchema := \u0026api.ApiKeySchema{\n\t\tDescription: \"Search-only key.\",\n\t\tActions:     []string{\"documents:search\"},\n\t\tCollections: []string{\"companies\"},\n\t\tExpiresAt:   time.Now().AddDate(0, 6, 0).Unix(),\n\t}\n\n\tclient.Keys().Create(context.Background(), keySchema)\n```\n\n### Retrieve an API Key\n\n```go\nclient.Key(1).Retrieve(context.Background())\n```\n\n### List all keys\n\n```go\nclient.Keys().Retrieve(context.Background())\n```\n\n### Delete API Key\n\n```go\nclient.Key(1).Delete(context.Background())\n```\n\n### Create or update an override\n\n```go\n\toverride := \u0026api.SearchOverrideSchema{\n\t\tRule: api.SearchOverrideRule{\n\t\t\tQuery: \"apple\",\n\t\t\tMatch: \"exact\",\n\t\t},\n\t\tIncludes: []api.SearchOverrideInclude{\n\t\t\t{\n\t\t\t\tId:       \"422\",\n\t\t\t\tPosition: 1,\n\t\t\t},\n\t\t\t{\n\t\t\t\tId:       \"54\",\n\t\t\t\tPosition: 2,\n\t\t\t},\n\t\t},\n\t\tExcludes: []api.SearchOverrideExclude{\n\t\t\t{\n\t\t\t\tId: \"287\",\n\t\t\t},\n\t\t},\n\t}\n\n\tclient.Collection(\"companies\").Overrides().Upsert(context.Background(), \"customize-apple\", override)\n```\n\n### List all overrides\n\n```go\nclient.Collection(\"companies\").Overrides().Retrieve(context.Background())\n```\n\n### Delete an override\n\n```go\nclient.Collection(\"companies\").Override(\"customize-apple\").Delete(context.Background())\n```\n\n### Create or Update an alias\n\n```go\n\tbody := \u0026api.CollectionAliasSchema{CollectionName: \"companies_june11\"}\n\tclient.Aliases().Upsert(\"companies\", body)\n```\n\n### Retrieve an alias\n\n```go\nclient.Alias(\"companies\").Retrieve(context.Background())\n```\n\n### List all aliases\n\n```go\nclient.Aliases().Retrieve(context.Background())\n```\n\n### Delete an alias\n\n```go\nclient.Alias(\"companies\").Delete(context.Background())\n```\n\n### Create or update a multi-way synonym\n\n```go\n\tsynonym := \u0026api.SearchSynonymSchema{\n\t\tSynonyms: []string{\"blazer\", \"coat\", \"jacket\"},\n\t}\n\tclient.Collection(\"products\").Synonyms().Upsert(context.Background(), \"coat-synonyms\", synonym)\n```\n\n### Create or update a one-way synonym\n\n```go\n\tsynonym := \u0026api.SearchSynonymSchema{\n\t\tRoot:     \"blazer\",\n\t\tSynonyms: []string{\"blazer\", \"coat\", \"jacket\"},\n\t}\n\tclient.Collection(\"products\").Synonyms().Upsert(context.Background(), \"coat-synonyms\", synonym)\n```\n\n### Retrieve a synonym\n\n```go\nclient.Collection(\"products\").Synonym(\"coat-synonyms\").Retrieve(context.Background())\n```\n\n### List all synonyms\n\n```go\nclient.Collection(\"products\").Synonyms().Retrieve(context.Background())\n```\n\n### Delete a synonym\n\n```go\nclient.Collection(\"products\").Synonym(\"coat-synonyms\").Delete(context.Background())\n```\n\n### Create or update a stopwords set\n\n```go\n\tstopwords := \u0026api.StopwordsSetUpsertSchema{\n\t\tLocale:    pointer.String(\"en\"),\n\t\tStopwords: []string{\"Germany\", \"France\", \"Italy\", \"United States\"},\n\t}\n\tclient.Stopwords().Upsert(context.Background(), \"stopword_set1\", stopwords)\n```\n\n### Retrieve a stopwords set\n\n```go\nclient.Stopword(\"stopword_set1\").Retrieve(context.Background())\n```\n\n### List all stopwords sets\n\n```go\nclient.Stopwords().Retrieve(context.Background())\n```\n\n### Delete a stopwords set\n\n```go\nclient.Stopword(\"stopword_set1\").Delete(context.Background())\n```\n\n### Create or update a preset\n\n```go\npreset := \u0026api.PresetUpsertSchema{}\npreset.Value.FromMultiSearchSearchesParameter(api.MultiSearchSearchesParameter{\n\t\tSearches: []api.MultiSearchCollectionParameters{\n\t\t\t{\n\t\t\t\tCollection: \"books\",\n\t\t\t},\n\t\t},\n\t})\n// or: preset.Value.FromSearchParameters(api.SearchParameters{Q: \"Books\"})\n\nclient.Presets().Upsert(context.Background(), \"listing-view-preset\", preset)\n```\n\n### Retrieve a preset\n\n```go\nclient.Preset(\"listing-view-preset\").Retrieve(context.Background())\n```\n\n### List all presets\n\n```go\nclient.Presets().Retrieve(context.Background())\n```\n\n### Delete a preset\n\n```go\nclient.Preset(\"listing-view-preset\").Delete(context.Background())\n```\n\n### Create snapshot (for backups)\n\n```go\nclient.Operations().Snapshot(context.Background(), \"/tmp/typesense-data-snapshot\")\n```\n\n### Re-elect Leader\n\n```go\nclient.Operations().Vote(context.Background())\n```\n\n### Cluster Metrics\n\n```go\nclient.Metrics().Retrieve(context.Background())\n```\n\n### API Stats\n\n```go\nclient.Stats().Retrieve(context.Background())\n```\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/typesense/typesense-go.\n\n#### Development Workflow Setup\n\nInstall dependencies,\n\n```bash\ngo mod download\n```\n\nUpdate the generated files,\n\n```bash\ngo generate ./...\n```\n\n## License\n\n`typesense-go` is distributed under the Apache 2 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypesense%2Ftypesense-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftypesense%2Ftypesense-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftypesense%2Ftypesense-go/lists"}