documentation/experimental-features.md
An experimental feature is a feature present in the final Meilisearch binary that is not considered stable. This means the API might become incompatible between two Meilisearch releases.
Experimental features must be explicitly enabled by a user.
⚠️ Experimental features are NOT prototypes. All experimental features are thoroughly tested before release and follow the same quality standards as other features.
Since the release of v1, Meilisearch is considered a stable binary and its API cannot break between minor and patch versions. This means it is impossible to make breaking changes to a feature without releasing a major version.
This limitation, which guarantees our users Meilisearch is a stable and reliable product, also applies to new features. If we introduce a new feature in one release, any breaking changes will require a new major release.
To prevent frequently releasing new major versions but still continue to develop new features, we will first provide these features as "experimental". This allows users to test them, report implementation issues, and give us important feedback.
Not all new features need to go through the experimental feature process.
We will treat features as experimental when:
Users must explicitly enable experimental features with a CLI flag. Experimental features will always be disabled by default.
Example CLI flags: --experimental-disable-soft-delete, --experimental-multi-index-search.
⚠️ To ensure users understand a feature is experimental, flags must contain the experimental prefix.
For each new experimental feature, we must:
--help command in the Meilisearch binary so it redirects users to the related GitHub discussion and warns them about the unstable state of the features⚠️ Since this process is not mature yet, users might experience issues with their DB when deactivating these features even when using a dump.
We recommend users always save their data (with snapshots and/or dumps) before activating experimental features.
Meilisearch uses LMDB to store both documents and internal application data, such as Meilisearch tasks. Altering these internal data structures requires closing and re-opening the LMDB environment.
If an experimental feature implementation involves a modification of internal data structures, users must restart Meilisearch. This cannot be done via HTTP routes.
Unfortunately, this might impact most experimental features. However, this might change in the future, or adapted to the context of a specific new feature.
Under some circumstances, Meilisearch might have issues when reading a database generated by a different Meilisearch release. This might cause an instance to crash or work with faulty data.
This is already a possibility when migrating between minor Meilisearch versions, and is more likely to happen when activating a new experimental feature. The opposite operation—migrating a database with experimental features activated to a database where those features are not active—is currently riskier. As we develop and improve the development of experimental features, this procedure will become safer and more reliable.
We understand the situation is inconvenient and less than ideal. We will only ask users to use dumps when activating experimental features when it’s strictly necessary.
Avoiding restarts is more difficult, especially for features that currently require database migrations with dumps. We are not currently working on this, but the situation might change in the future.