feat(llc, core, persistence): Add support for `PredefinedFilters` on `QueryChannels` by VelikovPetar · Pull Request #2709 · GetStream/stream-chat-flutter

VelikovPetar · 2026-06-02T13:28:12Z

Submit a pull request

CLA

I have signed the Stream CLA (required).
The code changes follow best practices
Code changes are tested (add some information if not applicable)

Description of the pull request

Adds support for server-defined predefined filters on queryChannels across the LLC, persistence, and core layers.

A predefined filter is a named filter/sort preset that lives on the server. The client sends predefined_filter (plus optional filter_values / sort_values to interpolate placeholders) instead of an inline filter, and the server echoes back the materialized filter and sort it applied.

stream_chat (LLC)

ChannelApi.queryChannels and StreamChatClient.queryChannels accept predefinedFilter, filterValues, sortValues.
New StreamChatClient.queryChannelsWithResult returns a QueryChannelsResult exposing both the live channels and the server-resolved PredefinedFilter (name + materialized filter + sort).
New PredefinedFilter model and predefined_filter field on QueryChannelsResponse.
SortOption<T>.fromJson added so sort specs can round-trip through persistence.
New ChatPersistenceClient hooks: getChannelStatesByPredefinedFilter and updateChannelQueriesByPredefinedFilter (default no-op so existing implementations keep compiling).

stream_chat_persistence

New channel_query_metadata table that stores the server-resolved filter + sort keyed by the predefined-filter query hash, so offline reads reconstruct the exact resolved spec the server applied.
New FilterConverter and ChannelStateSortOrderConverter Drift converters.
StreamChatPersistenceClient implements the new hooks; ChannelQueryDao gains updateChannelQueriesByPredefinedFilter and getChannelsAndSpecByPredefinedFilter.

stream_chat_flutter_core

StreamChannelListController accepts predefinedFilter, filterValues, sortValues. When set, they take precedence over filter / channelStateSort.
The controller tracks a _resolvedChannelStateSort that is overwritten with the server-resolved sort on every successful query, so event-driven inserts keep matching the server's ordering even when the caller only specifies a predefinedFilter.

Sample app

ChannelList now uses the stream_chat_flutter_sample_app predefined filter (interpolated with the current user_id) to demonstrate the flow end-to-end.

How to test

Run the sample app and confirm the channel list renders, paginates, and reacts to events as before.
Toggle offline (airplane mode) after an online query and reopen — channels for the predefined-filter query should be served from persistence, ordered using the server-resolved sort.

Test coverage

predefined_filter_test.dart — model.
predefined_filter_defaults_test.dart — fallback-sort selection.
client_test.dart — online/offline queryChannels paths and queryChannelsWithResult.
channel_api_test.dart — request payload assertions.
filter_converter_test.dart / sort_order_converter_test.dart — Drift converters.
channel_query_dao_test.dart — DAO read/write of cids + metadata.
stream_chat_persistence_client_test.dart — persistence client integration.
stream_channel_list_controller_test.dart — controller path including resolved-sort tracking.

… dynamic> to Filter.

…troller.

coderabbitai · 2026-06-02T13:28:22Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 8df410e7-28f7-4a5d-99ad-311cf5bd103d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/FLU-357_predefined_filters_v10

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

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

github-actions · 2026-06-02T13:28:44Z

⚠️ Database Entity Files Modified

The following database entity files have been modified in this PR:

packages/stream_chat_persistence/lib/src/entity/channel_queries_metadata.dart
packages/stream_chat_persistence/lib/src/entity/entity.dart

📝 Remember to:

Update database version in db/drift_chat_database.dart.
Update entity schema tests if necessary.

Note: This comment is automatically generated by the CI workflow.

VelikovPetar · 2026-06-02T14:02:22Z

+  /// Yields the offline-cached result first (when available), followed by
+  /// the online result. Concurrent identical online queries are coalesced
+  /// via [_queryChannelsCache].
+  Stream<QueryChannelsResult> queryChannelsWithResult({


I wasn't sure about the naming here, I tried to make it as explicit as possible. (it wasn't really possible to use the existing queryChannels without a breaking change, as we must change the return type).

VelikovPetar · 2026-06-02T14:05:17Z

+/// Carries the live [Channel] instances matching the query alongside the
+/// server-resolved [PredefinedFilter] spec (when one is associated with the
+/// query).
+class QueryChannelsResult {


I introduced this new model to serve as a container for the result of the StreamChatClient.queryChannelsWithResult.

VelikovPetar · 2026-06-02T14:10:06Z

  Future<List<Channel>> queryChannelsOnline({
    Filter? filter,
    SortOrder<ChannelState>? sort,
+    String? predefinedFilter,


Note: At the moment I didn't expose public queryChannelsWithResultOnline/queryChannelsWithResultOffline -> only the new queryChannelsWithResults is public. I didn't want to pollute the public API, with methods which most likely will not be used. Let me know if you think we should expose them as well.

VelikovPetar · 2026-06-02T14:19:48Z

          // passed options
          if (sort != null) 'sort': sort,
          if (filter != null) 'filter_conditions': filter,
+          if (predefinedFilter != null) 'predefined_filter': predefinedFilter,


I didn't add any guards preventing the users to send both predefined_filter and filter/sort. The BE will prioritise the predefined filter if available.
Another option would be to:

Fail early (throw error when building the StreamChannelListController, or when calling client.queryChannels)

Override filter/sort with null when predefinedFilter exists

But overall, I a think that letting the server handle this scenario would be the best, I don't want to introduce front-end guards which might become invalid if the server changes the default behaviour.

Let me know if you think we should introduce some front-end checks anyway.

VelikovPetar · 2026-06-02T16:19:37Z

+  /// falling back to `last_updated` otherwise — this mirrors the server's
+  /// default sort for channel queries.
+  SortOrder<ChannelState> get predefinedFilterFallbackSort {
+    if (_touchesField('last_message_at')) {


Note: This follows the BE default sort, if no sort is defined in the predefined filter. See this discussion.

VelikovPetar · 2026-06-02T16:20:34Z

+  /// Default implementation returns an empty response; persistence
+  /// implementations that support predefined-filter caching should override
+  /// this.
+  Future<QueryChannelsResponse> getChannelStatesByPredefinedFilter({


Do you think it is OK to return QueryChannelsResponse here - or should we introduce a new specific model for this?

codecov · 2026-06-02T20:04:57Z

Codecov Report

❌ Patch coverage is 94.83871% with 8 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v10.0.0@803b70d). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/stream_chat/lib/src/client/client.dart	92.30%	3 Missing ⚠️
...tream_chat/lib/src/db/chat_persistence_client.dart	0.00%	3 Missing ⚠️
...r_core/lib/src/stream_channel_list_controller.dart	93.75%	1 Missing ⚠️
...hat_persistence/lib/src/dao/channel_query_dao.dart	97.50%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             v10.0.0    #2709   +/-   ##
==========================================
  Coverage           ?   67.94%           
==========================================
  Files              ?      413           
  Lines              ?    24641           
  Branches           ?        0           
==========================================
  Hits               ?    16742           
  Misses             ?     7899           
  Partials           ?        0

☔ 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.

VelikovPetar added 7 commits May 29, 2026 16:59

feat(llc): Add predefined_filters support on LLC.

ff5c6ce

feat(llc): Add predefined_filters support in the persistence layer.

5dc6bd4

feat(llc): Changed predefined_filter filter property from Map<String,…

cfd8283

… dynamic> to Filter.

feat(llc): Add predefined_filter_test.dart.

852cd16

feat(llc): Add support for predefined filters in StreamChannelListCon…

6e2c1c2

…troller.

refactor(sample): Use predefined filters in the sample app.

c8fd41e

refactor(llc): Move predefined_filter_defaults to utils package.

33bc631

VelikovPetar commented Jun 2, 2026

View reviewed changes

Merge branch 'v10.0.0' into feature/FLU-357_predefined_filters_v10

420ecc9

VelikovPetar marked this pull request as ready for review June 2, 2026 18:04

Regenerate drift_chat_database.g.dart.

7ebb1aa

Merge branch 'v10.0.0' into feature/FLU-357_predefined_filters_v10

68cde5b

VelikovPetar requested a review from a team June 3, 2026 10:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(llc, core, persistence): Add support for `PredefinedFilters` on `QueryChannels`#2709

feat(llc, core, persistence): Add support for `PredefinedFilters` on `QueryChannels`#2709
VelikovPetar wants to merge 10 commits into
v10.0.0from
feature/FLU-357_predefined_filters_v10

VelikovPetar commented Jun 2, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

Review skipped

Uh oh!

github-actions Bot commented Jun 2, 2026 •

edited

Loading

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

VelikovPetar Jun 2, 2026

Uh oh!

codecov Bot commented Jun 2, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

VelikovPetar commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Submit a pull request

CLA

Description of the pull request

How to test

Test coverage

Uh oh!

coderabbitai Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

github-actions Bot commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Database Entity Files Modified

📝 Remember to:

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

VelikovPetar Jun 2, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

VelikovPetar commented Jun 2, 2026 •

edited

Loading

coderabbitai Bot commented Jun 2, 2026 •

edited

Loading

github-actions Bot commented Jun 2, 2026 •

edited

Loading

codecov Bot commented Jun 2, 2026 •

edited

Loading