{"id":13514071,"url":"https://github.com/meilisearch/meilisearch-go","last_synced_at":"2025-03-31T02:33:18.952Z","repository":{"id":37867942,"uuid":"226735754","full_name":"meilisearch/meilisearch-go","owner":"meilisearch","description":"Golang wrapper for the Meilisearch API ","archived":false,"fork":false,"pushed_at":"2025-03-21T22:35:17.000Z","size":2336,"stargazers_count":577,"open_issues_count":16,"forks_count":90,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T02:19:37.393Z","etag":null,"topics":["client","go","golang","meilisearch","sdk"],"latest_commit_sha":null,"homepage":"https://www.meilisearch.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meilisearch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2019-12-08T21:41:09.000Z","updated_at":"2025-03-24T11:52:56.000Z","dependencies_parsed_at":"2023-11-18T21:22:42.930Z","dependency_job_id":"f1968a1e-64ae-4ef3-aae8-0f7d0dcf6b72","html_url":"https://github.com/meilisearch/meilisearch-go","commit_stats":null,"previous_names":["alexisvisco/meilisearch-go"],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meilisearch","download_url":"https://codeload.github.com/meilisearch/meilisearch-go/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246407401,"owners_count":20772126,"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":["client","go","golang","meilisearch","sdk"],"created_at":"2024-08-01T05:00:45.315Z","updated_at":"2025-03-31T02:33:18.938Z","avatar_url":"https://github.com/meilisearch.png","language":"Go","funding_links":[],"categories":["Go","Integrations"],"sub_categories":["Official Integrations"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/meilisearch/integration-guides/main/assets/logos/meilisearch_go.svg\" alt=\"Meilisearch-Go\" width=\"200\" height=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMeilisearch Go\u003c/h1\u003e\n\n\u003ch4 align=\"center\"\u003e\n  \u003ca href=\"https://github.com/meilisearch/meilisearch\"\u003eMeilisearch\u003c/a\u003e |\n\u003ca href=\"https://www.meilisearch.com/cloud?utm_campaign=oss\u0026utm_source=github\u0026utm_medium=meilisearch-go\"\u003eMeilisearch Cloud\u003c/a\u003e |\n  \u003ca href=\"https://www.meilisearch.com/docs\"\u003eDocumentation\u003c/a\u003e |\n  \u003ca href=\"https://discord.meilisearch.com\"\u003eDiscord\u003c/a\u003e |\n  \u003ca href=\"https://roadmap.meilisearch.com/tabs/1-under-consideration\"\u003eRoadmap\u003c/a\u003e |\n  \u003ca href=\"https://www.meilisearch.com\"\u003eWebsite\u003c/a\u003e |\n  \u003ca href=\"https://www.meilisearch.com/docs/faq\"\u003eFAQ\u003c/a\u003e\n\u003c/h4\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/meilisearch/meilisearch-go/actions\"\u003e\u003cimg src=\"https://github.com/meilisearch/meilisearch-go/workflows/Tests/badge.svg\" alt=\"GitHub Workflow Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/meilisearch/meilisearch-go\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/meilisearch/meilisearch-go\" alt=\"Test\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/meilisearch/meilisearch-go\"\u003e\u003cimg src=\"https://codecov.io/gh/meilisearch/meilisearch-go/branch/main/graph/badge.svg?token=8N6N60D5UI\" alt=\"CodeCov\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/meilisearch/meilisearch-go\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/meilisearch/meilisearch-go.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/meilisearch/meilisearch-go/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-informational\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://ms-bors.herokuapp.com/repositories/58\"\u003e\u003cimg src=\"https://bors.tech/images/badge_small.svg\" alt=\"Bors enabled\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e⚡ The Meilisearch API client written for Golang\u003c/p\u003e\n\n**Meilisearch Go** is the Meilisearch API client for Go developers.\n\n**Meilisearch** is an open-source search engine. [Learn more about Meilisearch.](https://github.com/meilisearch/Meilisearch)\n\n## Table of Contents\n\n- [📖 Documentation](#-documentation)\n- [🔧 Installation](#-installation)\n- [🚀 Getting started](#-getting-started)\n  - [Add documents](#add-documents)\n  - [Basic search](#basic-search)\n  - [Custom search](#custom-search)\n  - [Custom search with filter](#custom-search-with-filters)\n  - [Customize client](#customize-client)\n- [🤖 Compatibility with Meilisearch](#-compatibility-with-meilisearch)\n- [⚡️ Benchmark performance](#-benchmark-performance)\n- [💡 Learn more](#-learn-more)\n- [⚙️ Contributing](#️-contributing)\n\n## 📖 Documentation\n\nThis readme contains all the documentation you need to start using this Meilisearch SDK.\n\nFor general information on how to use Meilisearch—such as our API reference, tutorials, guides, and in-depth articles—refer to our [main documentation website](https://www.meilisearch.com/docs/).\n\n\n## 🔧 Installation\n\nWith `go get` in command line:\n```bash\ngo get github.com/meilisearch/meilisearch-go\n```\n\n### Run Meilisearch \u003c!-- omit in toc --\u003e\n\n⚡️ **Launch, scale, and streamline in minutes with Meilisearch Cloud**—no maintenance, no commitment, cancel anytime. [Try it free now](https://cloud.meilisearch.com/login?utm_campaign=oss\u0026utm_source=github\u0026utm_medium=meilisearch-go).\n\n🪨  Prefer to self-host? [Download and deploy](https://www.meilisearch.com/docs/learn/self_hosted/getting_started_with_self_hosted_meilisearch?utm_campaign=oss\u0026utm_source=github\u0026utm_medium=meilisearch-go) our fast, open-source search engine on your own infrastructure.\n\n## 🚀 Getting started\n\n#### Add documents\n\n```go\npackage main\n\nimport (\n\t\"fmt\"\n\t\"os\"\n\n\t\"github.com/meilisearch/meilisearch-go\"\n)\n\nfunc main() {\n\tclient := meilisearch.New(\"http://localhost:7700\", meilisearch.WithAPIKey(\"foobar\"))\n\n\t// An index is where the documents are stored.\n\tindex := client.Index(\"movies\")\n\n\t// If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.\n\tdocuments := []map[string]interface{}{\n        { \"id\": 1, \"title\": \"Carol\", \"genres\": []string{\"Romance\", \"Drama\"} },\n        { \"id\": 2, \"title\": \"Wonder Woman\", \"genres\": []string{\"Action\", \"Adventure\"} },\n        { \"id\": 3, \"title\": \"Life of Pi\", \"genres\": []string{\"Adventure\", \"Drama\"} },\n        { \"id\": 4, \"title\": \"Mad Max: Fury Road\", \"genres\": []string{\"Adventure\", \"Science Fiction\"} },\n        { \"id\": 5, \"title\": \"Moana\", \"genres\": []string{\"Fantasy\", \"Action\"} },\n        { \"id\": 6, \"title\": \"Philadelphia\", \"genres\": []string{\"Drama\"} },\n\t}\n\ttask, err := index.AddDocuments(documents)\n\tif err != nil {\n\t\tfmt.Println(err)\n\t\tos.Exit(1)\n\t}\n\n\tfmt.Println(task.TaskUID)\n}\n```\n\nWith the `taskUID`, you can check the status (`enqueued`, `canceled`, `processing`, `succeeded` or `failed`) of your documents addition using the [task endpoint](https://www.meilisearch.com/docs/reference/api/tasks).\n\n#### Basic Search\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"os\"\n\n    \"github.com/meilisearch/meilisearch-go\"\n)\n\nfunc main() {\n    // Meilisearch is typo-tolerant:\n    searchRes, err := client.Index(\"movies\").Search(\"philoudelphia\",\n        \u0026meilisearch.SearchRequest{\n            Limit: 10,\n        })\n    if err != nil {\n        fmt.Println(err)\n        os.Exit(1)\n    }\n\n    fmt.Println(searchRes.Hits)\n}\n```\n\nJSON output:\n```json\n{\n  \"hits\": [{\n    \"id\": 6,\n    \"title\": \"Philadelphia\",\n    \"genres\": [\"Drama\"]\n  }],\n  \"offset\": 0,\n  \"limit\": 10,\n  \"processingTimeMs\": 1,\n  \"query\": \"philoudelphia\"\n}\n```\n\n#### Custom Search\n\nAll the supported options are described in the [search parameters](https://www.meilisearch.com/docs/reference/api/search#search-parameters) section of the documentation.\n\n```go\nfunc main() {\n    searchRes, err := client.Index(\"movies\").Search(\"wonder\",\n        \u0026meilisearch.SearchRequest{\n            AttributesToHighlight: []string{\"*\"},\n        })\n    if err != nil {\n        fmt.Println(err)\n        os.Exit(1)\n    }\n\n    fmt.Println(searchRes.Hits)\n}\n```\n\nJSON output:\n```json\n{\n    \"hits\": [\n        {\n            \"id\": 2,\n            \"title\": \"Wonder Woman\",\n            \"genres\": [\"Action\", \"Adventure\"],\n            \"_formatted\": {\n                \"id\": 2,\n                \"title\": \"\u003cem\u003eWonder\u003c/em\u003e Woman\"\n            }\n        }\n    ],\n    \"offset\": 0,\n    \"limit\": 20,\n    \"processingTimeMs\": 0,\n    \"query\": \"wonder\"\n}\n```\n\n#### Custom Search With Filters\n\nIf you want to enable filtering, you must add your attributes to the `filterableAttributes` index setting.\n\n```go\ntask, err := index.UpdateFilterableAttributes(\u0026[]string{\"id\", \"genres\"})\n```\n\nYou only need to perform this operation once.\n\nNote that Meilisearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take time. You can track the process using the [task status](https://www.meilisearch.com/docs/learn/advanced/asynchronous_operations).\n\nThen, you can perform the search:\n\n```go\nsearchRes, err := index.Search(\"wonder\",\n    \u0026meilisearch.SearchRequest{\n        Filter: \"id \u003e 1 AND genres = Action\",\n    })\n```\n\n```json\n{\n  \"hits\": [\n    {\n      \"id\": 2,\n      \"title\": \"Wonder Woman\",\n      \"genres\": [\"Action\",\"Adventure\"]\n    }\n  ],\n  \"offset\": 0,\n  \"limit\": 20,\n  \"estimatedTotalHits\": 1,\n  \"processingTimeMs\": 0,\n  \"query\": \"wonder\"\n}\n```\n\n#### Customize Client\n\nThe client supports many customization options:\n\n- `WithCustomClient` sets a custom `http.Client`.\n- `WithCustomClientWithTLS` enables TLS for the HTTP client.\n- `WithAPIKey` sets the API key or master [key](https://www.meilisearch.com/docs/reference/api/keys).\n- `WithContentEncoding` configures [content encoding](https://www.meilisearch.com/docs/reference/api/overview#content-encoding) for requests and responses. Currently, gzip, deflate, and brotli are supported.\n- `WithCustomRetries` customizes retry behavior based on specific HTTP status codes (`retryOnStatus`, defaults to 502, 503, and 504) and allows setting the maximum number of retries.\n- `DisableRetries` disables the retry logic. By default, retries are enabled.\n\n```go\npackage main\n\nimport (\n    \"net/http\"\n    \"github.com/meilisearch/meilisearch-go\"\n)\n\nfunc main() {\n\tclient := meilisearch.New(\"http://localhost:7700\",\n        meilisearch.WithAPIKey(\"foobar\"),\n        meilisearch.WithCustomClient(http.DefaultClient),\n        meilisearch.WithContentEncoding(meilisearch.GzipEncoding, meilisearch.BestCompression),\n        meilisearch.WithCustomRetries([]int{502}, 20),\n    )\n}\n```\n\n## 🤖 Compatibility with Meilisearch\n\nThis package guarantees compatibility with [version v1.x of Meilisearch](https://github.com/meilisearch/meilisearch/releases/latest), but some features may not be present. Please check the [issues](https://github.com/meilisearch/meilisearch-go/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.\n\n## ⚡️ Benchmark Performance\n\nThe Meilisearch client performance was tested in [client_bench_test.go](/client_bench_test.go).\n\n```shell\ngoos: linux\ngoarch: amd64\npkg: github.com/meilisearch/meilisearch-go\ncpu: AMD Ryzen 7 5700U with Radeon Graphics\n```\n\n**Results**\n\n```shell\nBenchmark_ExecuteRequest-16                  \t   10000\t    105880 ns/op\t    7241 B/op\t      87 allocs/op\nBenchmark_ExecuteRequestWithEncoding-16      \t    2716\t    455548 ns/op\t 1041998 B/op\t     169 allocs/op\nBenchmark_ExecuteRequestWithoutRetries-16    \t       1\t3002787257 ns/op\t   56528 B/op\t     332 allocs/op\n```\n\n## 💡 Learn more\n\nThe following sections in our main documentation website may interest you:\n\n- **Manipulate documents**: see the [API references](https://www.meilisearch.com/docs/reference/api/documents) or read more about [documents](https://www.meilisearch.com/docs/learn/core_concepts/documents).\n- **Search**: see the [API references](https://www.meilisearch.com/docs/reference/api/search) or follow our guide on [search parameters](https://www.meilisearch.com/docs/reference/api/search#search-parameters).\n- **Manage the indexes**: see the [API references](https://www.meilisearch.com/docs/reference/api/indexes) or read more about [indexes](https://www.meilisearch.com/docs/learn/core_concepts/indexes).\n- **ClientConfigure the index settings**: see the [API references](https://www.meilisearch.com/docs/reference/api/settings) or follow our guide on [settings parameters](https://www.meilisearch.com/docs/reference/api/settings#settings_parameters).\n\n## ⚙️ Contributing\n\nAny new contribution is more than welcome in this project!\n\nIf you want to know more about the development workflow or want to contribute, please visit our [contributing guidelines](/CONTRIBUTING.md) for detailed instructions!\n\n\u003chr\u003e\n\n**Meilisearch** provides and maintains many **SDKs and Integration tools** like this one. We want to provide everyone with an **amazing search experience for any kind of project**. If you want to contribute, make suggestions, or just know what's going on right now, visit us in the [integration-guides](https://github.com/meilisearch/integration-guides) repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeilisearch%2Fmeilisearch-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeilisearch%2Fmeilisearch-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeilisearch%2Fmeilisearch-go/lists"}