{"id":13721431,"url":"https://github.com/meilisearch/meilisearch-java","last_synced_at":"2025-05-07T13:32:44.831Z","repository":{"id":37984034,"uuid":"237707489","full_name":"meilisearch/meilisearch-java","owner":"meilisearch","description":"Java client for Meilisearch","archived":false,"fork":false,"pushed_at":"2025-05-01T04:13:32.000Z","size":2372,"stargazers_count":205,"open_issues_count":33,"forks_count":123,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-01T05:20:26.944Z","etag":null,"topics":["client","meilisearch","sdk"],"latest_commit_sha":null,"homepage":"https://meilisearch.com","language":"Java","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,"zenodo":null}},"created_at":"2020-02-02T02:29:46.000Z","updated_at":"2025-04-29T15:14:42.000Z","dependencies_parsed_at":"2023-11-22T14:45:48.664Z","dependency_job_id":"4dd34579-6448-4b7f-8920-0d2a805ec3fd","html_url":"https://github.com/meilisearch/meilisearch-java","commit_stats":null,"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meilisearch%2Fmeilisearch-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meilisearch","download_url":"https://codeload.github.com/meilisearch/meilisearch-java/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252886891,"owners_count":21819801,"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","meilisearch","sdk"],"created_at":"2024-08-03T01:01:16.967Z","updated_at":"2025-05-07T13:32:44.819Z","avatar_url":"https://github.com/meilisearch.png","language":"Java","funding_links":[],"categories":["others","Integrations"],"sub_categories":["Official Integrations"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/meilisearch/integration-guides/main/assets/logos/meilisearch_java.svg\" alt=\"Meilisearch Java\" width=\"200\" height=\"200\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMeilisearch Java\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-java\"\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://maven-badges.herokuapp.com/maven-central/com.meilisearch.sdk/meilisearch-java\"\u003e\u003cimg src=\"https://maven-badges.herokuapp.com/maven-central/com.meilisearch.sdk/meilisearch-java/badge.svg\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/meilisearch/meilisearch-java/actions\"\u003e\u003cimg src=\"https://github.com/meilisearch/meilisearch-java/workflows/Tests/badge.svg\" alt=\"Tests\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/meilisearch/meilisearch-java/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/60\"\u003e\u003cimg src=\"https://bors.tech/images/badge_small.svg\" alt=\"Bors enabled\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/meilisearch/meilisearch-java\"\u003e\u003cimg src=\"https://codecov.io/gh/meilisearch/meilisearch-java/branch/main/graph/badge.svg\" alt=\"Code Coverage\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e⚡ The Meilisearch API client written for Java ☕️\u003c/p\u003e\n\n**Meilisearch Java** is the Meilisearch API client for Java developers.\n\n**Meilisearch** is an open-source search engine. [Learn more about Meilisearch.](https://github.com/meilisearch/meilisearch)\n\n## Table of Contents \u003c!-- omit in TOC --\u003e\n\n- [📖 Documentation](#-documentation)\n- [🔧 Installation](#-installation)\n- [🚀 Getting started](#-getting-started)\n- [🛠 Customization](#-customization)\n- [🤖 Compatibility with Meilisearch](#-compatibility-with-meilisearch)\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\n## 🔧 Installation\n\n`meilisearch-java` is available from JCentral official repository. To be able to import this package, declare it as a dependency in your project:\n\n### Maven \u003c!-- omit in toc --\u003e\n\nAdd the following code to the `\u003cdependencies\u003e` section of your project:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.meilisearch.sdk\u003c/groupId\u003e\n  \u003cartifactId\u003emeilisearch-java\u003c/artifactId\u003e\n  \u003cversion\u003e0.14.4\u003c/version\u003e\n  \u003ctype\u003epom\u003c/type\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle \u003c!-- omit in toc --\u003e\n\nAdd the following line to the `dependencies` section of your `build.gradle`:\n\n```groovy\nimplementation 'com.meilisearch.sdk:meilisearch-java:0.14.4'\n```\n\n:warning: `meilisearch-java` also requires `okhttp` as a peer dependency.\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-java).\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-java) our fast, open-source search engine on your own infrastructure.\n\n## 🚀 Getting started\n\n#### Add documents \u003c!-- omit in toc --\u003e\n\n```java\npackage com.meilisearch.sdk;\n\nimport org.json.JSONArray;\nimport org.json.JSONObject;\n\nimport java.util.ArrayList;\n\nclass TestMeilisearch {\n  public static void main(String[] args) throws Exception {\n\n    JSONArray array = new JSONArray();\n    ArrayList items = new ArrayList() {{\n      add(new JSONObject().put(\"id\", \"1\").put(\"title\", \"Carol\").put(\"genres\",new JSONArray(\"[\\\"Romance\\\",\\\"Drama\\\"]\")));\n      add(new JSONObject().put(\"id\", \"2\").put(\"title\", \"Wonder Woman\").put(\"genres\",new JSONArray(\"[\\\"Action\\\",\\\"Adventure\\\"]\")));\n      add(new JSONObject().put(\"id\", \"3\").put(\"title\", \"Life of Pi\").put(\"genres\",new JSONArray(\"[\\\"Adventure\\\",\\\"Drama\\\"]\")));\n      add(new JSONObject().put(\"id\", \"4\").put(\"title\", \"Mad Max: Fury Road\").put(\"genres\",new JSONArray(\"[\\\"Adventure\\\",\\\"Science Fiction\\\"]\")));\n      add(new JSONObject().put(\"id\", \"5\").put(\"title\", \"Moana\").put(\"genres\",new JSONArray(\"[\\\"Fantasy\\\",\\\"Action\\\"]\")));\n      add(new JSONObject().put(\"id\", \"6\").put(\"title\", \"Philadelphia\").put(\"genres\",new JSONArray(\"[\\\"Drama\\\"]\")));\n    }};\n\n    array.put(items);\n    String documents = array.getJSONArray(0).toString();\n    Client client = new Client(new Config(\"http://localhost:7700\", \"masterKey\"));\n\n    // An index is where the documents are stored.\n    Index index = client.index(\"movies\");\n\n    // If the index 'movies' does not exist, Meilisearch creates it when you first add the documents.\n    index.addDocuments(documents); // =\u003e { \"taskUid\": 0 }\n  }\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 \u003c!-- omit in toc --\u003e\n\nA basic search can be performed by calling `index.search()` method, with a simple string query.\n\n```java\nimport com.meilisearch.sdk.model.SearchResult;\n\n// Meilisearch is typo-tolerant:\nSearchResult results = index.search(\"carlo\");\nSystem.out.println(results);\n```\n\n- Output:\n\n```\nSearchResult(hits=[{id=1.0, title=Carol, genres:[Romance, Drama]}], offset=0, limit=20, estimatedTotalHits=1, facetDistribution=null, processingTimeMs=3, query=carlo)\n```\n\n#### Custom Search \u003c!-- omit in toc --\u003e\n\nIf you want a custom search, the easiest way is to create a `SearchRequest` object, and set the parameters that you need.\u003cbr\u003e\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```java\nimport com.meilisearch.sdk.SearchRequest;\n\n// ...\n\nSearchResult results = (SearchResult) index.search(\n    new SearchRequest(\"of\")\n        .setShowMatchesPosition(true)\n        .setAttributesToHighlight(new String[]{\"title\"})\n);\nSystem.out.println(results.getHits());\n```\n\n- Output:\n\n```json\n[{\n  \"id\":3,\n  \"title\":\"Life of Pi\",\n  \"genres\":[\"Adventure\",\"Drama\"],\n  \"_formatted\":{\n    \"id\":3,\n    \"title\":\"Life \u003cem\u003eof\u003c/em\u003e Pi\",\n    \"genres\":[\"Adventure\",\"Drama\"]\n  },\n  \"_matchesPosition\":{\n    \"title\":[{\n      \"start\":5.0,\n      \"length\":2.0\n    }]\n  }\n}]\n```\n#### Custom Search With Filters \u003c!-- omit in toc --\u003e\n\nIf you want to enable filtering, you must add your attributes to the `filterableAttributes` index setting.\n\n```java\nindex.updateFilterableAttributesSettings(new String[]\n{\n  \"id\",\n  \"genres\"\n});\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/reference/api/tasks).\n\nThen, you can perform the search:\n\n```java\nindex.search(\n  new SearchRequest(\"wonder\")\n  .setFilter(new String[] {\"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#### Custom Search With Pagination \u003c!-- omit in toc --\u003e\n\n```java\nimport com.meilisearch.sdk.SearchResultPaginated;\n\n// ...\n\nSearchResultPaginated results = (SearchResultPaginated) index.search(\n    new SearchRequest(\"wonder\")\n        .setPage(1)\n        .setHitsPerPage(20)\n);\n```\n\n```json\n{\n    \"hits\": [\n        {\n            \"id\": 2,\n            \"title\": \"Wonder Woman\",\n            \"genres\": [\"Action\",\"Adventure\"]\n        }\n    ], \n    \"query\": \"wonder\",\n    \"processingTimeMs\": 0,\n    \"hitsPerPage\": 20,\n    \"page\": 1,\n    \"totalPages\": 1,\n    \"totalHits\": 1\n}\n```\n\n## 🛠 Customization\n\n### JSON \u003c!-- omit in toc --\u003e\n\n#### Default JSON `GsonJsonHandler` \u003c!-- omit in toc --\u003e\n\nThe default JSON library is `Gson`. You can however use another library with the `JsonHandler` Class.\n\n*Notes*: We strongly recommend using the `Gson` library.\n\n#### Using `JacksonJsonHandler` \u003c!-- omit in toc --\u003e\n\nInitialize your `Config` and assign it a new `JacksonJsonHandler` object as `JsonHandler`.\nSet up your `Client` with it.\n\n```java\nimport com.meilisearch.sdk.json.JacksonJsonHandler;\n\nConfig config = new Config(\"http://localhost:7700\", \"masterKey\", new JacksonJsonHandler());\nClient client = new Client(config);\n```\n\n#### Use a Custom `JsonHandler` \u003c!-- omit in toc --\u003e\n\nTo create your own JSON handler, you must conform to the `JsonHandler` interface by implementing its two methods.\n\n```java\n    String encode(Object o) throws Exception;\n\n    \u003cT\u003e T decode(Object o, Class\u003c?\u003e targetClass, Class\u003c?\u003e... parameters) throws Exception;\n```\n\n Then create your client by initializing your `Config` with your new handler.\n\n```java\nConfig config = new Config(\"http://localhost:7700\", \"masterKey\", new myJsonHandler());\nClient client = new Client(config);\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-java/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+label%3Aenhancement) for more info.\n\nThis SDK is compatible with the following JDK versions:\n\n| SDK Version | Supported Java Versions |\n|-------------|-------------------------|\n| v1.x        | JDK 8 and above         |\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- **Configure 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-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeilisearch%2Fmeilisearch-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeilisearch%2Fmeilisearch-java/lists"}