Add showPerformanceDetails option to search endpoints

[William-Laverty]

Summary

Adds support for the new showPerformanceDetails parameter introduced in Meilisearch v1.35.0.

Changes

• Added showPerformanceDetails parameter to SearchParameters
• Added PerformanceDetails and PerformanceValue types for response handling
• Added performanceDetails property to Searchable class

Implementation Notes

As specified in #501, the performance details are returned as "raw" data without imposing a specific schema. The PerformanceValue type is a recursive enum that can represent arbitrary JSON structures, allowing the SDK to handle any format changes in future Meilisearch versions.

Usage Example

let searchParameters = SearchParameters(
    query: "search term",
    showPerformanceDetails: true
)

let result = try await client.index("movies").search(searchParameters)
if let performanceDetails = result.performanceDetails {
    // Access the raw performance trace
    print(performanceDetails.rawValue)
}

Closes #501

Summary by CodeRabbit

• New Features
  • Added support for retrieving performance metrics from search queries. Users can now enable performance details to access timing and performance data in search results.

[coderabbitai]

📝 Walkthrough

Walkthrough

Introduces performance tracing support for Meilisearch 1.35 by adding a new showPerformanceDetails parameter to search requests and creating flexible data structures (PerformanceDetails and PerformanceValue) to capture and represent raw performance trace data returned in search responses.

Changes

Cohort / File(s)	Summary
Performance Data Models Sources/MeiliSearch/Model/PerformanceDetails.swift	New PerformanceDetails struct and PerformanceValue enum with custom Codable implementations to handle dynamic JSON performance trace data without enforcing a fixed schema.
Search Request Configuration Sources/MeiliSearch/Model/SearchParameters.swift	Added optional boolean showPerformanceDetails parameter to enable performance tracing in search requests.
Search Response Integration Sources/MeiliSearch/Model/SearchResult.swift	Added optional performanceDetails property to Searchable<T> class to capture performance data in search responses.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A swift trace through the fields of search,
Performance secrets, now within our reach,
Raw data flows like morning dew,
Dynamic JSON, tried and true,
Meilisearch speaks its hidden song! 🎵

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR implements showPerformanceDetails parameter in SearchParameters, adds PerformanceDetails and PerformanceValue types as raw data without fixed schema, and updates SearchResult to expose performance details [#501]. However, test cases are not included and only search endpoints were updated, not multi-search or similar documents.	Add test cases covering the new parameter and response handling. Verify that multi-search and similar documents endpoints also support showPerformanceDetails as specified in issue #501.
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding the showPerformanceDetails option to search endpoints, which aligns with the core modifications across SearchParameters, SearchResult, and PerformanceDetails.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the showPerformanceDetails feature specified in issue #501. The new PerformanceDetails, PerformanceValue types, SearchParameters modifications, and SearchResult changes are all in scope.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@Sources/MeiliSearch/Model/SearchParameters.swift`:
- Around line 71-76: Add unit and integration tests that mirror the existing
tests for showRankingScore/showRankingScoreDetails/showMatchesPosition to cover
the new SearchParameters.showPerformanceDetails optional Bool: (1) a unit test
that verifies request encoding includes the "showPerformanceDetails" flag when
SearchParameters.showPerformanceDetails is true/false and omits it when nil, and
(2) an integration test that sends a search request with
showPerformanceDetails=true and asserts the decoded response contains a non-nil
performanceDetails object (and that its fields deserialize correctly). Locate
tests that reference
showRankingScore/showRankingScoreDetails/showMatchesPosition and copy their
structure, replacing those symbols with showPerformanceDetails and validation of
the performanceDetails payload.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# Search for tests covering showPerformanceDetails/performanceDetails
rg -n 'showPerformanceDetails|performanceDetails' --type swift -g '*test*' -g '*Test*' -g '*Tests*'

Repository: meilisearch/meilisearch-swift

Length of output: 55

---

🏁 Script executed:

# Also search more broadly in test directories
fd -e swift '(test|Test)' | xargs rg -l 'showPerformanceDetails|performanceDetails' 2>/dev/null || echo "No matches found in test files"

Repository: meilisearch/meilisearch-swift

Length of output: 103

---

🏁 Script executed:

# Examine the SearchParameters.swift file to see the full scope of changes
cat -n Sources/MeiliSearch/Model/SearchParameters.swift | head -160

Repository: meilisearch/meilisearch-swift

Length of output: 5674

---

🏁 Script executed:

# Look for test files related to SearchParameters
fd -e swift '(test|Test)' | xargs grep -l 'SearchParameters' 2>/dev/null | head -10

Repository: meilisearch/meilisearch-swift

Length of output: 169

---

🏁 Script executed:

# Check the unit test file for SearchParameters tests
wc -l Tests/MeiliSearchUnitTests/SearchTests.swift

Repository: meilisearch/meilisearch-swift

Length of output: 121

---

🏁 Script executed:

# Look for tests covering similar boolean parameters
rg -n 'showRankingScore|showMatchesPosition' Tests/MeiliSearchUnitTests/SearchTests.swift Tests/MeiliSearchIntegrationTests/SearchTests.swift -A 3 -B 3

Repository: meilisearch/meilisearch-swift

Length of output: 3893

---

🏁 Script executed:

# Search for any test that encodes SearchParameters or checks request bodies
rg -n 'SearchParameters|encode|request' Tests/MeiliSearchUnitTests/SearchTests.swift -A 2 | head -50

Repository: meilisearch/meilisearch-swift

Length of output: 854

---

🏁 Script executed:

# Get a sample of the unit test file to see the encoding test pattern
sed -n '180,220p' Tests/MeiliSearchUnitTests/SearchTests.swift

Repository: meilisearch/meilisearch-swift

Length of output: 1523

---

Add test coverage for showPerformanceDetails request encoding and response handling.

Code implementation is correct, but test coverage is missing. Similar boolean parameters (showRankingScore, showRankingScoreDetails, showMatchesPosition) have both unit and integration tests—add corresponding tests for the new showPerformanceDetails parameter to verify request encoding and response deserialization.

🤖 Prompt for AI Agents

In `@Sources/MeiliSearch/Model/SearchParameters.swift` around lines 71 - 76, Add
unit and integration tests that mirror the existing tests for
showRankingScore/showRankingScoreDetails/showMatchesPosition to cover the new
SearchParameters.showPerformanceDetails optional Bool: (1) a unit test that
verifies request encoding includes the "showPerformanceDetails" flag when
SearchParameters.showPerformanceDetails is true/false and omits it when nil, and
(2) an integration test that sends a search request with
showPerformanceDetails=true and asserts the decoded response contains a non-nil
performanceDetails object (and that its fields deserialize correctly). Locate
tests that reference
showRankingScore/showRankingScoreDetails/showMatchesPosition and copy their
structure, replacing those symbols with showPerformanceDetails and validation of
the performanceDetails payload.