Meilisearch

Component format

To set up a Meilisearch vector store, create a component of type vector.meilisearch. See this guide on how to create and apply a vector store configuration.

apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
  name: <NAME>
spec:
  type: vector.meilisearch
  version: v1
  metadata:
  - name: host
    value: "http://localhost:7700"
  - name: apiKey
    value: "<API_KEY>"
  - name: timeout
    value: "10s"

Spec metadata fields

Supported features

Collection settings

A collection is a Meilisearch index with a single userProvided embedder named default with the requested dimensions. Record metadata is filterable by default.

You can pass the following Meilisearch index settings as comma-separated values in the metadata of a create collection request:

Creating a collection that already exists returns ALREADY_EXISTS and doesn’t change its settings. Collections share the Meilisearch instance with search indexes: list collections only returns indexes that have the default user-provided embedder, and getting or deleting any other index as a collection, or upserting or deleting records in it, returns FAILED_PRECONDITION.

Get collection returns the following properties: primaryKey (always id), filterableAttributes, and sortableAttributes when set.

Record mapping

• The record id is the Meilisearch primary key. It must be 1 to 511 bytes of ASCII letters, digits, hyphens, and underscores.
• The record values are stored in _vectors.default.
• The record metadata is stored as the daprMetadata object. Filter paths are translated to daprMetadata.<path>, so a filter on dealer.city addresses daprMetadata.dealer.city.
• The record payload is stored base64-encoded under the daprPayload attribute.

Distance metric and scores

Meilisearch only supports cosine similarity for user-provided embeddings. DISTANCE_METRIC_UNSPECIFIED selects cosine, and any other metric in a create collection or query request returns INVALID_ARGUMENT. Because cosine similarity is undefined for a vector whose values are all zero, such vectors, and vectors with values that aren’t finite numbers, are rejected with INVALID_ARGUMENT.

For a vector query, Meilisearch reports a normalised ranking score of (1 + cosine) / 2. The component converts it back so that match scores are the cosine similarity in [-1, 1], and translates a scoreThreshold of t into a Meilisearch rankingScoreThreshold of (1 + t) / 2. A scoreThreshold outside [-1, 1] returns INVALID_ARGUMENT.

When topK isn’t set, the component returns up to 10 matches.

Waiting for writes

Meilisearch processes writes asynchronously as tasks. With INDEXING_MODE_WAIT_FOR_COMPLETION, the component waits for the task to finish by polling the Meilisearch task API with exponential backoff.

When the experimental Meilisearch tasksStreamingRoute feature is enabled and the API key has the tasks.get permission, the component instead shares a single task-change stream for all waiting writes. If the route reports that it is unavailable, the component falls back to polling. The choice is transparent to your application.

A Meilisearch task is atomic: if the task fails, none of the records in it are written, and a request that waits for completion fails with the task’s error. The component therefore checks the records that Meilisearch would reject before it sends the task. A record with an invalid id, no vector values, a number of values that differs from the collection’s dimensions, or a vector with a zero norm or non-finite values is reported in failedItems with INVALID_ARGUMENT, and the rest of the records are still written.

Upserting into a collection that doesn’t exist fails the request with NOT_FOUND.

Setup Meilisearch

• Self-hosted
• Meilisearch Cloud

docker run -d --name meilisearch -p 7700:7700 \
  -e MEILI_MASTER_KEY=masterKey \
  getmeili/meilisearch:v1.43

Related links

• Basic schema for a Dapr component
• Vector API overview
• Vector API reference
• Meilisearch search component
• Meilisearch AI-powered search documentation