feat(sdk): add high-level Search helpers + ffi bindings by bnjbvr · Pull Request #6394 · matrix-org/matrix-rust-sdk

bnjbvr · 2026-04-01T08:13:30Z

Starting to extract relevant helpers that can be merged ahead of having search spider all rooms in background.

Part of #5350.

I've documented the public API Changes in the appropriate CHANGELOG.md files.
This PR was made with the help of AI (autocomplete).

codecov · 2026-04-01T08:24:41Z

Codecov Report

❌ Patch coverage is 96.70659% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.86%. Comparing base (b066260) to head (7fbbdba).
⚠️ Report is 29 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
crates/matrix-sdk/src/message_search.rs	96.69%	3 Missing and 8 partials ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             main    #6394    +/-   ##
========================================
  Coverage   89.85%   89.86%            
========================================
  Files         378      379     +1     
  Lines      104569   104893   +324     
  Branches   104569   104893   +324     
========================================
+ Hits        93964    94264   +300     
- Misses       6998     7012    +14     
- Partials     3607     3617    +10

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

codspeed-hq · 2026-04-01T08:37:19Z

Merging this PR will not alter performance

✅ 50 untouched benchmarks

_{Comparing bnjbvr/ui-search-iterators (7fbbdba) with main (1bff8cb)}

bnjbvr · 2026-04-02T11:23:51Z

This PR is in a sufficiently good state that it would allow FFI embedders to try out the search feature, build a search UI and so on. Doesn't do automatic indexation of all content, that problem is currently left as an exercise to the reader/embedder.

poljar

This looks mostly good, there is some missing documentation here and there though.

I'm also wondering if this would be better modeled as a stream, which is my main concern.

poljar · 2026-04-09T12:03:45Z

+    EventLoadError(#[from] matrix_sdk::Error),
+}
+
+/// An async iterator for a search query in a single room.


Hmm, a bit worried to call this an async iterator as some folks might expect this.

I wasn't too worried about that (async iterators are nightly only and have been for a while, so I wouldn't expect them to become stable any time soon?), but I like the idea of being able to add stream combinators much better 🥳

poljar · 2026-04-09T12:05:07Z

+#[derive(thiserror::Error, Debug)]
+pub enum SearchError {


Missing docs on the type and enum variants.

Since both error variants are transparent, I don't think it's really worth documenting them, since the interesting documentation should rather be on the wrapped inner error type. And ditto for the overall error, not sure that adding "an error that happened during search" makes it clearer, but I'll add a tiny one though.

poljar · 2026-04-09T12:05:24Z

+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+


The module is public but there's no module-level documentation.

It would be nice to have some sort of introductory example on how this should be used in the module level docs.

Still no example? Could we please add one as it makes things for newcommers much easier.

poljar · 2026-04-09T12:33:05Z

+
+#[matrix_sdk_ffi_macros::export]
+impl Room {
+    pub fn search(&self, query: String) -> RoomSearchIterator {


Missing docs.

In fact, a lot of the new types/functions here don't have docs.

Yeah, I don't think adding docs must be a religion, when the doc only repeats the function name or states something clearly obvious 🤷

I'll add some for your pleasure, where I think it makes the most sense.

poljar · 2026-04-09T12:38:53Z

+            return Ok(None);
+        }
+
+        let result = self.room.search(&self.query, num_results, self.offset).await?;


This function only uses the local index, which is fine for a first prototype, but it should use the homeserver for rooms that aren't encrypted.

A TODO item to record this might make sense.

For what it's worth: I do NOT think we should use the homeserver search for rooms that aren't encrypted, otherwise we need to make sure that the behavior of local search is exactly (and not more) than that of the homeserver search. Otherwise, it would be observable that we're using one or the other implementation, according to the search results, and the room encryption state.

This extra requirement may restrict what we're able to do (after all, we could do better search locally than what the search CS APIs ought to offer, because tantivy has fancy keywords, we could index more), and it might be hard to follow the implementation-specific details, especially as they evolve (which could be super slow as adding features to the homeserver is usually a slow process; or involve implementation-specific details, and show preference to a HS implementation rather than another).

As a result, I would strongly advocate for using a local index even in the case of unencrypted rooms, otherwise the semantics of our local search API would likely be harder to define.

I agree with all the arguments why it would be better to use local search for both types of rooms.

Sadly none of them matter since you can't expect every user, and potentially every device, to locally index something like Matrix HQ. It's just not possible for storage, bandwidth, and CPU usage on the device as well as on the homeserver, reasons.

You could argue that you don't need to index the whole lot of Matrix HQ, but then you have incomplete search results. This would be strictly worse than a complete but less feature-full search implementation.

It's just not feasible to implement full-text search in this manner.

That's a fair point (although I've managed to index the whole of the "new" ¹ MatrixHQ in around 30 minutes!). Will add a TODO 👍

Footnotes

the v11 room created around december 25 ↩

poljar · 2026-04-09T12:51:03Z

+    /// if there are no more results.
+    pub async fn next(
+        &mut self,
+        num_results: usize,


I wonder if we should put this argument into the builder.

Then we could convert this into a proper Stream which would allow users to use many of the available adapters to post-process the results.

This would also then require a rename of the type, but I think that's fine as well as we wouldn't confuse people by calling something an iterator which doesn't implement Iterator or AsyncIterator.

(I still need to address this, first.)

…racking

poljar · 2026-04-17T11:15:44Z

+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+


Still no example? Could we please add one as it makes things for newcommers much easier.

bnjbvr force-pushed the bnjbvr/ui-search-iterators branch from 6ed213a to 5f0244b Compare April 2, 2026 11:22

bnjbvr marked this pull request as ready for review April 2, 2026 11:22

bnjbvr requested a review from a team as a code owner April 2, 2026 11:22

bnjbvr requested review from stefanceriu and removed request for a team April 2, 2026 11:22

poljar requested review from poljar and removed request for stefanceriu April 8, 2026 14:26

poljar requested changes Apr 9, 2026

View reviewed changes

bnjbvr force-pushed the bnjbvr/ui-search-iterators branch 3 times, most recently from 232b5bc to 89c2da8 Compare April 14, 2026 14:03

bnjbvr marked this pull request as draft April 14, 2026 14:03

bnjbvr added 14 commits April 17, 2026 12:02

feat(search): higher-level Search API

4ff31c4

feat(multiverse): add support for global search (ctrl+g)

4f20907

feat(ffi): allow enabling search with a search index store

1a951a6

feat(ffi): bindings for search

09c2e35

chore: add changelog entries for search!

89b10f1

chore: address first batch of review comments

a9475f3

refactor(search): simplify code around global search

b5b73aa

refactor(search): avoid using a HashMap for linear iteration

7935058

refactor(search): simplify global search more by avoiding is_done t…

4056b7a

…racking

refactor(sdk): move search related functions to a message_search module

bc52268

refactor(sdk): move the high-level search helpers back to the SDK crate

757347d

refactor(search): pass the number of results per batch in the ctors

bbeac32

refactor(sdk): Room::search_messages and Client::search_messages

736b925

refactor(ffi): remove unused struct

5d3f324

chore: update changelogs

a37fdc2

bnjbvr force-pushed the bnjbvr/ui-search-iterators branch from 3e7e41f to a37fdc2 Compare April 17, 2026 10:18

bnjbvr marked this pull request as ready for review April 17, 2026 10:18

poljar approved these changes Apr 17, 2026

View reviewed changes

doc(sdk): add a module doc code example for search

7fbbdba

bnjbvr force-pushed the bnjbvr/ui-search-iterators branch from 0cdf60b to 7fbbdba Compare April 20, 2026 10:03

bnjbvr enabled auto-merge (rebase) April 20, 2026 10:16

bnjbvr merged commit 8b14a89 into main Apr 20, 2026
54 checks passed

bnjbvr deleted the bnjbvr/ui-search-iterators branch April 20, 2026 10:18

bnjbvr mentioned this pull request Apr 20, 2026

Meta: Full text search support #5350

Open

24 tasks

Conversation

bnjbvr commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

codspeed-hq Bot commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Uh oh!

bnjbvr commented Apr 2, 2026

Uh oh!

poljar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Footnotes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bnjbvr commented Apr 1, 2026 •

edited

Loading

codecov Bot commented Apr 1, 2026 •

edited

Loading

codspeed-hq Bot commented Apr 1, 2026 •

edited

Loading