Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api-docs: Update 'construct-narrow' article. 

Fixes small error in the example at the top of the article, and
adds a short statement about narrows searching the current user's
personal message history with a link to the help center article.

Gives the final section a subheader and adds the two other narrow
operators that take an ID.
This commit is contained in:
Lauryn Menard 2022-10-28 19:42:37 +02:00 committed by Tim Abbott
parent 81f3307da0
commit c4d407e992
1 changed files with 29 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
templates/zerver/api/construct-narrow.md
View File

@ -2,14 +2,14 @@
A **narrow** is a set of filters for Zulip messages, that can be based A **narrow** is a set of filters for Zulip messages, that can be based
on many different factors (like sender, stream, topic, search on many different factors (like sender, stream, topic, search
keywords, etc.). Narrows are used in various places in the the Zulip keywords, etc.). Narrows are used in various places in the the Zulip
API (most importantly, in the API for fetching messages). API (most importantly, in the API for fetching messages).
It is simplest to explain the algorithm for encoding a search as a It is simplest to explain the algorithm for encoding a search as a
narrow using a single example. Consider the following search query 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 (written as it would be entered in the Zulip web app's search box).
filters for messages sent on stream `announce`, not sent by It filters for messages sent to stream `announce`, not sent by
`iago@zulip.com`, and containing the phrase `cool sunglasses`: `iago@zulip.com`, and containing the words `cool` and `sunglasses`:
``` ```
stream:announce -sender:iago@zulip.com cool sunglasses stream:announce -sender:iago@zulip.com cool sunglasses
@ -36,25 +36,38 @@ as a list of simple objects, as follows:
] ]
``` ```
The full set of search/narrowing options supported by the Zulip API is The Zulip help center article on [searching for messages](/help/search-for-messages)
documented in [the Zulip Help Center article on documents the majority of the search/narrow options supported by the
search](/help/search-for-messages). There are a few additional Zulip API.
options, new in Zulip 2.1, that we don't document there because they
are primarily useful to API clients: Note that many narrows, including all that lack a `stream` or `streams`
operator, search the current user's personal message history. See
[searching shared history](/help/search-for-messages#searching-shared-history)
for details.
## Narrows that use IDs
The `near` and `id` operators, documented in the help center, use message
IDs for their operands.
* `near:12345`: Search messages around the message with ID `12345`.
* `id:12345`: Search for only message with ID `12345`.
There are a few additional narrow/search options (new in Zulip 2.1)
that use either stream IDs or user IDs that are not documented in the
help center because they are primarily useful to API clients:
* `sender:1234`: Search messages sent by user ID `1234`.
* `stream:1234`: Search messages sent to the stream with ID `1234`. * `stream:1234`: Search messages sent to the stream with ID `1234`.
* `sender:1234`: Search messages sent by user ID `1234`.
* `pm-with:1234`: Search the private message conversation between * `pm-with:1234`: Search the private message conversation between
you and user ID `1234`. you and user ID `1234`.
* `pm-with:1234,5678`: Search the private message conversation between * `pm-with:1234,5678`: Search the private message conversation between
you, user ID `1234`, and user ID `5678`. you, user ID `1234`, and user ID `5678`.
* `group-pm-with:1234`: Search all (group) private messages that * `group-pm-with:1234`: Search all group private messages that
include user ID `1234`. include you and user ID `1234`.
* `pm-with:1234,5678`: Search all (group) private messages that
include user ID `1234` and user ID `5678`.
The operands for these search options must be encoded either as an 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 integer ID or a JSON list of integer IDs. For example, to query
messages sent by a user 1234 to a PM thread with yourself, user 1234, messages sent by a user 1234 to a PM thread with yourself, user 1234,
and user 5678, the correct JSON-encoded query is: and user 5678, the correct JSON-encoded query is: