4.7 KiB
Search replaces the native Flarum search functionality which relies on MySQL badly performing fulltext search with one that is completely relying on the proven elasticsearch engine.
Features
- Sync discussions and posts to Elasticsearch using your queue, unobtrusively for the user.
- Reduces search loading times to well below 400ms (local tests with 50,000 discussions: 260ms)
- Uses Flarum's group permissions and tags system.
- Compatible with Friends of Flarum Byōbu.
Requirements
- Elasticsearch 7.x or OpenSearch 1.x+
- A non-sync queue driver with a running worker (
php flarum queue:work) is strongly recommended for production. The extension works with the default sync driver, but index jobs run inline which adds latency to user-facing changes like posting.
Installation
composer require blomstra/search:*
Enable the extension in the admin area and configure the Elasticsearch endpoint and index name in the extension settings.
Setting up the index
First install
Run the build command once. It creates a timestamped concrete index, immediately aliases your configured index name to it, and begins queuing documents. Search is available and improves as the queue processes:
php flarum blomstra:search:index build
php flarum queue:work
Subsequent rebuilds (zero-downtime)
When you need to rebuild the full index (e.g. after a mapping change):
# 1. Build into a staging index — live index is untouched
php flarum blomstra:search:index build
# 2. Drain the queue
php flarum queue:work --stop-when-empty
# 3a. Promote the new index to live
php flarum blomstra:search:index promote
# 3b: promote but keep the old index as a backup for rollback
php flarum blomstra:search:index promote --keep-backup
# 4. Add content added between 'build' and 'promote'
php flarum blomstra:search:index fill
If you kept the backup and want to roll back:
php flarum blomstra:search:index rollback
Once you are satisfied with the new index, drop the backup:
php flarum blomstra:search:index discard --backup
Resuming or cancelling an interrupted build
If a build is interrupted, re-run it with the appropriate flag:
# Resume each seeder from where it left off
php flarum blomstra:search:index build --resume
# Drop the staging index and start completely fresh
php flarum blomstra:search:index build --fresh
# Cancel the build without starting a new one
php flarum blomstra:search:index discard --pending
Filling gaps in an existing index
If documents are missing from the live index (e.g. due to queue failures):
php flarum blomstra:search:index fill
Updating the mapping only
To push a mapping change to the live index without rebuilding:
php flarum blomstra:search:index mapping
Command reference
| Command | Description |
|---|---|
build |
Build into a new timestamped staging index. On first install, aliases it immediately so search is live during seeding. On subsequent runs, use promote when the queue is drained. |
build --resume |
Resume an interrupted build from where each seeder left off. |
build --fresh |
Drop the staging index and start completely fresh. |
promote |
Atomically swap the alias from the live index to the completed staging index. Prompts for confirmation. |
promote --keep-backup |
Promote and retain the replaced live index as a backup for rollback. |
rollback |
Restore the backup index to live (after promote --keep-backup). Deletes the index that was live. |
discard --pending |
Drop the staging index without promoting (cancels an in-progress build). |
discard --backup |
Drop the backup index (cleanup after promote --keep-backup). |
mapping |
Push updated mapping to the live index without rebuilding or reseeding. |
fill |
Seed only documents missing from the live index. |
build --only=discussions |
Seed only the specified document type (discussions or posts). |
build --throttle=N |
Wait N seconds between batches (reduces queue pressure). |
build --max-id=N |
Limit seeding to documents with ID ≤ N. |
promote --i-am-sure |
Skip the promotion confirmation prompt (for scripts and CI). |
FAQ
Queue configuration
"Can I dispatch indexing jobs to a specific queue?"
Yes:
\Blomstra\Search\Jobs\Job::$onQueue = 'search';
"I have a different question"
Reach out ot us via https://support.on-floxum.com/t/ext-search . If you have an active subscription, please mention what plan you are on.
- Floxum provides managed Flarum hosting.
- https://floxum.com
- https://support.on-floxum.com/t/ext-search