Dynamic Search Rules

[YoEight]

Feature name	How to enable	Description	Missing for stabilization	Expected stabilization date/version
dynamic search rules	curl \ -X PATCH 'http://localhost:7700/experimental-features/' \ -H 'Content-Type: application/json' \ --data-binary '{ "dynamicSearchRules": true }'	Enables dynamic search rules feature	TBD	N/A

Hey everyone,

For the next Meilisearch release, we are introducing Dynamic Search Rules as an experimental feature.

Feature abstract

Dynamic Search Rules let you promote specific documents for specific searches.

A rule can match:

• a query
• an empty query
• a time window

When a rule matches, it can pin chosen documents at fixed positions in the results.

This is useful when you want more control over important searches. For example:

• show a help article first for a common support query
• promote a featured product for a business query
• schedule promoted results during a launch or a campaign

Pinned documents still respect the search request. If a pinned document is filtered out, it is not inserted into the results.

How to enable the feature in Meilisearch?

Call this route:

curl \
  -X PATCH 'http://localhost:7700/experimental-features' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "dynamicSearchRules": true
  }'

You can check that the feature is enabled by calling:

curl \
  -X GET 'http://localhost:7700/experimental-features'

How to use the feature?

Dynamic Search Rules use the /dynamic-search-rules routes:

• PATCH /dynamic-search-rules/{uid} to create or update a rule
• GET /dynamic-search-rules/{uid} to fetch a rule
• DELETE /dynamic-search-rules/{uid} to delete a rule
• POST /dynamic-search-rules to list rules

What can the feature do today?

Today, rules support:

• query conditions with contains
• query conditions with isEmpty
• time conditions with start and end
• pinning documents with a fixed position
• pinning more than one document in a chosen order

This first version focuses on pinning.

Example

The example below promotes billing help content when the query contains invoice:

curl \
  -X PATCH 'http://localhost:7700/dynamic-search-rules/invoice-help' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "description": "Promote billing help for invoice searches",
    "active": true,
    "conditions": [
      { "scope": "query", "contains": "invoice" }
    ],
    "actions": [
      {
        "selector": { "indexUid": "support", "id": "billing-workspace-overview" },
        "action": { "type": "pin", "position": 0 }
      },
      {
        "selector": { "indexUid": "support", "id": "download-monthly-statements" },
        "action": { "type": "pin", "position": 1 }
      }
    ]
  }'

What is not supported yet?

This first version does not support:

• regex or pattern-based triggers
• numeric-format triggers such as “any 6-digit code”
• request-context conditions such as “query + product filter”
• actions other than pinning

We would especially like feedback on these points.

What is an experimental feature?

• The API and behavior of an experimental feature can change between minor versions of Meilisearch.
• The feature may change a lot before it becomes stable.
• The feature may also be removed in the future.
• Experimental means we want feedback before we freeze the API.

Why is this feature not stable yet?

We still need feedback on the shape of the feature.

In particular, we want to better understand:

• which condition types are the most useful
• whether pinning is enough for a first stable version
• which extra actions users need after pinning
• how much request context rules should be able to inspect

When will the feature be stable?

We do not know yet.

We want to learn from real use cases first, then improve the feature over the next releases.

We would love your feedback

If you try Dynamic Search Rules, please tell us:

• which use cases you want to solve
• which conditions you need
• whether pinning is enough
• which missing actions matter most
• what feels awkward in the current API

Questions, feedback, and use cases are all very welcome.

[JSTLWK]

I've been using Dynamic Search Rules in production for about two weeks now, and it's been working great so far!

That said, to fully match our use case we'd need a few additional query condition types:

• is → exact match
• startsWith → prefix match
• endsWith → suffix match

Our use case: we run a pet supplies store and want to pin specific products to the top when they're temporarily on sale. For example, a query condition like is: "dog food" should fire only for that exact query, not for every query that happens to contain the substring (contains: "dog food" also matches things like "grain-free dog food deals", which we don't want here). Exact matching would let us curate these promoted results much more precisely and fits our merchandising workflow perfectly.

Other than that, we've been really enjoying MeiliSearch and this experimental feature. Happy to share more about our setup or show the project in action if that's useful, feel free to reach out.

Is there any chance is (exact match) could land soon? I'd love to test it in the wild!

[dureuill]

hello, thank you for your perspective and feature request.

Currently we're not exactly taking the route of adding more query condition types. Latest release (v1.50) even replaces contains with words, which matches on words present in the query (word in the Meilisearch sense) rather than by substring.

The reason is performance, as checking substrings has to be done on each rule, whereas finding rules containing a given word can return the list in near constant time.

Your use case appears interesting however, can you provide more information about the reasons why you would like the query "dog food" to match, but not "grain-free dog food deals" or even "dog food deals"? If it is because of the presence of grain-free, would having a "not contains" condition help here? So you could express your rule as:

• words: "dog food"
• not words: "grain-free"

?

[JSTLWK]

Hello, and thanks a lot for engaging with this so quickly. Much appreciated!

You're right that grain-free is one of the reasons we wouldn't want those products pinned. But the bigger driver is this: more and more of our suppliers are asking to have their own products ranked at the top for a specific keyword. So for us, matching on an exact query (or exact set of words) is really the behaviour we're after.

I do like the not words idea, and the performance reasoning behind the move from contains to words makes sense to me. My concern is that exclusions don't scale for our case. To make words: "dog food" behave the way we need, we'd have to exclude every competing brand and every unwanted modifier such as grain-free or deals, and that list keeps growing as more suppliers come on board. We could realistically end up with 100+ not words conditions on a single rule, which is hard to manage, and I'm not sure how it performs either.

That's exactly why an is (exact match) condition would be so valuable. Instead of maintaining an ever-growing blacklist, we'd express a clean allowlist: pin this product for this exact query, and nothing else.

I think performance is a completely valid reason, and I fully get the tradeoff. I just always feel there should be a balance between performance and manageability. If exact matching could live alongside words as an opt-in condition, that would be the sweet spot for us.

[dureuill]

OK, I understand your use case and it makes a lot of sense: reserving a specific query rather than a keyword inside a query.

I won't be working on this immediately, as I'll move to boosting/deboosting actions of dynamic search rules, but I guess we could try and allow for an exact match with the following:

1. Pre-filter on rules that contains the words, in the sense of the v1.50 words semantics
2. On surviving rules, linearly check the subset that has the stricter is condition.

Hopefully step (1) will remove a sufficient number of rules for step 2 to retain reasonable performance. I've also added the concept of "DSR fuel", which is a (configurable via hidden environment variable) structure that indicates how many of some operations we can do, so I could limit the evaluation in step (2) to 20 rules or something, to make sure we don't spend too much time in this step.

DSR is a complex topic because we have to evaluate a potentially high number of rules on the tight budget of a search request.

[JSTLWK]

Awesome, and thank you for taking the time to respond so quickly. The two-step approach makes a lot of sense to me, and the DSR fuel concept sounds like a smart way to keep the budget in check.

Would you mind giving me a quick ping once this is ready for release or has been released? I'd be happy to test it against real traffic and share feedback. I'll keep an eye on the Meilisearch release notes as well.

[dureuill]

I filed the issue on our end, will try and keep you up to date whenever it gets implemented