From 11c9e5bb3d401cf16bdb4e2696ddc480f0af7141 Mon Sep 17 00:00:00 2001 From: JohnLu2004 Date: Mon, 25 Mar 2024 12:21:11 -0400 Subject: [PATCH] api-docs: Document optimization of is:unread filter. Documents that the is:unread narrow/filter can be an important optimization for clients to consider using in certain cases. Fixes #28328. --- api_docs/construct-narrow.md | 6 ++++++ zerver/openapi/zulip.yaml | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/api_docs/construct-narrow.md b/api_docs/construct-narrow.md index a7e3554567..2bb4707274 100644 --- a/api_docs/construct-narrow.md +++ b/api_docs/construct-narrow.md @@ -45,6 +45,12 @@ operator, search the current user's personal message history. See [searching shared history](/help/search-for-messages#searching-shared-history) for details. +Clients should note that the `is:unread` filter takes advantage of the +fact that there is a database index for unread messages, which can be an +important optimization when fetching messages in certain cases (e.g. +when [adding the `read` flag to a user's personal +messages](/api/update-message-flags-for-narrow)). + **Changes**: In Zulip 7.0 (feature level 177), support was added for three filters related to direct messages: `is:dm`, `dm` and `dm-including`. The `dm` operator replaced and deprecated the diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 3956102bf4..a221afe11e 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -7043,6 +7043,11 @@ paths: The narrow you want update flags within. See how to [construct a narrow](/api/construct-narrow). + Note that, when adding the `read` flag to messages, clients should + consider including a narrow with the `is:unread` filter as an + optimization. Including that filter takes advantage of the fact that + the server has a database index for unread messages. + **Changes**: In Zulip 7.0 (feature level 177), narrows gained support for three new filters related to direct messages: `is:dm`, `dm` and `dm-including`; replacing and deprecating `is:private`, `pm-with` and