Build a Searchable Catalog with Filters, Facets, and Semantic Search

A search box is easy. A searchable catalog that keeps being useful after the first query is the harder part.

That is the problem this demo takes on. It uses a small board-game catalog, but the shape of the problem is familiar: users type something half-remembered, misspell it, narrow by constraints, keep browsing, open a result, then want "more like this" without starting over. If your product has that flow, most of the work is not the UI polish. It is getting the search behavior right without turning the stack into a science project.

In this article, we build a searchable catalog with autocomplete, typo tolerance, filters, facets, deep pagination, semantic search, and similar-item recommendations.

You can try the hosted version first:

https://catalog.manticoresearch.com

The app itself is implemented in PHP, but that is not really the story here. The interesting part is how little ceremony you need to get from a basic query box to something that already feels like a working catalog: search, filters, facets, and similar-item discovery all show up quickly.

Run it locally

To run the same demo locally, you only need PHP 8.1+, Composer, and Docker (or any other way to run Manticore).

In this setup, Manticore is the search engine behind the catalog: it handles indexing, filtering, faceting, and semantic retrieval. The repo already includes a Docker setup for it, so the quickest way to get the demo running is to clone the repo and start Manticore from the project root:

git clone https://github.com/manticoresoftware/php-catalog-demo
cd php-catalog-demo
docker compose up -d

docker compose ps should show the container as running.

Inside the cloned repo, create the app environment file:

cp app/.env.example app/.env

For a local run, the important part is just how the app reaches Manticore:

MANTICORE_HOST=127.0.0.1
MANTICORE_PORT=9308

Install dependencies:

cd app
composer install

The demo reads those settings and creates a Manticore client:

$settings = require $root . '/config/settings.php';

$client = new Client([
    'host' => $settings['manticore']['host'],
    'port' => $settings['manticore']['port'],
    'transport' => 'Http',
]);

Then load the demo dataset:

php bin/bootstrap-demo.php

That command recreates the demo table and imports the starter catalog, so you begin from a known state instead of debugging old data.

Start the app:

php -S localhost:8081 -t public

Open http://localhost:8081/ and you have a working catalog to search.

Not glamorous. Still worth it. A lot of search demos lose people before the first query because setup sprawls. This one does not need much.

What makes the app feel usable

The part I care about most is not that the demo returns results. Plenty of demos do that. It is that the search flow holds together as users get more specific.

Start with autocomplete

People usually begin with fragments. Sometimes they remember the exact game title. Often they do not.

So the first layer is autocomplete:

$payload = [
    'body' => [
        'query' => $term,
        'table' => $this->tableName,
        'options' => ['limit' => $limit, 'force_bigrams' => 1],
    ],
];
$suggestions = $this->client->autocomplete($payload);

Using force_bigrams here helps tighten typo-tolerant matching for short or slightly wrong input, which is exactly where autocomplete can otherwise get mushy.

This is a small feature, but it changes the feel of the app immediately. Users stop guessing what your catalog calls things.

Make the first results page forgiving

Once the query is submitted, the first page needs to be useful even when the spelling is off by a bit.

$search = (new Search($this->client))
    ->setTable($this->tableName)
    ->limit($limit);

if ($query !== '') {
    $search->search($query);
    if ($fuzzy) {
        $search->option('fuzzy', 1)->option('force_bigrams', 1);
    }
} else {
    $search->search('*');
}

Fuzzy mode is doing plain practical work here: recovering close matches when users do not type the title exactly right.

If you want the lower-level details, see Spell correction and fuzzy search.

Let users narrow without rewriting

This is where many search interfaces get annoying. The query is close enough, but the result set is still too broad, so now the user has to reformulate it from scratch.

Better to let them narrow in place.

Range filters handle constraints like price, player count, play time, and release year. Facets expose the shape of the current result set so users can click into categories or tags instead of thinking up a more precise sentence.

$attributeFilters = [
    'price_min' => $priceMin,
    'price_max' => $priceMax,
    'play_time_min' => $playTimeMin,
    'play_time_max' => $playTimeMax,
    'player_count_min' => $playerCountMin,
    'player_count_max' => $playerCountMax,
    'release_year_min' => $yearMin,
    'release_year_max' => $yearMax,
];

if ($categoryIds !== []) {
    $search->filter('category_id', 'in', $categoryIds);
}
if ($tagIds !== []) {
    $search->filter('tag_id', 'in', $tagIds);
}
$this->applyNumericFilters($search, $attributeFilters);
$search->facet('category_id')->facet('tag_id');

That combination matters more than it may look on paper. In practice, this is where the catalog starts feeling easy to use: a broad query can shrink fast once you click into a category or tag, without losing the original search intent.

Keep deep pagination stable

If people browse further, offset pagination starts showing its age. Data changes between requests, offsets get larger, and eventually "show more" becomes less trustworthy than it should be.

This demo uses scroll tokens instead:

// Page 1 starts a fresh scroll session; next pages continue with returned token.
$effectiveScrollToken = $page > 1 ? $scrollToken : null;
$search->option('scroll', $effectiveScrollToken ?? true);

$resultSet = new ResultSet($this->client->search(['body' => $body], true));
$nextScroll = $resultSet->getScroll();
$hasMore = $nextScroll !== null && (string) $nextScroll !== '';

That gives the app a much better foundation for deep pagination: each request continues from a returned token rather than recomputing larger and larger offsets.

Operationally, this is one of those choices users never notice when it works and definitely notice when it does not. More on the mechanism here: Scroll-Based Pagination.

Add semantic retrieval where keywords fail

Keyword search gets you far. It does not solve everything.

Sometimes users describe something in roughly the right language, but not in the same words your catalog uses. That is where hybrid search earns its keep.

Use hybrid search on the results page

In this demo, one request includes both a lexical query block and a semantic knn block, then combines them with reciprocal rank fusion via options.fusion_method = rrf:

$body = [
    'query' => ['bool' => ['must' => [['query_string' => ['query' => $query]]]]],
    'knn' => [
        'field' => 'description_vector',
        'query' => $query,
    ],
    'options' => ['fusion_method' => 'rrf'],
    'limit' => $limit,
];

The vector field uses auto-embeddings, so the app does not have to generate query vectors on its own:

'description_vector' => [
    'type' => 'float_vector',
    'options' => [
        'MODEL_NAME' => 'sentence-transformers/all-MiniLM-L6-v2',
        'FROM' => 'description',
    ],
],

Because the knn block names the vector field directly ('field' => 'description_vector'), Manticore can embed the query text automatically for KNN search.

That keeps the application logic simpler than many teams expect when they first hear "semantic search." It also lets the results page stay in one flow instead of bolting a separate semantic experience onto the side.

Use similar-item discovery on the detail page

The same vector field does a different job on the item page: "show me similar games" without forcing the user to invent another query. This part uses KNN directly against the current item.

$search = new Search($this->client);
$search->setTable($this->tableName)
    ->knn('description_vector', $source->getId(), self::SIMILAR_KNN_LIMIT)
    ->notFilter('id', 'in', [$source->getId()])
    ->limit(self::SIMILAR_RESULT_LIMIT);

$resultSet = $search->get();
$hits = $this->formatResultSet($resultSet)['hits'];
return array_slice($hits, 0, self::SIMILAR_RESULT_LIMIT);

That is where search stops being a utility and starts helping discovery. On a real detail page, this is the part that makes it easy to keep exploring instead of bouncing back to the search box.

For reference: Auto Embeddings and KNN Search.

Keeping writes and search results in sync

A demo app is easy to trust when the data never changes. Real apps do not get that luxury.

Here, the table stays in sync through the same application flow users and admins already touch: bootstrap for a clean baseline, batched imports from the admin UI, and update/delete actions for individual items.

Prepared imports use the client's batch write methods:

$table = $this->client->table($this->indexConfig['name']);

if ($appendAsNewIds) {
    $table->addDocuments($batch);
} else {
    $table->replaceDocuments($batch);
}

For individual item changes, the app uses the table API directly:

if ($id > 0) {
    $this->table->replaceDocument($document, $id);
} else {
    $this->table->addDocument($document);
}

$this->table->deleteDocument($id);

And if you want to reset the experiment, the admin UI can drop imported records and return to the baseline dataset:

$baseMaxId = $this->resolveBaseMaxId();

$this->table->deleteDocuments([
    'range' => [
        'id' => ['gt' => $baseMaxId],
    ],
]);

No extra background machinery in the demo, no detached sync story to explain away. Just writes going where they need to go.

Why this matters

What this demo shows is not just that Manticore can return results. It shows you can assemble a searchable catalog that feels complete: users can start loosely, narrow quickly with filters and facets, recover from imperfect queries, open an item, and keep discovering from there without the whole stack getting complicated.

That is already enough to make search feel like part of the product, not a bolt-on feature.