fix: Added tests and docstrings for showPerformanceDetails

meilisearch/client.py

@@ -273,8 +273,11 @@ def multi_search(
             https://www.meilisearch.com/docs/reference/api/search#search-in-an-index
             It can also include remote options in federationOptions for each query
             https://www.meilisearch.com/docs/reference/api/network
+            Each query may include showPerformanceDetails to request a performance
+            trace in the response (results[].performanceDetails, returned as raw data).
         federation: (optional):
-            Dictionary containing offset and limit
+            Dictionary containing offset, limit, and optionally showPerformanceDetails
+            for federated search (top-level performanceDetails in the response).
             https://www.meilisearch.com/docs/reference/api/multi_search
 
         Returns

meilisearch/index.py

@@ -351,11 +351,14 @@ def search(self, query: str, opt_params: Optional[Mapping[str, Any]] = None) ->
             - filter: Filter queries by an attribute's value
             - limit: Maximum number of documents returned
             - offset: Number of documents to skip
+            - showPerformanceDetails: If true, the response includes a
+              performanceDetails object (raw data; fields may change in future API versions)
 
         Returns
         -------
         results:
-            Dictionary with hits, offset, limit, processingTime and initial query
+            Dictionary with hits, offset, limit, processingTime and initial query.
+            When showPerformanceDetails is true, may include a performanceDetails object.
 
         Raises
         ------
@@ -485,12 +488,14 @@ def get_similar_documents(self, parameters: Mapping[str, Any]) -> Dict[str, Any]
         ----------
         parameters:
             parameters accepted by the get similar documents route: https://www.meilisearch.com/docs/reference/api/similar#body
-            "id" and "embedder" are required.
+            "id" and "embedder" are required. May include showPerformanceDetails to
+            request a performance trace in the response (performanceDetails, raw data).
 
         Returns
         -------
         results:
-            Dictionary with hits, offset, limit, processingTimeMs, and id
+            Dictionary with hits, offset, limit, processingTimeMs, and id.
+            When showPerformanceDetails is true, may include a performanceDetails object.
 
         Raises
         ------

tests/client/test_client_multi_search_meilisearch.py

@@ -30,6 +30,16 @@ def test_multi_search_one_index(client, empty_index):
     assert response["results"][0]["limit"] == 20
 
 
+def test_multi_search_show_performance_details(client, empty_index):
+    """Tests multi-search with showPerformanceDetails (Meilisearch 1.35+)."""
+    empty_index("indexA")
+    response = client.multi_search(
+        [{"indexUid": "indexA", "q": "", "showPerformanceDetails": True}]
+    )
+    assert response["results"][0]["indexUid"] == "indexA"
+    assert isinstance(response["results"][0]["performanceDetails"], dict)
+
+
 def test_multi_search_on_no_index(client):
     """Tests multi-search on a non existing index."""
     with pytest.raises(MeilisearchApiError):

tests/index/test_index_search_meilisearch.py

@@ -502,6 +502,17 @@ def test_show_ranking_score(index_with_documents):
     assert response["hits"][0]["_rankingScore"] >= 0.9
 
 
+def test_show_performance_details(index_with_documents):
+    """Tests search with showPerformanceDetails returns performance trace when supported (Meilisearch 1.35+)."""
+    response = index_with_documents().search(
+        "dragon",
+        {"showPerformanceDetails": True},
+    )
+    assert isinstance(response, dict)
+    assert "hits" in response
+    assert isinstance(response["performanceDetails"], dict)
+
+
 def test_vector_search(index_with_documents_and_vectors):
     """Tests vector search with hybrid parameters."""
     response = index_with_documents_and_vectors().search(
@@ -618,3 +629,25 @@ def test_get_similar_documents_with_identical_vectors(empty_index):
     # Verify that doc4 is not the first result (it has a different vector)
     if "doc4" in result_ids:
         assert result_ids[0] != "doc4"
+
+
+def test_get_similar_documents_show_performance_details(empty_index):
+    """Tests get_similar_documents with showPerformanceDetails (Meilisearch 1.35+)."""
+    identical_vector = [0.5, 0.5]
+    documents = [
+        {"id": "doc1", "title": "Doc 1", "_vectors": {"default": identical_vector}},
+        {"id": "doc2", "title": "Doc 2", "_vectors": {"default": identical_vector}},
+    ]
+    index = empty_index()
+    task = index.update_embedders({"default": {"source": "userProvided", "dimensions": 2}})
+    index.wait_for_task(task.task_uid)
+    task = index.add_documents(documents)
+    index.wait_for_task(task.task_uid)
+
+    response = index.get_similar_documents(
+        {"id": "doc1", "embedder": "default", "showPerformanceDetails": True}
+    )
+    assert isinstance(response, dict)
+    assert "hits" in response
+    assert response["id"] == "doc1"
+    assert isinstance(response["performanceDetails"], dict)