⚠️ If possible, use v0.28.1 instead of this version (v0.28.0) to include the highlight fix available in v0.28.1

The main goal of this new release is to stabilize the Meilisearch API 🚀

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.

New features 🚀

Smart crop

The smart crop is an improvement of the Meilisearch crop.

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.

Done by @ManyTheFish (#2408)

API key management: deterministic keys

• 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.

The key field is generated by hashing the master key and the uid:

echo -n $HYPHENATED_UUID | openssl dgst -sha256 -hmac $MASTER_KEY

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.

• Adds a name field: specify a human-readable name to make API key retrieval more convenient.
• Introduces new actions to manage API keys (keys.get, keys.create, keys.update, keys.delete).
• It is no longer possible to update an API key's actions, indexes, or expiresAt after creation.

Done by @ManyTheFish in #2438, #2451, #2475, and #2474

Hebrew language support

New language support: Hebrew, using the Niqqud library.

Done by the amazing @benny-n in meilisearch/charabia#101.

New tokenizer contribution experience: add your language to Meilisearch

The contribution experience in the tokenizer has been significantly improved.

If your language is missing in Meilisearch, please consider contributing to the Meilisearch tokenizer by following the CONTRIBUTING.md file and integrating your intended normalizer/segmenter.

The whole core team is available to help you contribute. Feel free to ask for any clarifications you need!

Done by @ManyTheFish, @loiclec @gmourier, and @curquiza.

Customizable limits

Limit of facet values

When searching using the facets search parameter, Meilisearch will now return a maximum of 100 different facet values per faceted attribute.

This default limit is customizable using the new faceting setting, accessible via the /indexes/{uid}/settings/faceting route.

To increase this limit to 3000:

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/faceting' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxValuesPerFacet": 3000
  }'

You can also get the value using the HTTP GET verb, or reset the value using the DELETE verb.

Done by @Kerollmops in meilisearch/milli#550 and #2494

Limit of documents returned by search

When making a search request, Meilisearch returns a maximum of 1000 documents: the documents deemed most relevant to the query.

This default limit is now customizable using the pagination setting, accessible via the /indexes/{uid}/settings/pagination route.

To increase this limit to 2000:

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxTotalHits": 2000
  }'

You can also get the value using the HTTP GET verb, or reset the value using the DELETE verb.

Done by @Kerollmops in meilisearch/milli#550 and #2494

Breaking changes and improvement ⚠️

For most of the following changes, if you use one of our SDKs, these changes will be transparent for you by only updating to the latest version of the SDK.

Changes in /indexes/{uid}/search endpoint

• 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 to learn how to paginate with Meilisearch without using nbHits.
• The facetsDistribution search parameter is renamed facets
• The facetsDistribution field in the response body is renamed facetDistribution
• The matches search parameter is renamed showMatchesPosition
• The _matchesInfo field in the response body is renamed _matchesPosition
• exhaustiveNbHits and exhaustiveFacetsCount are removed. Meilisearch does not return exhaustive hit or facet counts at this time.

Done by @irevoire in #2406.

Changes in /indexes endpoints

• When getting the index list (GET /indexes), the response is now paginated. That means:
  • You can use the offset and limit parameters to browse indexes.
  • The indexes are returned in the results field in the response body.
  • limit, offset, and total now appear in the response body.
• The endpoint to update an index is now PATCH /indexes/{indexUid} instead of PUT
• The already deprecated name field has now been removed entirely.

Done by @irevoire and @Kerollmops in #2423, #2452, and #2454.

Changes in indexes/{uid}/documents endpoints

• When getting the documents list (GET /indexes/{uid}/documents), pagination has been improved. That means:
  • You can still use the offset and limit parameters to browse documents.
  • The documents are returned in the results field in the response body.
  • limit, offset, and total now appear in the response body.
• When getting documents via the GET /indexes/{uid}/documents route, the attributesToRetrieve parameter has been renamed fields
• The fields parameter is also available for the GET /indexes/{uid}/documents/{document_uid} endpoint.
• The displayedAttributes setting does not impact GET indexes/{uid}/documents anymore.

Done by @irevoire in #2372, #2433, and #2454.

Changes in /tasks and /indexes/{uid}/tasks endpoints

• You can now filter on the GET /tasks endpoint:
  • Filtering is possible on the type, status, and indexUid fields.
  • Use the , character to specify several values for a filter, e.g. ?status=enqueued,processing. This is equivalent to an OR operation.
  • Use the & character to apply multiple filters, e.g. ?status=enqueued&type=indexCreation. This is equivalent to an AND operation.
• Add keyset pagination on the GET /tasks endpoint, allowing users to browse multiple sets of task items.
  • Use the limit and from query parameters to browse tasks.
  • limit, from, and next now appear in the response body.
• GET /indexes/:indexUid/tasks has been removed. It can be replaced by GET /tasks?indexUid=:indexUid
• GET /indexes/:indexUid/tasks/:taskUid has been removed.
• uid has been renamed taskUid in the response body returned by every asynchronous task (e.g. index creation, document addition, etc...)
• Some task properties have been renamed
  • documentPartial-> documentAdditionOrUpdate
  • documentAddition-> documentAdditionOrUpdate
  • clearAll -> documentDeletion

Done by Kerollmops in #2399 and #2445.

Changes regarding dumps

• Dump creation is now an asynchronous task.
• Dump tasks are placed at the end of the task queue, but processed in priority.
  • In other words, a dump will run as soon as the current task is finished processing.
  • The dump's uid will reflect when it was enqueued in relation to the other tasks, not when it was processed.
• POST /dumps now returns 202 like any other asynchronous operation (e.g. index creation, document addition...)
• The GET /dumps/:dump_uid/status endpoint has been removed. It can be replaced by GET /tasks?type=dumpCreation.
• The dump_already_processing error has been removed since dumps can now be enqueued.

Done by @MarinPostma in #2410

Changes in /keys endpoint

• Tenant tokens: apiKeyPrefix has been renamed apiKeyUid.
• It is no longer possible to update actions, indexes, or expiresAt after key creation. Only the name and description fields are updatable.
• When getting the keys list (GET /keys), the response is now paginated. That means:
  • You can use the offset and limit parameters to browse keys.
  • limit, offset, and total now appear in the response body.
• 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.
• The dumps.get action has been removed.

Done by @ManyTheFish in #2438, #2451, #2475, and #2474)

Changes in /indexes/{uid}/settings endpoints

The following changes only concern the HTTP verb associated with a given method.

• The endpoint to update the global settings is now PATCH /indexes/{indexUid}/settings instead of POST
• The endpoint to update the typo tolerance settings is now PATCH /indexes/{indexUid}/settings/typo-tolerance instead of POST
• The endpoint to update the displayed attributes settings is now PUT /indexes/{indexUid}/settings/displayed-attributes instead of POST
• The endpoint to update the distinct attribute settings is now PUT /indexes/{indexUid}/settings/distinct-attribute instead of POST
• The endpoint to update the filterable attribute settings is now PUT /indexes/{indexUid}/settings/filterable-attributes instead of POST
• The endpoint to update the ranking rules settings is now PUT /indexes/{indexUid}/settings/ranking-rules instead of POST
• The endpoint to update the searchable attributes settings is now PUT /indexes/{indexUid}/settings/searchable-attributes instead of POST
• The endpoint to update the sortable attributes settings is now PUT /indexes/{indexUid}/settings/sortable-attributes instead of POST
• The endpoint to update the stop words settings is now PUT /indexes/{indexUid}/settings/stop-words instead of POST
• The endpoint to update the synonyms settings is now PUT /indexes/{indexUid}/settings/synonyms instead of POST

Done by @Kerollmops in #2452

Other improvements 🔨

• Geosearch: Support string type for _geo, lat, and lng fields (#2408 and meilisearch/milli#523) @irevoire
• Improve ranking rules error message (meilisearch/milli#536, #2468) @matthias-wright
• Improve docker CI: push vX.Y tag (without patch) to Docker Hub (#2529) @janithpet
• Remove the connection keep-alive timeout (#2471) @Thearas
• Improve index uid validation upon API key creation (#2414) @pierre-l
• Improve estimatedTotalHits behavior with distinct attribute (#2546) @Kerollmops

Fixes 🐞

• Fix filtering on documents with double and/or single quote characters (#2500 and meilisearch/milli#552) @irevoire

Misc

• Telemetry: handle the X-Meilisearch-Client header (#2374) @irevoire
• Telemetry: send the analytics to telemetry.meilisearch.com instead of segment (#2429) @irevoire
• Create custom error types for TaskType, TaskStatus, and IndexUid (#2460) @walterbm
• Improve the Docker CIs (#2477 and #2491) @choznerol and @curquiza
• Some internal changes (#2447, #2464, #2453, #2455) @MarinPostma @Kerollmops
• Update dependencies (#2450) @Kerollmops
• Add dump tests in CI (#2357) @irevoire
• Deny warnings in CI (#2339) @MarinPostma
• Update mini-dashboard for v0.28.0 (#2587) @mdubus @bidoubiwa
• Change Nelson path (#2347) @curquiza
• Re-integrate Clippy in the CI (#2424) @irevoire
• Fix typo in README (#2448) @ryanrussell
• Fix typo in code base comments (#2459, and #2508) @ryanrussell
• Update url of movies.json in README (#2422) @0x0x1
• Fix command in README (#2434) @0x0x1

---

❤️ Thanks again to our external contributors:

• Meilisearch: @0x0x1, @choznerol, @janithpet, @pierre-l, @ryanrussell, @Thearas, and @walterbm
• Milli: @matthias-wright
• Charabia: @benny-n

curl -fL -o v0.28.0.zip https://ratatoskr.space/pkg/meilisearch/v0.28.0.zip
                    printf '%s  %s\n' 'c8820f13335ef472b1477f2bc265169567c284113057ca0d35777e310d6732f2' 'v0.28.0.zip' | sha256sum -c -

$url = "https://ratatoskr.space/pkg/meilisearch/v0.28.0.zip"
$out = "v0.28.0.zip"
Invoke-WebRequest -Uri $url -OutFile $out
if ((Get-FileHash $out -Algorithm SHA256).Hash.ToLowerInvariant() -ne "c8820f13335ef472b1477f2bc265169567c284113057ca0d35777e310d6732f2") { throw "sha256 mismatch" }

curl -fL -o v0.28.0.tar.gz https://ratatoskr.space/pkg/meilisearch/v0.28.0.tar.gz
                    printf '%s  %s\n' 'd47758b24e90bea9e442403de40108c21b40458598ce43701fa3004d490d3cb2' 'v0.28.0.tar.gz' | sha256sum -c -

$url = "https://ratatoskr.space/pkg/meilisearch/v0.28.0.tar.gz"
$out = "v0.28.0.tar.gz"
Invoke-WebRequest -Uri $url -OutFile $out
if ((Get-FileHash $out -Algorithm SHA256).Hash.ToLowerInvariant() -ne "d47758b24e90bea9e442403de40108c21b40458598ce43701fa3004d490d3cb2") { throw "sha256 mismatch" }

curl -fL -o v0.28.0.zip http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.zip
                    printf '%s  %s\n' 'c8820f13335ef472b1477f2bc265169567c284113057ca0d35777e310d6732f2' 'v0.28.0.zip' | sha256sum -c -

$url = "http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.zip"
$out = "v0.28.0.zip"
Invoke-WebRequest -Uri $url -OutFile $out
if ((Get-FileHash $out -Algorithm SHA256).Hash.ToLowerInvariant() -ne "c8820f13335ef472b1477f2bc265169567c284113057ca0d35777e310d6732f2") { throw "sha256 mismatch" }

curl -fL -o v0.28.0.tar.gz http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.tar.gz
                    printf '%s  %s\n' 'd47758b24e90bea9e442403de40108c21b40458598ce43701fa3004d490d3cb2' 'v0.28.0.tar.gz' | sha256sum -c -

$url = "http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.tar.gz"
$out = "v0.28.0.tar.gz"
Invoke-WebRequest -Uri $url -OutFile $out
if ((Get-FileHash $out -Algorithm SHA256).Hash.ToLowerInvariant() -ne "d47758b24e90bea9e442403de40108c21b40458598ce43701fa3004d490d3cb2") { throw "sha256 mismatch" }

http_archive(
    name = "meilisearch",
    urls = ["https://ratatoskr.space/pkg/meilisearch/v0.28.0.tar.gz"],
    integrity = "sha256-1HdYsk6QvqnkQkA95AEIwhtARYWYzkNwH6MATUkNPLI=",
    strip_prefix = "meilisearch-v0.28.0",
)

.url = "https://ratatoskr.space/pkg/meilisearch/v0.28.0.tar.gz",

http_archive(
    name = "meilisearch",
    urls = ["http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.tar.gz"],
    integrity = "sha256-1HdYsk6QvqnkQkA95AEIwhtARYWYzkNwH6MATUkNPLI=",
    strip_prefix = "meilisearch-v0.28.0",
)

.url = "http://14cc7d57b5e70f679b851fe5b272ce17c70632ff4beb5b35ab64bc706b2485af.pk.ygg/pkg/meilisearch/v0.28.0.tar.gz",