# 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](https://getstream.io/signin/?product=chat).

## Searching Messages

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

```java label="Java"
var searchResult = chat.search(SearchRequest.builder()
    .Payload(SearchPayload.builder()
        .filterConditions(Map.of("cid", "messaging:my-channel"))
        .messageFilterConditions(Map.of("text", Map.of("$autocomplete", "supercali")))
        .limit(10)
        .build())
    .build()).execute().getData();
```

### Query Parameters

| Name                      | Type         | Description                                                                                                             | Default                      | Optional |
| ------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------- | -------- |
| filter_conditions         | object       | Channel filters. Maximum 500 channels are searched. See [Querying Channels](https://getstream.io/chat/docs/java/query-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](https://getstream.io/docs/platform/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.

```java label="Java"
var searchResult = chat.search(SearchRequest.builder()
    .Payload(SearchPayload.builder()
        .filterConditions(Map.of("cid", "messaging:my-channel"))
        .messageFilterConditions(Map.of("text", Map.of("$autocomplete", "supercali")))
        .sort(List.of(
            SortParamRequest.builder().field("relevance").direction(-1).build(),
            SortParamRequest.builder().field("updated_at").direction(1).build()))
        .limit(2)
        .build())
    .build()).execute().getData();

// Next page
var nextResult = chat.search(SearchRequest.builder()
    .Payload(SearchPayload.builder()
        .filterConditions(Map.of("cid", "messaging:my-channel"))
        .messageFilterConditions(Map.of("text", Map.of("$autocomplete", "supercali")))
        .sort(List.of(
            SortParamRequest.builder().field("relevance").direction(-1).build(),
            SortParamRequest.builder().field("updated_at").direction(1).build()))
        .limit(2)
        .next(searchResult.getNext())
        .build())
    .build()).execute().getData();
```

---

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/java/search/](https://getstream.io/chat/docs/java/search/).