---
title: Search-Result Data Source
slug: experience/search-result-data-source
docTags: 
createdAt: 2026-05-12T13:50:01.235Z
---

## Overview

The `search-result` data source runs a full-text search against the Catalog API and returns matching content items. The search phrase is provided via the `phrase` config property, which is typically bound to a URL query parameter or context value set by the search Input component.

## When to use this

Use `search-result` on any view that displays the outcome of a user's search query. The `phrase` property drives what is searched — when it resolves to an empty value, the data source returns an empty list, which is the correct idle state.

## Basic Example

```json
{
  "type": "search-result",
  "contextKey": "results",
  "phrase": "$context.phrase",
  "batchSize": 20,
  "filter": {
    "publication": {
      "id": { "value": ":publicationId" }
    }
  }
}
```

`$context.phrase` is typically populated from the URL query param `?phrase=...` at runtime.                                          

## Configuration

### Type-specific properties

| Property                 | Type      | Default                       | Description                                                                                                                                 |
| ------------------------ | --------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| phrase                   | string    | —                             | **Required.** The search phrase. Supports `$context` interpolation — e.g. `"$context.phrase"` reads from the URL query param `?phrase=...`  |
| filter                   | object    | —                             | Scope the search to a subset of content                                                                                                     |
| sort                     | array     | —                             | Controls result ordering (default: relevance)                                                                                               |
| searchFields             | string\[] | `['CONTENT', 'CONTENT_NAME']` | Fields to search in                                                                                                                         |
| searchOptions            | object    | —                             | Additional search API options                                                                                                               |
| limitCharactersBeforeHit | number    | —                             | Trim excerpt to at most N characters before the first highlighted hit                                                                       |
| groupBy                  | object    | —                             | **Deprecated.**<br /> Group results by a custom content property — requires <br />legacyMode.unwrapBundles<br /> which is itself deprecated |

For common properties (`contextKey`, `limit`, `batchSize`, etc.) see [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)

### Filter properties

Uses the same filter shape as the `content` data source (`StorefrontContentFilter`).

| Filter key  | Type                  | Description                                                       |
| ----------- | --------------------- | ----------------------------------------------------------------- |
| publication | PublicationFilter     | Restrict results to a specific publication — use `publication.id` |
| contentType | `{ value, negated? }` | Limit results to a content type: `post`, `issue`, `bundle`        |
| taxonomies  | TaxonomyListFilter    | Restrict results to specific taxonomy nodes                       |
| properties  | MapFilter             | Filter by custom content properties                               |

Supports `AND`, `OR`, and `condition` — see da.

### Sort properties

| Sort key        | Type            | Description                       |
| --------------- | --------------- | --------------------------------- |
| relevance       | `{ direction }` | Sort by relevance score (default) |
| publicationDate | `{ direction }` | Sort by publication date          |

`direction` accepts `ASC` or `DESC`.

## Advanced Features

### Showing results only when a query exists

Wrap the result list in a condition:

```json
{
  "condition": {
    "value": "$context.phrase",
    "operation": "SET"
  }
}
```

### Trimming excerpts

Use `limitCharactersBeforeHit` to prevent very long excerpts with the search hit far from the start:

```json
{
  "type": "search-result",
  "phrase": "$context.phrase",
  "limitCharactersBeforeHit": 100
}
```

## Testing Notes / Edge Cases

- **Empty&#x20;**`phrase`**&#x20;= no results**: When `phrase` resolves to an empty string or undefined, the data source returns zero items. Always pair with a "no results" empty state.
- `preventSSRCache`: Search results are user-driven — set `preventSSRCache: true` on server-rendered search pages.
- **Short queries**: Very short phrases (1–2 characters) may return unexpected results depending on API configuration.

## Related Topics

- [Content Data Source](docId\:dfdY32ZAnYtMHKUhzXOrb)
- [Data Sources Overview](docId\:fuMBUaBWeON_OTO5wfevf)