mirror of
https://github.com/zulip/zulip.git
synced 2025-11-03 21:43:21 +00:00
3cb14ba7db
On the server-side, the implementation of the "near" operator is a noop. Clients should instead use the "anchor" parameter to express the "near" operator in a search box or URL fragment.
184 lines
6.8 KiB
Markdown
184 lines
6.8 KiB
Markdown
# Construct a narrow
|
|
|
|
A **narrow** is a set of filters for Zulip messages, that can be based
|
|
on many different factors (like sender, channel, topic, search
|
|
keywords, etc.). Narrows are used in various places in the Zulip
|
|
API (most importantly, in the API for fetching messages).
|
|
|
|
It is simplest to explain the algorithm for encoding a search as a
|
|
narrow using a single example. Consider the following search query
|
|
(written as it would be entered in the Zulip web app's search box).
|
|
It filters for messages sent to channel `announce`, not sent by
|
|
`iago@zulip.com`, and containing the words `cool` and `sunglasses`:
|
|
|
|
```
|
|
channel:announce -sender:iago@zulip.com cool sunglasses
|
|
```
|
|
|
|
This query would be JSON-encoded for use in the Zulip API using JSON
|
|
as a list of simple objects, as follows:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"operator": "channel",
|
|
"operand": "announce"
|
|
},
|
|
{
|
|
"operator": "sender",
|
|
"operand": "iago@zulip.com",
|
|
"negated": true
|
|
},
|
|
{
|
|
"operator": "search",
|
|
"operand": "cool sunglasses"
|
|
}
|
|
]
|
|
```
|
|
|
|
The Zulip help center article on [searching for messages](/help/search-for-messages)
|
|
documents the majority of the search/narrow options supported by the
|
|
Zulip API.
|
|
|
|
Note that many narrows, including all that lack a `channel` or `channels`
|
|
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 9.0 (feature level 271), support was added for a new filter
|
|
operator, `with`, which uses a [message ID](#message-ids) for its
|
|
operand, and is designed for creating permanent links to topics.
|
|
|
|
* In Zulip 9.0 (feature level 265), support was added for a new
|
|
`is:followed` filter, matching messages in topics that the current
|
|
user is [following](/help/follow-a-topic).
|
|
|
|
* In Zulip 9.0 (feature level 250), support was added for two filters
|
|
related to stream messages: `channel` and `channels`. The `channel`
|
|
operator is an alias for the `stream` operator. The `channels`
|
|
operator is an alias for the `streams` operator. Both `channel` and
|
|
`channels` return the same exact results as `stream` and `streams`
|
|
respectively.
|
|
|
|
* In Zulip 9.0 (feature level 249), support was added for a new filter,
|
|
`has:reaction`, which returns messages that have at least one [emoji
|
|
reaction](/help/emoji-reactions).
|
|
|
|
* 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 `pm-with` operator. The
|
|
`is:dm` filter replaced and deprecated the `is:private` filter. The
|
|
`dm-including` operator replaced and deprecated the `group-pm-with`
|
|
operator.
|
|
|
|
* The `dm-including` and `group-pm-with` operators return slightly
|
|
different results. For example, `dm-including:1234` returns all
|
|
direct messages (1-on-1 and group) that include the current user
|
|
and the user with the unique user ID of `1234`. On the other hand,
|
|
`group-pm-with:1234` returned only group direct messages that
|
|
included the current user and the user with the unique user ID of
|
|
`1234`.
|
|
|
|
* Both `dm` and `is:dm` are aliases of `pm-with` and `is:private`
|
|
respectively, and return the same exact results that the
|
|
deprecated filters did.
|
|
|
|
## Narrows that use IDs
|
|
|
|
### Message IDs
|
|
|
|
The `id` and `with` operators use message IDs for their operands. The
|
|
message ID operand for these two operators may be encoded as either a
|
|
number or a string.
|
|
|
|
* `id:12345`: Search for only the message with ID `12345`.
|
|
* `with:12345`: Search for the conversation that contains the message
|
|
with ID `12345`.
|
|
|
|
The `id` operator returns the message with the specified ID if it exists,
|
|
and if it can be accessed by the user.
|
|
|
|
The `with` operator is designed to be used for permanent links to topics,
|
|
which means they should continue to work when the topic is
|
|
[moved](/help/move-content-to-another-topic) or
|
|
[resolved](/help/resolve-a-topic). If the message with the specified ID
|
|
exists, and can be accessed by the user, then it will return messages
|
|
with the `channel`/`topic`/`dm` operators corresponding to the current
|
|
conversation containing that message, and replacing any such filters
|
|
included in the narrow.
|
|
|
|
The [help center](/help/search-for-messages#search-by-message-id) also
|
|
documents the `near` operator for searching for messages by ID, but
|
|
this narrow operator has no effect on filtering messages when sent to
|
|
the server. In practice, when the `near` operator is used to search for
|
|
messages, or is part of a URL fragment, the value of its operand should
|
|
instead be used for the value of the `anchor` parameter in endpoints
|
|
that also accept a `narrow` parameter; see
|
|
[GET /messages][anchor-get-messages] and
|
|
[POST /messages/flags/narrow][anchor-post-flags].
|
|
|
|
**Changes**: Prior to Zulip 8.0 (feature level 194), the message ID
|
|
operand for the `id` operator needed to be encoded as a string.
|
|
|
|
|
|
```json
|
|
[
|
|
{
|
|
"operator": "id",
|
|
"operand": 12345
|
|
}
|
|
]
|
|
```
|
|
|
|
### Channel and user IDs
|
|
|
|
There are a few additional narrow/search options (new in Zulip 2.1)
|
|
that use either channel IDs or user IDs that are not documented in the
|
|
help center because they are primarily useful to API clients:
|
|
|
|
* `channel:1234`: Search messages sent to the channel with ID `1234`.
|
|
* `sender:1234`: Search messages sent by user ID `1234`.
|
|
* `dm:1234`: Search the direct message conversation between
|
|
you and user ID `1234`.
|
|
* `dm:1234,5678`: Search the direct message conversation between
|
|
you, user ID `1234`, and user ID `5678`.
|
|
* `dm-including:1234`: Search all direct messages (1-on-1 and group)
|
|
that include you and user ID `1234`.
|
|
|
|
!!! tip ""
|
|
|
|
A user ID can be found by [viewing a user's profile][view-profile]
|
|
in the web or desktop apps. A channel ID can be found when [browsing
|
|
channels][browse-channels] in the web or desktop apps.
|
|
|
|
The operands for these search options must be encoded either as an
|
|
integer ID or a JSON list of integer IDs. For example, to query
|
|
messages sent by a user 1234 to a direct message thread with yourself,
|
|
user 1234, and user 5678, the correct JSON-encoded query is:
|
|
|
|
```json
|
|
[
|
|
{
|
|
"operator": "dm",
|
|
"operand": [1234, 5678]
|
|
},
|
|
{
|
|
"operator": "sender",
|
|
"operand": 1234
|
|
}
|
|
]
|
|
```
|
|
|
|
[view-profile]: /help/view-someones-profile
|
|
[browse-channels]: /help/introduction-to-channels#browse-and-subscribe-to-channels
|
|
[anchor-get-messages]: /api/get-messages#parameter-anchor
|
|
[anchor-post-flags]: /api/update-message-flags-for-narrow#parameter-anchor
|