Smart Search in Joomla

1. The Basics

1.1 What is Smart Search?

Smart Search is Joomla's modern site-search engine. The component is called com_finder, which is why developers often call it Finder.

Smart Search:

• Has shipped with Joomla core since Joomla 2.5.
• Builds a search index in the database.
• Queries that index instead of scanning content tables.
• Returns ranked, filterable results.
• Replaces the legacy com_search, which was removed in Joomla 5.

Old Search ran a live LIKE '%keyword%' query against #__content. Smart Search builds a real search index that is updated on save.

1.2 Two Search Systems - Know the Difference

If you still hear someone talk about "the Search module" in Joomla, they almost certainly mean Smart Search. The two systems are very different:

1.3 Joomla Version Timeline

Smart Search has been part of Joomla for over a decade. The status of search through the Joomla versions:

1.4 Where Do I Find Smart Search?

In the Joomla 6 backend, Smart Search lives in several places:

Components → Smart Search                (manage indexed items + filters)
Components → Smart Search → Maps         (taxonomy branches & nodes)
Components → Smart Search → Filters      (saved filter sets)
System     → Manage → Plugins            (Smart Search content plugins)
System     → Manage → Modules            (the search box module)

The frontend search page lives at /index.php?option=com_finder, usually exposed through a menu item of type Smart Search → Search.

1.5 The Four Building Blocks

Smart Search has four parts. Understand these four and the rest is configuration.

1.6 The Five Pieces in a Working Setup

A complete Smart Search installation uses five different pieces. Each one is independently enable-able:

3. Inside the Index

3.1 The Smart Search Tables

Smart Search stores its data in a small set of dedicated tables:

#__finder_links             one row per indexed item (article, contact, ...)
#__finder_links_terms       link ↔ term, with weight and context
#__finder_terms             every distinct term in the index
#__finder_terms_common      stop-words ("the", "and", ...) per language
#__finder_tokens            MEMORY engine - scratch tokens during indexing
#__finder_tokens_aggregate  MEMORY engine - aggregated tokens during indexing
#__finder_taxonomy          taxonomy branches (Type, Category, Language, ...)
#__finder_taxonomy_map      link ↔ taxonomy node
#__finder_types             registry of indexed content types
#__finder_filters           saved filter sets bound to modules or menu items
#__finder_logging           search-term log (popular queries)

There are two logical layers:

• Links - what is indexed.
• Terms - the searchable vocabulary, mapped back to links with weights.

The #__finder_tokens and #__finder_tokens_aggregate tables use MySQL's MEMORY storage engine. They live in RAM and are wiped between indexer runs. If indexing a huge site hits max_heap_table_size, raise the MySQL setting - do not switch the engine.

3.2 The Taxonomy Tree

Smart Search auto-builds a taxonomy of every indexed item. These taxonomy branches are what the visitor sees as filter checkboxes on the results page:

Branch          Examples
─────────────   ────────────────────────
Type            Article, Category, Contact, News Feed, Tag
Category        Site categories (hierarchical)
Language        nl-NL, en-GB, *
Author          User who created the item
Tag             Tags on the item

3.3 Weighted Fields

When Smart Search indexes an article, it assigns different weights to each field. A term in the title scores more than the same term in the body. This is why a title-only match beats a body-only match in the result list.

3.4 Language and Stemming

Each indexed term is tagged with a language. At query time:

• The active site language picks the stemmer.
• "running" reduces to stem run and matches "run", "runs", and "running".
• The stemmer is per language - Dutch, English, French, German, and others all have their own rules.

Set the article's language correctly. A Dutch article indexed inside an English index gets the wrong stemmer and weak relevance.

5. Maintenance

5.1 Keeping the Index Fresh

You should use two strategies together:

1. On-save indexing: plg_content_finder re-indexes a single item on save or publish.
2. Scheduled rebuild: a cron task periodically purges and re-indexes everything.

Joomla 4 and newer ships a Smart Search Indexer scheduled task. You can run it from the Scheduled Tasks component or directly via cron:

# Run every night at 03:30
30 3 * * *  cd /var/www/site && php cli/joomla.php finder:index

5.2 Statistics

Go to Components → Smart Search → Statistics. The page shows:

• Total indexed items per type.
• Index size.
• Number of terms.
• Recent search log (if logging is enabled).

A growing index with a shrinking term count is usually a sign of duplicates or trashed items still indexed. Purge and re-index.

5.3 Search Logging - What Visitors Actually Search For

In the Smart Search component options, set Gather Search Statistics to Yes. Joomla logs every query to #__finder_logging. View the top queries at Components → Smart Search → Search Terms.

This data is gold for SEO and content strategy:

• High-volume queries with zero results point to a content gap.
• High-volume queries with abandoned clicks point to poor result ranking.

Treat the search log as a backlog. Every popular zero-result query is a piece of content you should write.

5.4 Optimising the Index

Go to Components → Smart Search → Maintenance → Optimise. This:

• Defragments the terms tables.
• Removes orphaned tokens.
• Rebuilds the common-words list.

Run Optimise after a big bulk import or a heavy content prune.

5.5 Synonyms

In Components → Smart Search → Options → Search Tab you can register synonym pairs so a query for one term also matches the other.

joomla,joomla!
nl,netherlands,holland
cms,content management system
event,evenement

How it works:

• One synonym group per line, comma-separated.
• At query time, each token is expanded to its synonym group before lookup.
• Synonyms are stored in the component params, not in a dedicated table.

Good uses include brand variants (Joomla / Joomla!), abbreviations (CMS / content management system), and cross-language hints on a single-language site (event / evenement).

Synonyms apply at query time, not at index time. Add them whenever you like - no re-index needed.

5.6 Stop-words and Common Terms

In Components → Smart Search → Options → Indexing Tab:

• Common-word threshold: a term used in more than X percent of items is auto-flagged as common and effectively ignored.
• Stop-words file: a per-language list shipped by each language plugin.

You rarely need to edit stop-words by hand. The auto-threshold does the right thing on most sites.

5.7 Popular Searches Module

The Smart Search Module - Most Popular Searches renders the top N queries from #__finder_logging as clickable suggestions. It is only available when Gather Search Statistics is enabled. Place it on the homepage and visitors can click a popular search instead of typing.

7. Access Control and Privacy

7.1 Access Levels

Each indexed link stores the item's Access level. At query time, Smart Search:

1. Resolves the current user's access levels.
2. Filters out links the user cannot see.
3. Filters out taxonomy filters that would only yield results the user cannot access.

So a Guest never sees Registered-only articles in search results. The same rules apply everywhere in Joomla.

7.2 Unpublished, Archived, Trashed

Smart Search respects the publishing state at index time and the query engine re-checks at search time:

7.3 Privacy of the Search Log

If you enable search logging, you store visitor queries. Treat the log as personal data:

• Anonymise IPs at the webserver level.
• Document retention in your privacy policy.
• Disable logging on highly sensitive sites.

9. Common Mistakes and Pitfalls

9.1 Search Returns No Results

• Did you build the index? Go to Components → Smart Search → Index.
• Are the content plugins enabled (plg_finder_content and friends)?
• Is the item published, with publish_up in the past?
• Is the language correct? A Dutch query against an English-only index returns nothing.

9.2 Search is Slow

Smart Search should be fast. If it is not:

• Run Optimise.
• Check the #__finder_links row count. An extreme size means stale entries - purge and re-index.
• Disable content-type plugins you do not use.
• Look at MySQL tuning, especially innodb_buffer_pool_size.

9.3 Stale Results After Edits

This usually means plg_content_finder is disabled, or an article save is going through a custom path that skips the event.

• Enable the Content - Smart Search plugin.
• After bulk imports, run php cli/joomla.php finder:index.

9.4 Confusing Legacy Search with Smart Search

• com_search is the legacy component, removed in Joomla 5.
• com_finder is Smart Search, the only core search in Joomla 6.

If a tutorial mentions "the Search component", check the date before you follow it.

9.5 Custom Fields and Smart Search

This is a common source of outdated advice. Since Joomla 4.2, Smart Search does index Custom Field values out of the box. No extra extension is needed. Joomla 6 inherits this behaviour.

What gets indexed automatically:

• Values of fields whose type produces searchable text: Text, Textarea, Editor, List, Radio, Checkboxes, URL, Calendar, and so on.
• Per article, contact, category, or user - wherever Custom Fields apply.
• The field's Access level is respected at query time.

What does not get indexed automatically:

• Fields with Searchable = No on the field's Options tab. Opt-out is per field.
• Binary or non-text types: Media file paths, Color, and raw Subform JSON without a render.
• Custom field types from third-party plugins that do not implement the indexer hook.

Gotchas:

• After enabling Custom Fields on existing content, run Purge + re-index so the values land in #__finder_links_terms.
• A Subform value is stored as JSON in the database. Only the rendered output is indexed - override subform.php if you need a different shape.
• Pre-4.2 sites that migrated up may still have the old workaround installed, such as Tassos Finder or PHProberto Finder Plus. Check whether you still need it.

9.6 SQL Field Gotcha

SQL Custom Fields that query private content can leak data into the search index. The indexer runs as a privileged user, so whatever the SQL returns ends up searchable.

Audit every SQL Custom Field before you rely on Smart Search across multi-tenant data.

9.7 The Index Never Finishes

Symptoms: the indexer page times out, the progress bar stalls.

• Increase max_execution_time and memory_limit for the indexer run.
• Index from the CLI - there is no PHP timeout there.
• Batch by content type: disable all but one plugin, index, repeat.

9.8 Large-site Tuning Knobs

For sites with tens of thousands of items, the defaults are too aggressive. Tune these:

11. Best Practices and Quick Reference

If you only remember a few things from this article, remember these:

• Enable only the content-type plugins you actually use - the index stays leaner.
• Run a full re-index after migrations, content cleanups, or plugin changes.
• Schedule a nightly CLI re-index for large sites.
• Enable search logging - it is your most honest content gap report.
• Set the article language correctly so the right stemmer is used.
• Use saved filters to scope search per section or per language.
• Override default_result.php in your template instead of editing core.
• Audit SQL Custom Fields before relying on Smart Search.

Cheat Sheet

COMPONENT          Components → Smart Search
PLUGINS            System → Plugins → "finder"
INDEX              Components → Smart Search → Index
PURGE              Components → Smart Search → Maintenance → Purge
OPTIMISE           Components → Smart Search → Maintenance → Optimise
LOGS               Components → Smart Search → Search Terms
MODULE             Modules → Smart Search Module → New
RESULTS PAGE       Menus → New → Smart Search → Search
SAVED FILTER       Components → Smart Search → Filters
CLI INDEX          php cli/joomla.php finder:index
TABLES             #__finder_links / _terms / _taxonomy / _logging
QUERY SYNTAX       "phrase"  -exclude  word*
OVERRIDE           templates/{tpl}/html/com_finder/search/default_result.php
API                GET /api/index.php/v1/fields/com_finder/search?filter[q]=...
LEGACY             com_search is REMOVED - Smart Search is the search.