|
| 1 | +# v0.28.0 release changelogs |
| 2 | + |
| 3 | +The main goal of this new release is to stabilize the Meilisearch API 🚀 |
| 4 | + |
| 5 | +This release introduces a lot of breaking changes (especially regarding names), and we are sorry for this. The purpose is to guarantee what we care about the most—providing the best search engine experience—by stabilizing the Meilisearch API. There should not be any breaking changes to the API in the future. |
| 6 | + |
| 7 | +<!-- The following line should NOT be put in the official release changelogs --> |
| 8 | +⚠️ Since this is a release candidate (RC), the official documentation is not updated yet, but will be ready for the official v0.28.0 release. The work-in-progress documentation is available [here](). |
| 9 | + |
| 10 | +# New features 🚀 |
| 11 | + |
| 12 | +## Smart crop |
| 13 | + |
| 14 | +The smart crop is an improvement of the Meilisearch crop. |
| 15 | + |
| 16 | +The cropping algorithm tries to find the window(s) with the highest density of query terms within the `cropLength` limit. From these, it picks the window that contains the most query terms in order. |
| 17 | + |
| 18 | +Done by @ManyTheFish (#2408) |
| 19 | + |
| 20 | +## API key management: deterministic keys |
| 21 | + |
| 22 | +- It is now possible to create a deterministic `key` value by specifying a `uid` field at creation. `uid` value must be a UUID v4. If omitted, Meilisearch generates it. |
| 23 | + |
| 24 | +The [`key`](/reference/api/keys.md#key) field is generated by hashing the master key and the [`uid`](/reference/api/keys.md#uid): |
| 25 | + |
| 26 | +```bash |
| 27 | +echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY |
| 28 | +``` |
| 29 | + |
| 30 | +As a result, `key` values are deterministic between instances sharing the same configuration. Since the `key` field depends on the master key, it is not propagated to dumps and snapshots. If a malicious user ever gets access to your dumps or snapshots, they will not have access to your instance's API keys. |
| 31 | + |
| 32 | +- Adds a `name` field: specify a human-readable `name` to make API key retrieval more convenient. |
| 33 | +- Introduces new actions to manage API keys (`keys.get`, `keys.create`, `keys.update`, `keys.delete`). |
| 34 | +- It is no longer possible to update an API key's `actions`, `indexes`, or `expiresAt` after creation. |
| 35 | + |
| 36 | +Done by @ManyTheFish in #2438, #2451, #2475, and #2474) |
| 37 | + |
| 38 | +## Hebrew language support |
| 39 | + |
| 40 | +New language support: Hebrew, using the [Niqqud library](https://github.com/benny-n/niqqud). |
| 41 | + |
| 42 | +Done by the amazing @benny-n in meilisearch/charabia#101. |
| 43 | + |
| 44 | +## New tokenizer contribution experience: add your language to Meilisearch |
| 45 | + |
| 46 | +The contribution experience in the tokenizer has been significantly improved. |
| 47 | + |
| 48 | +If your language is missing in Meilisearch, please consider contributing to [the Meilisearch tokenizer](https://github.com/meilisearch/charabia) by following the CONTRIBUTING.md file and integrating your intended normalizer/segmenter. |
| 49 | + |
| 50 | +The whole core team is available to help you contribute. Feel free to ask for any clarifications you need! |
| 51 | + |
| 52 | +Done by @ManyTheFish, @loiclec @gmourier, and @curquiza. |
| 53 | + |
| 54 | +## Customizable limits |
| 55 | + |
| 56 | +### Limit of facet values |
| 57 | + |
| 58 | +When searching using the `facets` search parameter, Meilisearch will now return a maximum of 100 different facet values per faceted attribute. |
| 59 | + |
| 60 | +This default limit is customizable using the new `faceting` setting, accessible via the `/indexes/{uid}/settings/faceting` route. |
| 61 | + |
| 62 | +To increase this limit to 3000: |
| 63 | + |
| 64 | +```bash |
| 65 | +curl \ |
| 66 | + -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \ |
| 67 | + -H 'Content-Type: application/json' \ |
| 68 | + --data-binary '{ |
| 69 | + "maxValuesPerFacet": 3000 |
| 70 | + }' |
| 71 | +``` |
| 72 | + |
| 73 | +You can also get the value using the HTTP `GET` verb, or reset the value using the `DELETE` verb. |
| 74 | + |
| 75 | +Done by @Kerollmops in meilisearch/milli#550 and #2494 |
| 76 | + |
| 77 | +### Limit of documents returned by search |
| 78 | + |
| 79 | +When making a search request, Meilisearch returns a maximum of 1000 documents: the documents deemed most relevant to the query. |
| 80 | + |
| 81 | +This default limit is now customizable using the `pagination` setting, accessible via the `/indexes/{uid}/settings/pagination` route. |
| 82 | + |
| 83 | +To increase this limit to 2000: |
| 84 | + |
| 85 | +```bash |
| 86 | +curl \ |
| 87 | + -X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \ |
| 88 | + -H 'Content-Type: application/json' \ |
| 89 | + --data-binary '{ |
| 90 | + "maxTotalHits": 2000 |
| 91 | + }' |
| 92 | +``` |
| 93 | + |
| 94 | +You can also get the value using the HTTP `GET` verb, or reset the value using the `DELETE` verb. |
| 95 | + |
| 96 | +Done by @Kerollmops in meilisearch/milli#550 and #2494 |
| 97 | + |
| 98 | +# Breaking changes and improvement ⚠️ |
| 99 | + |
| 100 | +<!-- The following line should only be put in the official release changelogs, not for the RC --> |
| 101 | +For most of the following changes, if you use [one of our SDKs](https://docs.meilisearch.com/learn/what_is_meilisearch/sdks.html), these changes will be transparent for you by only updating to the latest version of the SDK. |
| 102 | + |
| 103 | +## Changes in `/indexes/{uid}/search` endpoint |
| 104 | + |
| 105 | +- `nbHits` is renamed `estimatedTotalHits`. Some users were confused by the old name and used it for their pagination, which we discourage. Please check out this [fresh new guide](https://docs.meilisearch.com/learn/advanced/pagination.html) to learn how to paginate with Meilisearch without using `nbHits`. |
| 106 | +- The `facetsDistribution` search parameter is renamed `facets` |
| 107 | +- The `facetsDistribution` field in the response body is renamed `facetDistribution` |
| 108 | +- The `matches` search parameter is renamed `showMatchesPosition` |
| 109 | +- The `_matchesInfo` field in the response body is renamed `_matchesPosition` |
| 110 | +- `exhaustiveNbHits` and `exhaustiveFacetsCount` are removed. Meilisearch does not return exhaustive hit or facet counts at this time. |
| 111 | + |
| 112 | +Done by @irevoire in #2406. |
| 113 | + |
| 114 | +## Changes in `/indexes` endpoints |
| 115 | + |
| 116 | +- When getting the index list (`GET /indexes`), the response is now paginated. That means: |
| 117 | + - You can use the `offset` and `limit` parameters to browse indexes. |
| 118 | + - The indexes are returned in the `results` field in the response body. |
| 119 | + - `limit`, `offset`, and `total` now appear in the response body. |
| 120 | +- The endpoint to update an index is now `PATCH /indexes/{indexUid}` instead of `PUT` |
| 121 | +- The already deprecated `name` field has now been removed entirely. |
| 122 | + |
| 123 | +Done by @irevoire and @Kerollmops in #2423, #2452, and #2454. |
| 124 | + |
| 125 | +## Changes in `indexes/{uid}/documents` endpoints |
| 126 | + |
| 127 | +- When getting the documents list (`GET /indexes/{uid}/documents`), pagination has been improved. That means: |
| 128 | + - You can still use the `offset` and `limit` parameters to browse documents. |
| 129 | + - The documents are returned in the `results` field in the response body. |
| 130 | + - `limit`, `offset`, and `total` now appear in the response body. |
| 131 | +- When getting documents via the `GET /indexes/{uid}/documents` route, the `attributesToRetrieve` parameter has been renamed `fields` |
| 132 | +- The `fields` parameter is also available for the `GET /indexes/{uid}/documents/{document_uid}` endpoint. |
| 133 | +- The [`displayedAttributes` setting](https://docs.meilisearch.com/reference/api/displayed_attributes.html) does not impact `GET indexes/{uid}/documents` anymore. |
| 134 | + |
| 135 | +Done by @irevoire in #2372, #2433, and #2454. |
| 136 | + |
| 137 | +## Changes in `/tasks` and `/indexes/{uid}/tasks` endpoints |
| 138 | + |
| 139 | +- You can now filter on the `GET /tasks` endpoint: |
| 140 | + - Filtering is possible on the `type`, `status`, and `indexUid` fields. |
| 141 | + - Use the `,` character to specify several values for a filter, e.g. `?status=enqueued,processing`. This is equivalent to an `OR` operation. |
| 142 | + - Use the `&` character to apply multiple filters, e.g. `?status=enqueued&type=indexCreation`. This is equivalent to an `AND` operation. |
| 143 | +- Add keyset pagination on the `GET /tasks` endpoint, allowing users to browse multiple sets of `task` items. |
| 144 | + - Use the `limit` and `from` query parameters to browse tasks. |
| 145 | + - `limit`, `from`, and `next` now appear in the response body. |
| 146 | +- `GET /indexes/:indexUid/tasks` has been removed. It can be replaced by `GET /tasks?indexUid=:indexUid` |
| 147 | +- `GET /indexes/:indexUid/tasks/:taskUid` has been removed. |
| 148 | +- `uid` has been renamed `taskUid` in the response body returned by every asynchronous task (e.g. index creation, document addition, etc...) |
| 149 | +- Some task properties have been renamed |
| 150 | + - `documentPartial`-> `documentAdditionOrUpdate` |
| 151 | + - `documentAddition`-> `documentAdditionOrUpdate` |
| 152 | + - `clearAll` -> `documentDeletion` |
| 153 | + |
| 154 | +Done by Kerollmops in #2399 and #2445. |
| 155 | + |
| 156 | +## Changes regarding dumps |
| 157 | + |
| 158 | +- Dump creation is now an asynchronous task. |
| 159 | +- Dump tasks are placed at the end of the task queue, but processed in priority. |
| 160 | + - In other words, a dump will run as soon as the current task is finished processing. |
| 161 | + - The dump's `uid` will reflect when it was enqueued in relation to the other tasks, not when it was processed. |
| 162 | +- `POST /dumps` now returns `202` like any other asynchronous operation (e.g. index creation, document addition...) |
| 163 | +- The `GET /dumps/:dump_uid/status` endpoint has been removed. It can be replaced by `GET /tasks?type=dumpCreation`. |
| 164 | +- The `dump_already_processing` error has been removed since dumps can now be enqueued. |
| 165 | + |
| 166 | +Done by @MarinPostma in #2410 |
| 167 | + |
| 168 | +## Changes in `/keys` endpoint |
| 169 | + |
| 170 | +- Tenant tokens: `apiKeyPrefix` has been renamed `apiKeyUid`. |
| 171 | +- It is no longer possible to update `actions`, `indexes`, or `expiresAt` after key creation. Only the `name` and `description` fields are updatable. |
| 172 | +- When getting the keys list (`GET /keys`), the response is now paginated. That means: |
| 173 | + - You can use the `offset` and `limit` parameters to browse keys. |
| 174 | + - `limit`, `offset`, and `total` now appear in the response body. |
| 175 | +- Due to changes to the `keys` resource, dumps are not fully compatible with API keys. As a result, keys imported from an old version of Meilisearch will have their `key` and `uid` fields regenerated. In other words, **you will need to update your keys**. Other key fields such as `actions` and `indexes` will not be affected. |
| 176 | +- The `dumps.get` action has been removed. |
| 177 | + |
| 178 | +Done by @ManyTheFish in #2438, #2451, #2475, and #2474) |
| 179 | + |
| 180 | +## Changes in `/indexes/{uid}/settings` endpoints |
| 181 | + |
| 182 | +The following changes only concern the HTTP verb associated with a given method. |
| 183 | + |
| 184 | +- The endpoint to update the global settings is now `PATCH /indexes/{indexUid}/settings` instead of `POST` |
| 185 | +- The endpoint to update the typo tolerance settings is now `PATCH /indexes/{indexUid}/settings/typo-tolerance` instead of `POST` |
| 186 | +- The endpoint to update the displayed attributes settings is now `PUT /indexes/{indexUid}/settings/displayed-attributes` instead of `POST` |
| 187 | +- The endpoint to update the distinct attribute settings is now `PUT /indexes/{indexUid}/settings/distinct-attribute` instead of `POST` |
| 188 | +- The endpoint to update the filterable attribute settings is now `PUT /indexes/{indexUid}/settings/filterable-attributes` instead of `POST` |
| 189 | +- The endpoint to update the ranking rules settings is now `PUT /indexes/{indexUid}/settings/ranking-rules` instead of `POST` |
| 190 | +- The endpoint to update the searchable attributes settings is now `PUT /indexes/{indexUid}/settings/searchable-attributes` instead of `POST` |
| 191 | +- The endpoint to update the sortable attributes settings is now `PUT /indexes/{indexUid}/settings/sortable-attributes` instead of `POST` |
| 192 | +- The endpoint to update the stop words settings is now `PUT /indexes/{indexUid}/settings/stop-words` instead of `POST` |
| 193 | +- The endpoint to update the synonyms settings is now `PUT /indexes/{indexUid}/settings/synonyms` instead of `POST` |
| 194 | + |
| 195 | +Done by @Kerollmops in #2452 |
| 196 | + |
| 197 | +# Other improvements 🔨 |
| 198 | + |
| 199 | +- Geosearch: Support string type for `_geo`, `lat`, and `lng` fields (#2408 and meilisearch/milli#523) @irevoire |
| 200 | +- Improve ranking rules error message (meilisearch/milli#536, #2468) @matthias-wright |
| 201 | +- Improve docker CI: push vX.Y tag (without patch) to Docker Hub (#2529) @janithpet |
| 202 | +- Remove the connection keep-alive timeout (#2471) @Thearas |
| 203 | +- Improve index uid validation upon API key creation (#2414) @pierre-l |
| 204 | +- Improve `estimatedTotalHits` behavior with distinct attribute (#2546) @Kerollmops |
| 205 | + |
| 206 | +# Fixes 🐞 |
| 207 | + |
| 208 | +- Fix filtering on documents with double and/or single quote characters (#2500 and meilisearch/milli#552) @irevoire |
| 209 | + |
| 210 | +# Misc |
| 211 | + |
| 212 | +- Telemetry: handle the `X-Meilisearch-Client` header (#2374) @irevoire |
| 213 | +- Telemetry: send the analytics to `telemetry.meilisearch.com` instead of segment (#2429) @irevoire |
| 214 | +- Create custom error types for `TaskType`, `TaskStatus`, and `IndexUid` (#2460) @walterbm |
| 215 | +- Improve the Docker CIs (#2477 and #2491) @choznerol and @curquiza |
| 216 | +- Some internal changes (#2447, #2464, #2453, #2455) @MarinPostma @Kerollmops |
| 217 | +- Update dependencies (#2450) @Kerollmops |
| 218 | +- Add dump tests in CI (#2357) @irevoire |
| 219 | +- Deny warnings in CI (#2339) @MarinPostma |
| 220 | +- Update mini-dashboard for v0.28.0 (#2587) @mdubus @bidoubiwa |
| 221 | +- Change Nelson path (#2347) @curquiza |
| 222 | +- Re-integrate Clippy in the CI (#2424) @irevoire |
| 223 | +- Fix typo in README (#2448) @ryanrussell |
| 224 | +- Fix typo in code base comments (#2459, and #2508) @ryanrussel |
| 225 | +- Update url of `movies.json` in README (#2422) @0x0x1 |
| 226 | +- Fix command in README (#2434) @0x0x1 |
| 227 | + |
| 228 | +---- |
| 229 | + |
| 230 | +❤️ Thanks again to our external contributors: |
| 231 | +- [Meilisearch](https://github.com/meilisearch/meilisearch): @0x0x1, @choznerol, @janithpet, @pierre-l, @ryanrussel, @Thearas, and @walterbm |
| 232 | +- [Milli](https://github.com/meilisearch/milli): @matthias-wright |
| 233 | +- [Charabia](https://github.com/meilisearch/charabia): @benny-n |
0 commit comments