perf(llc): Move pinned messages pagination to SQL

Author: VelikovPetar

packages/stream_chat_persistence/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Reduce the number of DB reads in the `ChatPersistenceClient.getChannelStates` method.
 - Read only the messages matching the `PaginationParams` from DB when calling `MessageDao.getMessagesByCid` instead of reading all messages for the channel and applying pagination in memory.
+- Read only the messages matching the `PaginationParams` from DB when calling `PinnedMessageDao.getMessagesByCid` instead of reading all pinned messages for the channel and applying pagination in memory.
 - Read only the reactions matching the `userId` from DB when calling `ReactionDao.getReactionsByUserId` instead of reading all reactions for the message and filtering in memory.
 - Read only the reactions matching the `userId` from DB when calling `PinnedMessageReactionDao.getReactionsByUserId` instead of reading all reactions for the message and filtering in memory.
 - Improve the message read times from DB.
@@ -13,6 +14,8 @@
 - `MessageDao.getMessagesByCid` now honours `PaginationParams.lessThanOrEqual` and `PaginationParams.greaterThanOrEqual` (inclusive of the cursor message), in addition to the existing strict `lessThan`/`greaterThan`.
 - `MessageDao.getMessagesByCid` now treats `PaginationParams.greaterThan` as strict (exclusive of the cursor), matching the `PaginationParams` contract and the existing `lessThan` behaviour.
 - `MessageDao.getMessagesByCid` with a forward cursor (`greaterThan`/`greaterThanOrEqual`) and a `limit` now returns the messages immediately AFTER the pivot, instead of the channel tail — mirroring how `lessThan` already returned the messages immediately before the pivot.
+- `PinnedMessageDao.getMessagesByCid` now honours `PaginationParams.lessThanOrEqual` and `PaginationParams.greaterThanOrEqual` (inclusive of the cursor message), in addition to the existing strict `lessThan`/`greaterThan`.
+- `PinnedMessageDao.getMessagesByCid` with a forward cursor (`greaterThan`/`greaterThanOrEqual`) and a `limit` now returns the messages immediately AFTER the pivot, instead of the channel tail.
 
 
 ## 9.24.0

packages/stream_chat_persistence/lib/src/dao/pinned_message_dao.dart

@@ -242,6 +242,38 @@ class PinnedMessageDao extends DatabaseAccessor<DriftChatDatabase>
     bool fetchDraft = true,
     PaginationParams? messagePagination,
   }) async {
+    final (
+      lessThanCursor,
+      lessThanOrEqualCursor,
+      greaterThanCursor,
+      greaterThanOrEqualCursor,
+    ) = await (
+      _lookupCursor(messagePagination?.lessThan),
+      _lookupCursor(messagePagination?.lessThanOrEqual),
+      _lookupCursor(messagePagination?.greaterThan),
+      _lookupCursor(messagePagination?.greaterThanOrEqual),
+    ).wait;
+
+    // When the caller is paginating forward (greaterThan / greaterThanOrEqual
+    // only), order ASC so the SQL `LIMIT` retains the N messages immediately
+    // AFTER the cursor. Otherwise order DESC so `LIMIT` retains the N most
+    // recent (closest to a `lessThan` cursor, or the channel tail when no
+    // cursor is set). The final result is always reshaped to ASC for display.
+    final isForwardPagination =
+        (greaterThanCursor != null || greaterThanOrEqualCursor != null) &&
+            lessThanCursor == null &&
+            lessThanOrEqualCursor == null;
+
+    final orderBy = isForwardPagination
+        ? [
+            OrderingTerm.asc(pinnedMessages.createdAt),
+            OrderingTerm.asc(pinnedMessages.id),
+          ]
+        : [
+            OrderingTerm.desc(pinnedMessages.createdAt),
+            OrderingTerm.desc(pinnedMessages.id),
+          ];
+
     final query = select(pinnedMessages).join([
       leftOuterJoin(_users, pinnedMessages.userId.equalsExp(_users.id)),
       leftOuterJoin(
@@ -252,35 +284,48 @@ class PinnedMessageDao extends DatabaseAccessor<DriftChatDatabase>
       ..where(pinnedMessages.channelCid.equals(cid))
       ..where(pinnedMessages.parentId.isNull() |
           pinnedMessages.showInChannel.equals(true))
-      ..orderBy([OrderingTerm.asc(pinnedMessages.createdAt)]);
+      ..orderBy(orderBy);
 
-    final rows = await query.get();
-    final msgList = await _messagesFromJoinRows(rows, fetchDraft: fetchDraft);
+    // Cursor predicates compare the full `(createdAt, id)` tuple — the same
+    // key used in ORDER BY — so messages sharing a `createdAt` with the cursor
+    // fall on the correct side of the boundary. Filtering on `createdAt` alone
+    // would skip or repeat those siblings across pages.
+    if (lessThanCursor case final c?) {
+      query.where(
+        pinnedMessages.createdAt.isSmallerThanValue(c.createdAt) |
+            (pinnedMessages.createdAt.equals(c.createdAt) &
+                pinnedMessages.id.isSmallerThanValue(c.id)),
+      );
+    }
+    if (lessThanOrEqualCursor case final c?) {
+      query.where(
+        pinnedMessages.createdAt.isSmallerThanValue(c.createdAt) |
+            (pinnedMessages.createdAt.equals(c.createdAt) &
+                pinnedMessages.id.isSmallerOrEqualValue(c.id)),
+      );
+    }
+    if (greaterThanCursor case final c?) {
+      query.where(
+        pinnedMessages.createdAt.isBiggerThanValue(c.createdAt) |
+            (pinnedMessages.createdAt.equals(c.createdAt) &
+                pinnedMessages.id.isBiggerThanValue(c.id)),
+      );
+    }
+    if (greaterThanOrEqualCursor case final c?) {
+      query.where(
+        pinnedMessages.createdAt.isBiggerThanValue(c.createdAt) |
+            (pinnedMessages.createdAt.equals(c.createdAt) &
+                pinnedMessages.id.isBiggerOrEqualValue(c.id)),
+      );
+    }
 
-    if (msgList.isNotEmpty) {
-      final mutable = msgList.toList();
-      if (messagePagination?.lessThan != null) {
-        final lessThanIndex = mutable.indexWhere(
-          (m) => m.id == messagePagination!.lessThan,
-        );
-        if (lessThanIndex != -1) {
-          mutable.removeRange(lessThanIndex, mutable.length);
-        }
-      }
-      if (messagePagination?.greaterThan != null) {
-        final greaterThanIndex = mutable.indexWhere(
-          (m) => m.id == messagePagination!.greaterThan,
-        );
-        if (greaterThanIndex != -1) {
-          mutable.removeRange(0, greaterThanIndex);
-        }
-      }
-      if (messagePagination?.limit != null) {
-        return mutable.take(messagePagination!.limit).toList();
-      }
-      return mutable;
+    if (messagePagination != null) {
+      query.limit(messagePagination.limit);
     }
-    return msgList;
+
+    final rows = await query.get();
+    final orderedRows = isForwardPagination ? rows : rows.reversed.toList();
+    return _messagesFromJoinRows(orderedRows, fetchDraft: fetchDraft);
   }
 
   /// Updates the message data of a particular channel with
@@ -304,4 +349,23 @@ class PinnedMessageDao extends DatabaseAccessor<DriftChatDatabase>
       (batch) => batch.insertAllOnConflictUpdate(pinnedMessages, entities),
     );
   }
+
+  /// Returns the `(createdAt, id)` cursor for the pinned message with [id] in
+  /// the local cache, or `null` if [id] is null, the message isn't cached, or
+  /// isn't visible in the channel (i.e. a thread reply with
+  /// `showInChannel = false`).
+  Future<({DateTime createdAt, String id})?> _lookupCursor(String? id) async {
+    if (id == null) return null;
+    final createdAt = await (selectOnly(pinnedMessages)
+          ..addColumns([pinnedMessages.createdAt])
+          ..where(pinnedMessages.id.equals(id))
+          ..where(
+            pinnedMessages.parentId.isNull() |
+                pinnedMessages.showInChannel.equals(true),
+          ))
+        .map((row) => row.read(pinnedMessages.createdAt))
+        .getSingleOrNull();
+    if (createdAt == null) return null;
+    return (createdAt: createdAt, id: id);
+  }
 }

packages/stream_chat_persistence/test/src/dao/pinned_message_dao_test.dart

@@ -25,14 +25,20 @@ void main() {
   }) async {
     final channels = [ChannelModel(cid: cid)];
     final users = List.generate(count, (index) => User(id: 'testUserId$index'));
+    // Strictly monotonic `createdAt` per message so SQL-side pagination
+    // filters (`WHERE createdAt < cutoff`, `ORDER BY createdAt ASC`) can't be
+    // confused by ties. Drift stores `DateTime` as integer Unix seconds by
+    // default, so the offset must be at least 1 second per row — otherwise
+    // sub-second offsets all round-trip onto the same second.
+    final baseTime = DateTime.now();
     final messages = List.generate(
       count,
       (index) => Message(
         id: 'testMessageId$cid$index',
         type: 'testType',
         user: users[index],
         channelRole: 'channel_member',
-        createdAt: DateTime.now(),
+        createdAt: baseTime.add(Duration(seconds: index)),
         shadowed: math.Random().nextBool(),
         replyCount: index,
         updatedAt: DateTime.now(),
@@ -54,7 +60,7 @@ void main() {
         type: 'testType',
         user: users[index],
         channelRole: 'channel_member',
-        createdAt: DateTime.now(),
+        createdAt: baseTime.add(Duration(seconds: index)),
         shadowed: math.Random().nextBool(),
         replyCount: index,
         updatedAt: DateTime.now(),
@@ -75,7 +81,7 @@ void main() {
         channelRole: 'channel_member',
         parentId:
             mapAllThreadToFirstMessage ? messages[0].id : messages[index].id,
-        createdAt: DateTime.now(),
+        createdAt: baseTime.add(Duration(seconds: index)),
         shadowed: math.Random().nextBool(),
         replyCount: index,
         updatedAt: DateTime.now(),
@@ -380,8 +386,8 @@ void main() {
       messagePagination: pagination,
     );
     expect(fetchedMessages.length, limit);
-    expect(fetchedMessages.first.id, greaterThan);
-    expect(fetchedMessages.last.id != lessThan, true);
+    expect(fetchedMessages.first.id, 'testMessageId${cid}10');
+    expect(fetchedMessages.last.id, 'testMessageId${cid}24');
   });
 
   test('updateMessages', () async {