newznab-tmux-NNTmux/docs/search-performance.md

# Search performance and index maintenance

The website, Newznab API, and API v2 share the release search contract in
`app/Services/Search/DTO`. Offset responses keep exact totals. API v2 also accepts an
empty `cursor` parameter to start cursor-mode pagination and returns the next opaque,
signed cursor in `pagination.next_cursor`.

## Baseline and validation

Capture warm- and cold-cache measurements for both `SEARCH_DRIVER=manticore` and
`SEARCH_DRIVER=elasticsearch`. Record p50/p95 response time, search backend duration,
SQL query count, peak memory, result count, offset, and whether fuzzy fallback ran.
Use the same query/category/sort matrix before and after a change. Include offsets 0,
1,000, and 5,000 plus API v2 cursor traversal.

Do not set a performance target until the baseline is recorded. A normal successful
exact search should make one search request; fuzzy search may make a second request
only after an exact zero-result response.

## Maintenance rebuild

Search schema changes require a maintenance window. Before rebuilding, enable
`nntmux.mysql_search_fallback` if bounded database fallback is desired while indexes
are empty.

1. Run `php artisan tmux:stop` and pause queue workers that update search indexes.
2. Recreate Manticore indexes with `php artisan manticore:create-indexes --drop`, or
   recreate Elasticsearch indexes with the project's Elasticsearch index command.
3. Repopulate enabled indexes with `php artisan nntmux:populate --manticore --all` or
   the equivalent Elasticsearch population flags.
4. Compare source and index document counts and run representative filtered searches.
5. Increment `SEARCH_INDEX_GENERATION` to invalidate outstanding API v2 cursors.
6. Restart queue workers and run `php artisan tmux:start`.

If count or query validation fails, leave processing stopped, restore/rebuild the
previous schema, and keep database fallback enabled until indexes are healthy.