Search

LAST EDIT Sep 16 2021

Message search is built-in to the chat API. You can enable and/or disable the search indexing on a per channel type through the Stream Dashboard.

The command shown below selects the channels in which John is a member. Next, it searches the messages in those channels for the keyword “'supercalifragilisticexpialidocious'”.

After sending a message, it may take several minutes for the message to be returned in search results.

Query Parameters

Copied!
nametypedescriptiondefaultoptional
filter_conditionsobjectFilter conditions for channels. We will only ever search a maximum of 500 channels at a time, so it is beneficial to make these filters as strict as possible. See the Query Channels section for information about these filters.-
message_filter_conditionsobjectFilter conditions for messages. See the next section for details. You must either specify query or message_filter_conditions.-
querystringA string to search for. This is equivalent passing {text: {$q: <query>}} to message_filter_conditions. You must either specify query or message_filter_conditions.-
limitintegerThe number of messages to return.100
offsetintegerThe pagination offset. See the Pagination section for more information. You cannot use a non-zero offset with the sort or the next parameters.0
sortobject or array of objectsThe sorting used for the messages matching the filters. Sorting is based on field and direction, and multiple sorting options can be provided. Direction can be ascending (1) or descending (-1).[{relevance: -1}, {id: 1}]
nextstringA key used to paginate. See the Pagination section for more information.-

Message Filter Conditions

Copied!

You can use following operators and fields in order to search messages:

Field

Description

Allowed operators

id

message ID

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

text

text of the message

$q. $autocomplete, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

type

type of the message

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

parent_id

the parent message ID (if the message is a reply)

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

reply_count

number of replies the message has

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

attachments

whether or not the message contains an attachment

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

attachments.type

the type of the attachment

$eq, $in

mentioned_users.id

user ID that is included in the message's mentions

$contains

user.id

user ID of the user that sent the message

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

created_at

created at time

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

updated_at

updated at time

$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin

pinned

whether the message has been pinned

$eq

<custom field>

any custom field that is attached to your message

$eq, $gt, $gte, $lt, $lte, $in

Stream Chat does not run MongoDB on the backend, only a subset of the query options are available.

Sorting

Copied!

Messages default to being sorted by relevance to your query, with the message ID as a tie-breaker for any equally relevant results. If your query does not use the $q or $autocomplete operators then all results are considered equally relevant.

You can sort by any of the filter-able fields, including custom fields. Custom fields that are numbers will be sorted numerically, while custom string fields will be sorted lexicographically. See the Pagination section for examples of sorting.

Pagination

Copied!

There are two ways to paginate through search results:

  1. Using limit and offset

  2. Using limit and next/previous values

Limit and offset will allow you to access up to 1000 results matching your query. You will not be able to sort using limit and offset. The results will instead be sorted by relevance and message ID. See the code at the top of the page for examples of limit and offset pagination.

Next pagination will allow you to access all search results that match your query, and you will be able to sort using any filter-able fields and custom fields.

Pages of sort results will be returned with next and previous strings, which tell the API where to start searching from and what sort order to use. You can supply those values as a next parameter when making a query to get a new page of results.