Add support for Dynamic Search Rules

.code-samples.meilisearch.yaml

@@ -625,6 +625,27 @@ update_embedders_1: |-
   })
 reset_embedders_1: |-
   client.index('INDEX_NAME').reset_embedders()
+list_dynamic_search_rules_1: |-
+  client.get_dynamic_search_rules()
+get_dynamic_search_rule_1: |-
+  client.get_dynamic_search_rule('RULE_UID')
+patch_dynamic_search_rule_1: |-
+  client.create_or_update_dynamic_search_rule('RULE_UID', {
+    'description': 'Rule description',
+    'priority': 10,
+    'active': True,
+    'conditions': [
+      {'scope': 'query', 'isEmpty': True}
+    ],
+    'actions': [
+      {
+        'selector': {'indexUid': 'movies', 'id': '123'},
+        'action': {'type': 'pin', 'position': 1}
+      }
+    ],
+  })
+delete_dynamic_search_rule_1: |-
+  client.delete_dynamic_search_rule('RULE_UID')
 post_render_template_1: |-
   client.update_experimental_features({"renderRoute": True})
 

meilisearch/client.py

@@ -20,6 +20,7 @@
     MeilisearchError,
 )
 from meilisearch.index import Index
+from meilisearch.models.dynamic_search_rule import DynamicSearchRule, DynamicSearchRuleResults
 from meilisearch.models.key import Key, KeysResults
 from meilisearch.models.task import Batch, BatchResults, Task, TaskInfo, TaskResults
 from meilisearch.models.webhook import Webhook, WebhooksResults
@@ -625,6 +626,114 @@ def delete_webhook(self, webhook_uuid: str) -> int:
         response = self.http.delete(f"{self.config.paths.webhooks}/{webhook_uuid}")
         return response.status_code
 
+    # DYNAMIC SEARCH RULES ROUTES
+
+    def get_dynamic_search_rules(
+        self, parameters: Mapping[str, Any] | None = None
+    ) -> DynamicSearchRuleResults:
+        """Get all dynamic search rules.
+
+        Parameters
+        ----------
+        parameters (optional):
+            Parameters accepted by the list dynamic search rules route:
+            https://www.meilisearch.com/docs/reference/api/dynamic-search-rules/list-dynamic-search-rules
+            Accepts offset, limit, and filter in the request body.
+
+        Returns
+        -------
+        rules:
+            DynamicSearchRuleResults instance containing list of rules and pagination info.
+            https://www.meilisearch.com/docs/reference/api/dynamic-search-rules/list-dynamic-search-rules
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request.
+            Meilisearch error codes are described here:
+            https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
+        """
+        if parameters is None:
+            parameters = {}
+        rules = self.http.post(self.config.paths.dynamic_search_rules, parameters)
+        return DynamicSearchRuleResults(**rules)
+
+    def get_dynamic_search_rule(self, uid: str) -> DynamicSearchRule:
+        """Get information about a specific dynamic search rule.
+
+        Parameters
+        ----------
+        uid:
+            The uid of the dynamic search rule to retrieve.
+
+        Returns
+        -------
+        rule:
+            The dynamic search rule information.
+            https://www.meilisearch.com/docs/reference/api/dynamic-search-rules/get-a-dynamic-search-rule
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request.
+            Meilisearch error codes are described here:
+            https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
+        """
+        rule = self.http.get(f"{self.config.paths.dynamic_search_rules}/{uid}")
+        return DynamicSearchRule(**rule)
+
+    def create_or_update_dynamic_search_rule(
+        self, uid: str, options: Mapping[str, Any]
+    ) -> DynamicSearchRule:
+        """Create or update a dynamic search rule.
+
+        Parameters
+        ----------
+        uid:
+            The uid of the dynamic search rule to create or update.
+        options:
+            The dynamic search rule fields to create or update.
+
+        Returns
+        -------
+        rule:
+            The created or updated dynamic search rule.
+            https://www.meilisearch.com/docs/reference/api/dynamic-search-rules/create-or-update-a-dynamic-search-rule
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request.
+            Meilisearch error codes are described here:
+            https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
+        """
+        rule = self.http.patch(f"{self.config.paths.dynamic_search_rules}/{uid}", options)
+        return DynamicSearchRule(**rule)
+
+    def delete_dynamic_search_rule(self, uid: str) -> int:
+        """Delete a dynamic search rule.
+
+        Parameters
+        ----------
+        uid:
+            The uid of the dynamic search rule to delete.
+
+        Returns
+        -------
+        status_code:
+            The Response status code. 204 signifies a successful delete.
+            https://www.meilisearch.com/docs/reference/api/dynamic-search-rules/delete-a-dynamic-search-rule
+
+        Raises
+        ------
+        MeilisearchApiError
+            An error containing details about why Meilisearch can't process your request.
+            Meilisearch error codes are described here:
+            https://www.meilisearch.com/docs/reference/errors/error_codes#meilisearch-errors
+        """
+        response = self.http.delete(f"{self.config.paths.dynamic_search_rules}/{uid}")
+        return response.status_code
+
     def get_version(self) -> dict[str, str]:
         """Get version Meilisearch
 

meilisearch/config.py

@@ -49,6 +49,7 @@ class Paths:
         network = "network"
         experimental_features = "experimental-features"
         webhooks = "webhooks"
+        dynamic_search_rules = "dynamic-search-rules"
         export = "export"
         render_template = "render-template"
 

meilisearch/models/dynamic_search_rule.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from camel_converter.pydantic_base import CamelBase
+
+
+class DynamicSearchRule(CamelBase):
+    uid: str
+    description: str | None = None
+    priority: int | None = None
+    active: bool
+    conditions: list[dict[str, Any]]
+    actions: list[dict[str, Any]]
+
+
+class DynamicSearchRuleResults(CamelBase):
+    results: list[DynamicSearchRule]
+    offset: int
+    limit: int
+    total: int

tests/client/test_client_dynamic_search_rules_meilisearch.py

@@ -0,0 +1,166 @@
+"""Tests for dynamic search rule management endpoints."""
+
+import pytest
+
+from meilisearch.errors import MeilisearchApiError
+
+pytestmark = pytest.mark.usefixtures("enable_dynamic_search_rules", "clear_dynamic_search_rules")
+
+
+def test_get_dynamic_search_rules_empty(client):
+    """Test getting dynamic search rules when none exist."""
+    rules = client.get_dynamic_search_rules()
+    assert rules.results is not None
+    assert isinstance(rules.results, list)
+    assert len(rules.results) == 0
+
+
+def test_get_dynamic_search_rules_with_parameters(client):
+    """Test getting dynamic search rules with offset, limit, and filter parameters."""
+    # Create a few rules to paginate/filter
+    for i in range(3):
+        client.create_or_update_dynamic_search_rule(
+            f"test-rule-{i}",
+            {
+                "description": f"Rule {i}",
+                "active": i != 2,
+                "conditions": [{"scope": "query", "isEmpty": True}],
+                "actions": [
+                    {
+                        "selector": {"indexUid": "movies", "id": str(i)},
+                        "action": {"type": "pin", "position": i + 1},
+                    }
+                ],
+            },
+        )
+
+    # Test with limit
+    rules = client.get_dynamic_search_rules({"limit": 1})
+    assert len(rules.results) == 1
+
+    # Verify total count before testing offset
+    all_rules = client.get_dynamic_search_rules()
+    assert len(all_rules.results) == 3, "Offset test requires exactly 3 rules"
+    rules = client.get_dynamic_search_rules({"offset": 1})
+    assert len(rules.results) == 2
+
+    # Test with filter on active status
+    rules = client.get_dynamic_search_rules({"filter": {"active": True}})
+    assert all(r.active is True for r in rules.results)
+
+
+def test_create_or_update_dynamic_search_rule(client):
+    """Test creating a dynamic search rule."""
+    rule_data = {
+        "description": "Test rule for promotion",
+        "priority": 10,
+        "active": True,
+        "conditions": [{"scope": "query", "isEmpty": True}],
+        "actions": [
+            {
+                "selector": {"indexUid": "movies", "id": "123"},
+                "action": {"type": "pin", "position": 1},
+            }
+        ],
+    }
+
+    rule = client.create_or_update_dynamic_search_rule("test-rule", rule_data)
+
+    assert rule.uid == "test-rule"
+    assert rule.description == rule_data["description"]
+    assert rule.priority == 10
+    assert rule.active is True
+
+
+def test_get_dynamic_search_rule(client):
+    """Test getting a single dynamic search rule."""
+    # Create a rule first
+    rule_data = {
+        "description": "Test rule",
+        "active": True,
+        "conditions": [{"scope": "query", "isEmpty": True}],
+        "actions": [
+            {
+                "selector": {"indexUid": "movies", "id": "123"},
+                "action": {"type": "pin", "position": 1},
+            }
+        ],
+    }
+
+    created_rule = client.create_or_update_dynamic_search_rule("test-rule", rule_data)
+
+    # Get the rule
+    rule = client.get_dynamic_search_rule(created_rule.uid)
+
+    assert rule.uid == created_rule.uid
+    assert rule.description == rule_data["description"]
+
+
+def test_get_dynamic_search_rule_not_found(client):
+    """Test getting a dynamic search rule that doesn't exist."""
+    with pytest.raises(MeilisearchApiError):
+        client.get_dynamic_search_rule("non-existent-uid")
+
+
+def test_update_dynamic_search_rule(client):
+    """Test updating a dynamic search rule."""
+    # Create a rule first
+    rule_data = {
+        "description": "Original description",
+        "priority": 10,
+        "active": True,
+        "conditions": [{"scope": "query", "isEmpty": True}],
+        "actions": [
+            {
+                "selector": {"indexUid": "movies", "id": "123"},
+                "action": {"type": "pin", "position": 1},
+            }
+        ],
+    }
+
+    created_rule = client.create_or_update_dynamic_search_rule("test-rule", rule_data)
+
+    # Update the rule
+    update_data = {
+        "description": "Updated description",
+        "priority": 5,
+    }
+
+    updated_rule = client.create_or_update_dynamic_search_rule(created_rule.uid, update_data)
+
+    assert updated_rule.uid == created_rule.uid
+    assert updated_rule.description == update_data["description"]
+    assert updated_rule.priority == 5
+
+
+def test_delete_dynamic_search_rule(client):
+    """Test deleting a dynamic search rule."""
+    # Create a rule first
+    rule_data = {
+        "description": "Rule to delete",
+        "active": True,
+        "conditions": [{"scope": "query", "isEmpty": True}],
+        "actions": [
+            {
+                "selector": {"indexUid": "movies", "id": "123"},
+                "action": {"type": "pin", "position": 1},
+            }
+        ],
+    }
+
+    created_rule = client.create_or_update_dynamic_search_rule("test-rule", rule_data)
+
+    # Delete the rule
+    status_code = client.delete_dynamic_search_rule(created_rule.uid)
+
+    assert status_code == 204
+
+    # Verify it's deleted
+    with pytest.raises(MeilisearchApiError):
+        client.get_dynamic_search_rule(created_rule.uid)
+
+
+def test_delete_dynamic_search_rule_not_found(client):
+    """Test deleting a dynamic search rule that doesn't exist."""
+    with pytest.raises(MeilisearchApiError):
+        client.delete_dynamic_search_rule("non-existent-uid")

tests/conftest.py

@@ -61,6 +61,22 @@ def clear_webhooks(client):
         client.delete_webhook(webhook.uuid)
 
 
+@fixture
+def clear_dynamic_search_rules(client):
+    """
+    Clears the dynamic search rules after each test function run.
+    Must be explicitly used alongside enable_dynamic_search_rules,
+    since the dynamic search rules feature requires experimental feature toggle.
+    """
+    # Yields back to the test function.
+
+    yield
+    # Deletes all the dynamic search rules in the Meilisearch instance.
+    rules = client.get_dynamic_search_rules()
+    for rule in rules.results:
+        client.delete_dynamic_search_rule(rule.uid)
+
+
 @fixture(autouse=True)
 def clear_all_tasks(client, client2):
     """
@@ -354,6 +370,23 @@ def enable_network_options():
     )
 
 
+@fixture
+def enable_dynamic_search_rules():
+    requests.patch(
+        f"{common.BASE_URL}/experimental-features",
+        headers={"Authorization": f"Bearer {common.MASTER_KEY}"},
+        json={"dynamicSearchRules": True},
+        timeout=10,
+    )
+    yield
+    requests.patch(
+        f"{common.BASE_URL}/experimental-features",
+        headers={"Authorization": f"Bearer {common.MASTER_KEY}"},
+        json={"dynamicSearchRules": False},
+        timeout=10,
+    )
+
+
 @fixture
 def enable_render_route():
     requests.patch(