Add filterableAttributes syntax API to settings

[kumarUjjawal]

Pull Request

Related issue

Fixes #660

What does this PR do?

PR checklist

Please check if your PR fulfills the following requirements:

• Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
• Have you read the contributing guidelines?
• Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!

Summary by CodeRabbit

• New Features

  • Advanced filterable-attributes configuration: supports both simple attribute names and richer settings objects with granular feature controls.
  • Retrieval and update operations accept the mixed-syntax representation for filterable attributes.

• Backward Compatibility

  • Existing simple-name workflows remain supported with automatic mapping to the new format.

• Documentation / Tests

  • Examples, tests, and docs updated to demonstrate the mixed-syntax behavior.

[coderabbitai]

Walkthrough

Adds mixed-syntax support for Meilisearch v1.14 filterableAttributes: introduces new types (FilterableAttribute, FilterableAttributesSettings, FilterFeatures, FilterFeatureModes), changes Settings to store Vec<FilterableAttribute>, updates Index methods to get/set advanced representations, and updates tests and examples to use the new types and API.

Changes

Cohort / File(s)	Summary
Core types & Settings src/settings.rs	Introduces FilterableAttribute (untagged enum), FilterableAttributesSettings, FilterFeatures, FilterFeatureModes; implements From<String> and From<&str>; changes Settings.filterable_attributes: Option<Vec<FilterableAttribute>>; adds with_filterable_attributes_advanced() and adapts with_filterable_attributes() to wrap strings as FilterableAttribute::Attribute.
Index API methods & requests src/settings.rs	Adds get_filterable_attributes_advanced() and set_filterable_attributes_advanced(); updates set_filterable_attributes() to accept/serialize Vec<FilterableAttribute> (wrapping string inputs for backward compatibility); updates internal request/response types from Vec<String> to Vec<FilterableAttribute> where applicable.
Tests src/documents.rs	Updates test assertions to expect Option<Vec<FilterableAttribute>> and uses FilterableAttribute::Attribute(...) variants; adds local imports for the new type.
Code samples .code-samples.meilisearch.yaml	Replaces simple list example with mixed-syntax example (plain attribute + settings object), imports meilisearch_sdk::settings types, and uses set_filterable_attributes_advanced in sample usage.

Sequence Diagram(s)

sequenceDiagram
    participant Client as Client Code
    participant Index as Index API
    participant Server as Meilisearch

    rect rgba(135,206,250,0.08)
    Note over Client,Index: Update filterable attributes (mixed syntax)
    Client->>Index: set_filterable_attributes_advanced([ "author", { attributePatterns:[...], features:{...} } ])
    Index->>Server: POST /settings/filterable-attributes  (body: Vec<FilterableAttribute>)
    Server-->>Index: TaskInfo
    Index-->>Client: Result<TaskInfo]
    end

    rect rgba(220,220,220,0.06)
    Note over Client,Index: Backward-compatible string usage
    Client->>Index: set_filterable_attributes(["author","genre"])
    Index->>Index: Wrap strings -> FilterableAttribute::Attribute(...)
    Index->>Server: POST /settings/filterable-attributes  (body: Vec<FilterableAttribute>)
    Server-->>Index: TaskInfo
    Index-->>Client: Result<TaskInfo]
    end

    rect rgba(144,238,144,0.06)
    Note over Client,Index: Retrieve mixed syntax
    Client->>Index: get_filterable_attributes_advanced()
    Index->>Server: GET /settings/filterable-attributes
    Server-->>Index: Vec<FilterableAttribute> (mixed)
    Index-->>Client: Result<Vec<FilterableAttribute>>
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Verify serde untagged behavior for FilterableAttribute and JSON round-tripping.
• Check From<String> / From<&str> implementations and places relying on previous Vec<String> types.
• Inspect Index request/response changes for correct serialization and backward-compatible wrapping.

Suggested labels

enhancement

Suggested reviewers

• curquiza
• irevoire

Poem

🐇 I nibble on types with a curious hop,
Strings and settings now share a shop.
Patterns and features in a tidy heap,
Filterable fields jump, awake from sleep—
A tiny hop for settings, code that won’t stop.

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: adding a new filterableAttributes syntax API to settings, matching the PR's primary objective.
Linked Issues check	✅ Passed	All three objectives from #660 are implemented: methods accept new filterableAttributes syntax with mixed plain names and objects [#660], methods return new syntax when Meilisearch provides it [#660], and code sample updated [#660].
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing new filterableAttributes syntax API. No unrelated modifications detected in the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

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

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 873f112 and 89f6c6b.

📒 Files selected for processing (1)

• src/settings.rs (7 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/settings.rs (2)

src/indexes.rs (20)

• client (186-188)
• client (232-234)
• client (320-322)
• client (376-378)
• client (428-430)
• client (473-475)
• client (522-525)
• client (556-558)
• client (634-636)
• client (700-702)
• client (970-972)
• client (1038-1040)
• client (1089-1091)
• index (2171-2171)
• index (2188-2189)
• index (2226-2226)
• index (2298-2298)
• index (2326-2326)
• index (2352-2352)
• index (2379-2379)

src/request.rs (1)

• body (49-56)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: integration-tests

🔇 Additional comments (5)

src/settings.rs (5)

67-114: Well-designed type system for mixed syntax support.

The new types correctly model Meilisearch v1.14's mixed filterable attributes syntax. The untagged FilterableAttribute enum will properly deserialize both plain strings and settings objects, and the From implementations provide ergonomic conversions.

---

372-399: Good backward-compatible builder methods.

The updated with_filterable_attributes maintains compatibility by wrapping strings as FilterableAttribute::Attribute, while the new with_filterable_attributes_advanced provides full control over mixed syntax. This is a clean API design.

---

1590-1633: Setter methods correctly handle backward compatibility.

Both set_filterable_attributes (wrapping strings) and set_filterable_attributes_advanced (accepting mixed syntax) are implemented correctly. The request body uses Vec<FilterableAttribute>, which will serialize properly to the mixed syntax format expected by Meilisearch v1.14.

---

2907-3013: Good test coverage for new functionality.

The tests properly verify:

• Builder method with mixed syntax
• Request body serialization
• Response deserialization

Suggested additional test:

Consider adding a test that demonstrates the deserialization failure when using the legacy get_filterable_attributes() with a mixed-syntax response. This would help document the limitation and guide users toward the advanced method.

#[meilisearch_test]
async fn test_get_filterable_attributes_fails_with_mixed_syntax() -> Result<(), Error> {
    let mut s = mockito::Server::new_async().await;
    let client = Client::new(s.url(), Some("masterKey")).unwrap();
    let index = client.index("test");
    
    // Server returns mixed syntax
    let body = json!(["author", {"attributePatterns": ["genre"], "features": {...}}]);
    
    let _mock = s.mock("GET", "/indexes/test/settings/filterable-attributes")
        .with_status(200)
        .with_body(body.to_string())
        .create_async()
        .await;
    
    // This should fail to deserialize
    let result = index.get_filterable_attributes().await;
    assert!(result.is_err(), "Should fail to deserialize mixed syntax to Vec<String>");
    
    Ok(())
}

---

244-248: Breaking change in filterable_attributes field type has conversion helpers to ease migration.

The type changed from Option<Vec<String>> to Option<Vec<FilterableAttribute>>, which breaks direct field access. However, FilterableAttribute implements From<String> and From<&str>, so most method calls remain compatible. Tests in the codebase (src/documents.rs) have already been updated to use the new type.

The breaking change is contained to code that directly accesses this public field. If this is a published library, document the breaking change and bump the major version per semantic versioning.

---

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

🧹 Nitpick comments (1)

src/settings.rs (1)

1614-1633: Consider more flexible signature for set_filterable_attributes_advanced.

The current signature impl IntoIterator<Item = FilterableAttribute> requires owned values, which prevents passing borrowed slices like &[FilterableAttribute]. This differs from other setter methods (e.g., set_stop_words at line 1497) that use Item = impl AsRef<str> to accept both owned and borrowed values.

While the current design is simpler and works correctly, consider whether accepting borrowed values would improve ergonomics:

pub async fn set_filterable_attributes_advanced(
    &self,
    filterable_attributes: &[FilterableAttribute],
) -> Result<TaskInfo, Error> {
    self.client
        .http_client
        .request::<(), Vec<FilterableAttribute>, TaskInfo>(
            &format!(...),
            Method::Put {
                query: (),
                body: filterable_attributes.to_vec(),
            },
            202,
        )
        .await
}

This would allow callers to retain ownership of their configurations.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e90a3c2 and b926f13.

📒 Files selected for processing (3)

• .code-samples.meilisearch.yaml (1 hunks)
• src/documents.rs (1 hunks)
• src/settings.rs (6 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/settings.rs (1)

src/indexes.rs (13)

• client (186-188)
• client (232-234)
• client (320-322)
• client (376-378)
• client (428-430)
• client (473-475)
• client (522-525)
• client (556-558)
• client (634-636)
• client (700-702)
• client (970-972)
• client (1038-1040)
• client (1089-1091)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: integration-tests

🔇 Additional comments (5)

.code-samples.meilisearch.yaml (1)

549-567: LGTM: Imports and mixed-syntax demonstration are correct.

The new types are properly imported and the example correctly demonstrates both legacy syntax (using .into() for string conversion) and the new settings object syntax.

src/documents.rs (1)

706-713: LGTM: Test correctly updated for new FilterableAttribute type.

The test properly imports and uses the new FilterableAttribute enum, wrapping attribute names in the Attribute variant. This correctly reflects the changes to Settings::filterable_attributes from Option<Vec<String>> to Option<Vec<FilterableAttribute>>.

src/settings.rs (3)

67-114: LGTM: Well-structured types for mixed-syntax filterable attributes.

The new types properly model Meilisearch v1.14's advanced filterable attributes syntax:

• Hierarchical structure with FilterFeatureModes → FilterFeatures → FilterableAttributesSettings
• Untagged enum allows seamless JSON serialization of mixed plain strings and settings objects
• From implementations provide ergonomic string-to-attribute conversion
• Proper camelCase JSON mapping via serde annotations

---

244-399: LGTM: Backward-compatible API design with advanced method.

The changes maintain backward compatibility:

• Existing with_filterable_attributes accepts strings and converts internally
• New with_filterable_attributes_advanced accepts mixed FilterableAttribute items
• Clear documentation distinguishes the two approaches

This design allows gradual adoption of the new syntax while preserving existing code.

---

767-799: LGTM: Dual getter methods provide both legacy and advanced access.

The addition of get_filterable_attributes_advanced alongside the existing get_filterable_attributes enables:

• Legacy code continues using Vec<String> return type
• New code can retrieve mixed-syntax Vec<FilterableAttribute>

Both methods query the same endpoint but deserialize to different types, maintaining backward compatibility.

[codecov]

Codecov Report

❌ Patch coverage is 97.77778% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.42%. Comparing base (e90a3c2) to head (89f6c6b).

Files with missing lines	Patch %	Lines
src/settings.rs	97.72%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #730      +/-   ##
==========================================
+ Coverage   86.18%   86.42%   +0.23%     
==========================================
  Files          20       20              
  Lines        6263     6395     +132     
==========================================
+ Hits         5398     5527     +129     
- Misses        865      868       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.