Apache Solr + TYPO3: Enterprise Search with Facets, Autocomplete, and Vector Search

The built-in TYPO3 search scans page titles and content – sufficient for small projects, but a bottleneck for enterprise requirements. When you need to make thousands of pages, structured records, and files searchable, you require a dedicated search infrastructure. Apache Solr provides exactly that – and the EXT:solr extension integrates this capability seamlessly into TYPO3.

This article demonstrates how EXT:solr works, what is possible since Solr 9.8 with the language-models module (embedding/vector pipeline, e.g. knn_text_to_vector), and how to implement enterprise search in your project.

Table of Contents  

What EXT:solr Achieves  

EXT:solr connects TYPO3 to an Apache Solr server and provides a complete enterprise search infrastructure:

Architecture Overview  

The system consists of four cooperating components:

How the document lifecycle works:

1. Editors create or edit content in TYPO3.
2. The monitoring detects changes via PSR-14 events and writes an entry to the Index Queue.
3. A scheduler task processes the queue and sends documents as JSON to the Solr server.
4. The search plugin in the frontend sends queries to Solr and renders results via Fluid templates.

Component Overview  

Version Compatibility  

composer require apache-solr-for-typo3/solr:dev-main

Setup in under 10 minutes  

Installation via Composer  

composer require apache-solr-for-typo3/solr

Local Development with DDEV  

The fastest way to a local Solr instance is the official DDEV add-on :

ddev add-on get ddev/ddev-typo3-solr
ddev restart

Configure cores in .ddev/typo3-solr/config.yaml:

config: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/solr.xml'
typo3lib: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/typo3lib'
configsets:
  - name: 'ext_solr_13_1_0'
    path: 'vendor/apache-solr-for-typo3/solr/Resources/Private/Solr/configsets/ext_solr_13_1_0'
cores:
  - name: 'core_de'
    schema: 'german/schema.xml'
  - name: 'core_en'
    schema: 'english/schema.xml'

And configure .ddev/config.yaml to create the cores after starting:

hooks:
  post-start:
    - exec-host: ddev solrctl apply

Docker Production  

For production, the official Docker image provides pre-configured cores for all languages:

services:
  solr:
    image: typo3solr/ext-solr:13.1
    ports:
      - "8983:8983"
    volumes:
      - solr-data:/var/solr
    restart: unless-stopped

volumes:
  solr-data:
    driver: local

Managed Hosting  

Two options for anyone who prefers not to operate their own Solr server:

TYPO3 Site Configuration  

Add the connection in config/sites/<identifier>/config.yaml:

solr_enabled_read: true
solr_host_read: solr
solr_port_read: '8983'
solr_scheme_read: http
solr_path_read: /
solr_core_read: core_de

Index Queue: The Core Component  

The Index Queue is the central mechanism through which TYPO3 content reaches Solr.

Indexing Pages  

Pages are indexed out of the box – no additional configuration is required. The page indexer renders the page and sends the content to Solr.

Indexing Custom Records  

Any TYPO3 table can be added to the index via TypoScript. Here is an example for EXT:news:

plugin.tx_solr.index.queue {
    news = 1
    news {
        type = tx_news_domain_model_news

        fields {
            title = title
            abstract = teaser
            author = author

            content = SOLR_CONTENT
            content {
                cObject = COA
                cObject {
                    10 = TEXT
                    10.field = bodytext
                }
            }

            category_stringM = SOLR_RELATION
            category_stringM {
                localField = categories
                multiValue = 1
            }

            url = TEXT
            url {
                typolink.parameter = {$plugin.tx_news.settings.detailPid}
                typolink.additionalParams = &tx_news_pi1[controller]=News&tx_news_pi1[action]=detail&tx_news_pi1[news]={field:uid}
                typolink.additionalParams.insertData = 1
                typolink.returnLast = url
            }
        }
    }
}

The three content objects at a glance:

Dynamic Fields  

EXT:solr uses dynamic field suffixes to add custom fields without requiring a schema change :

Monitoring  

EXT:solr detects record changes via PSR-14 events. Two modes are available:

• Immediate (Default): Changes are processed directly during the DataHandler operation.
• Delayed: Changes are collected in the event queue (tx_solr_eventqueue_item) and processed by a separate scheduler task.

Configuration is done via Extension Settings → monitoringType.

Site Hash Strategy  

Under Admin Tools → Settings → Extension Configuration → solr, siteHashStrategy controls how the site hash is formed in Solr documents. For new TYPO3 13.4+ projects, siteHashStrategy = 1 (Site Identifier) is recommended; in older defaults, the domain-based variant (0, deprecated) may still be active. Changing the strategy requires a complete reindexing.

Configuring the Search  

Basic Configuration  

plugin.tx_solr {
    enabled = 1
    search {
        targetPage = 42
        initializeWithEmptyQuery = 1
        showResultsOfInitialEmptyQuery = 0
        trustedFields = url
    }
}

Faceted Navigation  

Facets transform the search into an interactive filtering experience :

plugin.tx_solr.search {
    faceting = 1
    faceting {
        facets {
            contentType {
                label = Inhaltstyp
                field = type
            }
            category {
                label = Kategorie
                field = category_stringM
            }
            year {
                label = Jahr
                field = year_intS
                type = queryGroup
                queryGroup {
                    2026.query = [2026-01-01T00:00:00Z TO 2026-12-31T23:59:59Z]
                    2025.query = [2025-01-01T00:00:00Z TO 2025-12-31T23:59:59Z]
                }
            }
        }
    }
}

Available facet types: options (Default), queryGroup, hierarchy, dateRange, numericRange.

Autocomplete / Suggest  

plugin.tx_solr {
    suggest = 1
    suggest {
        numberOfSuggestions = 10
        suggestField = spell
        showTopResults = 1
        numberOfTopResults = 5
    }
}

Highlighting & Spellchecking  

plugin.tx_solr.search {
    results {
        resultsHighlighting = 1
        resultsHighlighting {
            fragmentSize = 200
            wrap = <mark>|</mark>
        }
    }
    spellchecking = 1
    sorting = 1
}

Vector and Hybrid Search with Solr 9.8+  

Since Apache Solr 9.8 (January 2025), Solr includes the Solr language-models module (Text-to-Vector, embedding pipeline; often referred to as the 'LLM module' in older texts) , which enables semantic search on the Solr server – without a separate vector database, without additional middleware. Classes and configurations follow the org.apache.solr.languagemodels.* / solr.languagemodels.* packages (depending on the Solr version, please check the Reference Guide).

The LLM Module (Solr: 'language-models' / Text-to-Vector)  

The pipeline solves the vocabulary mismatch problem of classic keyword search: Users formulate their questions differently than the content does. Texts and search queries are converted into vectors that map semantic similarity.

Supported embedding providers (via LangChain4j ):

Hybrid Search: BM25 + Vector  

The most powerful configuration combines classic BM25 ranking with vector re-ranking:

?q=Kundenbeschwerden Bearbeitung
&rq={!rerank reRankQuery=$rqq reRankDocs=50 reRankWeight=2}
&rqq={!knn_text_to_vector model=openai-embed f=vector topK=50}Kundenbeschwerden Bearbeitung

This way, you benefit from exact keyword matches and semantic similarity.

Use Cases  

Troubleshooting in 6 Steps  

If the search is not working, the problem lies in one of four areas: Connection, Indexing, Solr Core, or Frontend. Proceed systematically.

Diagnosis Flowchart  

Common Errors and Solutions  

Activating Logging  

For deeper diagnosis, activate TypoScript logging (only dev/staging):

plugin.tx_solr.logging {
    debugOutput = 1
    exceptions = 1
    indexing = 1
    query.rawGet = 1
    query.queryString = 1
}

And configure the log file in config/system/additional.php:

$GLOBALS['TYPO3_CONF_VARS']['LOG']['ApacheSolrForTypo3']['Solr']['writerConfiguration'] = [
    \Psr\Log\LogLevel::DEBUG => [
        \TYPO3\CMS\Core\Log\Writer\FileWriter::class => [
            'logFile' => \TYPO3\CMS\Core\Core\Environment::getVarPath() . '/log/solr.log',
        ],
    ],
];

ddev exec tail -f var/log/solr.log

PSR-14 Events for Custom Extensions  

EXT:solr triggers PSR-14 events at central points , which you can use for your own logic.

Adding Custom Fields to Documents  

<?php

declare(strict_types=1);

namespace MyVendor\MyExt\EventListener;

use ApacheSolrForTypo3\Solr\Event\Indexing\BeforeDocumentsAreIndexedEvent;
use TYPO3\CMS\Core\Attribute\AsEventListener;

#[AsEventListener(identifier: 'my-ext/enrich-solr-documents')]
final class EnrichSolrDocuments
{
    public function __invoke(BeforeDocumentsAreIndexedEvent $event): void
    {
        foreach ($event->getDocuments() as $document) {
            $document->addField(
                'custom_score_floatS',
                $this->calculateScore($document)
            );
        }
    }

    private function calculateScore(
        \ApacheSolrForTypo3\Solr\System\Solr\Document\Document $document
    ): float {
        return match ($document->getField('type')['value'] ?? '') {
            'pages' => 1.0,
            'tx_news_domain_model_news' => 0.8,
            default => 0.5,
        };
    }
}

Important Events at a Glance  

TYPO3 v14: Changes for Developers  

If you are upgrading EXT:solr to TYPO3 v14 / Fluid 5.0, the following points, among others, are relevant according to SKILL and upstream:

• Fluid 5.0: Search templates and facet partials require strictly typed ViewHelper arguments, no underscore-prefixed template variables – check your custom overrides.
• TypoScriptFrontendController: Custom indexers or plugins that use $GLOBALS['TSFE'] must migrate to request attributes / the new frontend simulation.
• TCA: ctrl.searchFields is dropped in v14 in favour of 'searchable' => true per column (primarily affects backend search, not Index Queue field mappings).

Production Checklist  

Conclusion  

EXT:solr elevates TYPO3 search to an enterprise level – with facets, autocomplete, highlighting, and, since Solr 9.8, semantic vector search. The extension is mature, actively maintained by dkd Internet Service , and locally ready to use with DDEV in just a few minutes.

The three key takeaways:

1. EXT:solr indexes everything – pages, news, products, files. The Index Queue and PSR-14 events make integration flexible and extensible.
2. Vector search on the Solr server – The language-models module (Text-to-Vector, e.g., knn_text_to_vector) in Solr 9.8+ brings semantic search to the Solr core; check the EXT:solr integration for all steps in the current release.
3. The setup is straightforward – install the DDEV add-on, configure the cores, create the scheduler task. Done.

When deciding whether the standard search is sufficient for your project or if a dedicated search infrastructure is needed: as soon as you have more than a few hundred pages, need to make structured data searchable, or require facets – there is no getting around Solr.