Skip to content

Message Search

Search messages across channels using full-text search or specific field filters. Enable or disable search indexing per channel type in the Stream Dashboard.

Searching Messages

Search requires a channel filter and either a text query or message filter conditions.

// Search for messages containing text
var results = await Client.SearchMessagesAsync(new StreamSearchMessagesRequest
{
  // Channel filter is required - here, channels the local user is a member of
  ChannelFilter = new IFieldFilterRule[]
  {
    ChannelFilter.Members.In("john"),
  },
  Query = "supercalifragilisticexpialidocious",
  Limit = 10,
});

foreach (var hit in results.Results)
{
  Debug.Log(hit.Message.Id); // Stateful IStreamMessage
  Debug.Log(hit.Message.Text);
  Debug.Log(hit.Message.User);
  Debug.Log(hit.Channel.Cid); // Stateful IStreamChannel (auto-watched by default)
}

// Search with message filters - mutually exclusive with Query
var filtered = await Client.SearchMessagesAsync(new StreamSearchMessagesRequest
{
  ChannelFilter = new IFieldFilterRule[]
  {
    ChannelFilter.Members.In("john"),
  },
  MessageFilter = new IFieldFilterRule[]
  {
    MessageFilter.Text.Autocomplete("super"),
    MessageFilter.AttachmentType.In("image", "video"),
  },
  Limit = 10,
  // Set to false for one-off search bars where you don't want every result
  // channel to start receiving realtime updates.
  WatchResultChannels = true,
});

Query Parameters

Name Type Description Default Optional
filter_conditions object Channel filters. Maximum 500 channels are searched. See Querying Channels. -
message_filter_conditions object Message filters. See Message Filter Conditions below. Either this or query is required. -
query string Full-text search string. Equivalent to {text: {$q: <query>}}. Either this or message_filter_conditions is required. -
limit integer Number of messages to return. 100
offset integer Pagination offset. Cannot be used with sort or next. 0
sort object/array Sort order. Use field names with 1 (ascending) or -1 (descending). [{relevance: -1}, {id: 1}]
next string Pagination cursor. See Pagination below. -

Message Filter Conditions

For the full list of supported query operators, see Query Syntax Operators.

Field Description Operators
id Message ID $eq, $gt, $gte, $lt, $lte, $in
text Message text $q, $autocomplete, $eq, $gt, $gte, $lt, $lte, $in
type Message type. System and deleted messages are excluded $eq, $gt, $gte, $lt, $lte, $in
parent_id Parent message ID (for replies) $eq, $gt, $gte, $lt, $lte, $in
reply_count Number of replies $eq, $gt, $gte, $lt, $lte, $in
attachments Whether message has attachments $exists, $eq, $gt, $gte, $lt, $lte, $in
attachments.type Attachment type $eq, $in
mentioned_users.id Mentioned user ID $contains
user.id Sender user ID $eq, $gt, $gte, $lt, $lte, $in
created_at Creation timestamp $eq, $gt, $gte, $lt, $lte, $in
updated_at Update timestamp $eq, $gt, $gte, $lt, $lte, $in
pinned Whether message is pinned $eq
custom field Any custom field on the message $eq, $gt, $gte, $lt, $lte, $in

Sorting

Results are sorted by relevance by default, with message ID as a tiebreaker. If your query does not use $q or $autocomplete, all results are equally relevant.

Sort by any filterable field, including custom fields. Numeric custom fields are sorted numerically; string fields are sorted lexicographically.

Pagination

Two pagination methods are available:

Offset pagination allows access to up to 1,000 results. Results are sorted by relevance and message ID. You cannot use custom sorting with offset pagination.

Cursor pagination (using next/previous) allows access to all matching results with custom sorting. The response includes next and previous cursors to navigate between pages.

var channelFilters = new IFieldFilterRule[]
{
  ChannelFilter.Cid.EqualsTo("messaging:my-channel"),
};
var messageFilters = new IFieldFilterRule[]
{
  MessageFilter.Text.Autocomplete("supercali"),
};

// First page with custom sorting
var page1 = await Client.SearchMessagesAsync(new StreamSearchMessagesRequest
{
  ChannelFilter = channelFilters,
  MessageFilter = messageFilters,
  Sort = MessagesSort
    .OrderByDescending(MessageSortFieldName.Relevance)
    .ThenByAscending(MessageSortFieldName.UpdatedAt),
  Limit = 10,
});

// Next page using the cursor returned by the previous response
var page2 = await Client.SearchMessagesAsync(new StreamSearchMessagesRequest
{
  ChannelFilter = channelFilters,
  MessageFilter = messageFilters,
  Limit = 10,
  Next = page1.Next,
});

// Previous page
var page1Again = await Client.SearchMessagesAsync(new StreamSearchMessagesRequest
{
  ChannelFilter = channelFilters,
  MessageFilter = messageFilters,
  Limit = 10,
  Next = page2.Previous,
});