Understanding Search Architecture in Liferay
Liferay search feels instant and fuzzy in a way that databases are not, and that is because it does not use the database for search at all. It uses a dedicated search engine - historically Elasticsearch - fed by an indexing pipeline that turns portal content into searchable documents. Most search problems in Liferay come from misunderstanding that this is a second data store that must be kept in sync, not a live view of the database.
Two data stores, not one
The database is the system of record. The search index is a derived, denormalized copy optimized for querying text. Every searchable entity - a blog entry, a document, a custom object record - exists in both places. When they disagree, you get the classic symptom: a record is in the database but does not appear in search, or appears in search after it has been deleted. That is an index synchronization problem, not a data problem.
| Concern | Database | Search index |
|---|---|---|
| Role | System of record | Derived query-optimized copy |
| Query style | Exact, relational, joins | Full-text, ranked, fuzzy |
| Consistency | Immediate | Eventual, depends on indexing |
| Truth on conflict | Always wins | Must be rebuilt to match |
Indexers turn entities into documents
Each searchable entity type has an indexer. Its job is to convert a domain object into a search document - a flat bag of fields like title, content, tags, scope, and permissions. The indexer decides what is searchable and how. If a field is not added to the document by the indexer, no query will ever find content by that field, no matter what is in the database.
@Override
protected Document doGetDocument(BlogsEntry entry) {
Document document = getBaseModelDocument(
CLASS_NAME, entry);
document.addText(Field.TITLE, entry.getTitle());
document.addText(Field.CONTENT,
HtmlUtil.extractText(entry.getContent()));
document.addKeyword("status", entry.getStatus());
return document; // Only these fields become searchable.
}When indexing happens
Documents are written to the index in response to lifecycle events - create, update, delete - usually through the framework's indexing hooks. Reindexing can also be triggered manually for a full rebuild. The gap between a database change and the index reflecting it is why search is eventually consistent. Under load, or if indexing is disabled during a bulk import, that gap widens and results drift.
- Incremental indexing keeps the index current as individual records change.
- Full reindexing rebuilds an entity type from scratch - the fix for a drifted index.
- Bulk operations that bypass the service layer skip indexing entirely, which is a common cause of missing results.
Permissions are baked into search
Search does not return everything that matches - it returns what the current user is allowed to see. Permission information is indexed into the document and applied as a filter at query time, so results respect the same rules described in the permission framework. This is why the same query returns different result counts for different users, and why a permission change may require reindexing to take effect in search.
Queries are filtered, scored, and paged
A Liferay search query combines full-text matching with filters for scope, status, and permissions, then ranks results by relevance and returns a page of them. The pagination here is done by the search engine, not the database, which is why deep pagination in search has its own performance characteristics.
Debugging search problems
- Missing result: confirm the record exists in the database, then check whether it was indexed at all.
- Stale result: the index is out of sync - trigger a reindex for that entity type.
- Wrong result set per user: this is permissions in the index, not a query bug.
- Field not searchable: the indexer never added that field to the document.
Conclusion
Search in Liferay is a synchronized second data store, not a database query. Indexers define what is searchable, lifecycle events keep the index current, permissions are baked into every result, and queries are filtered and ranked by the engine. Once you accept that the index is derived and can drift, the fix for most search bugs becomes obvious: bring the index back into agreement with the system of record.