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

The built-in TYPO3 search queries 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 need a dedicated search infrastructure. Apache Solr delivers 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 llm module (from Solr 10: language-models; embedding/vector pipeline, e.g., knn_text_to_vector), and how you can implement enterprise search in your project.

Table of Contents  

What EXT:solr Delivers  

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 into 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 route to a local Solr instance is the official DDEV addon :

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 create the cores after startup in .ddev/config.yaml:

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 those who prefer not to run 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 Heart of the System  

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

Indexing Pages  

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

Indexing Arbitrary Records  

Every 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
            }
        }
    }
}

An overview of the three content objects:

Dynamic Fields  

EXT:solr utilises dynamic field suffixes to add custom fields without modifying the schema :

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 queued 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, the siteHashStrategy controls how the site hash is generated in Solr documents. For new TYPO3 13.4+ projects, siteHashStrategy = 1 (Site-Identifier) is recommended; older defaults might still use the domain-based variant (0, deprecated). A change of strategy requires a complete re-indexing.

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 module llm (Text-to-Vector, embedding pipeline; renamed to language-models from Solr 10) . This enables semantic search directly on the Solr server – without a separate vector database and without additional middleware. Classes and configuration follow the packages org.apache.solr.llm.* / solr.llm.* (in Solr 10+: org.apache.solr.languagemodels.* / solr.languagemodels.*; depending on the Solr version, please check the Reference Guide).

The LLM Module (Solr 9.8: "llm" / from Solr 10: "language-models" / Text-to-Vector)  

The pipeline solves the vocabulary mismatch problem of classic keyword search: users phrase their questions differently to how the content is written. Texts and search queries are transformed 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 allows you to benefit from exact keyword matches and semantic similarity.

Use Cases  

Troubleshooting in 6 Steps  

If the search doesn't work, the problem lies in one of four areas: Connection, Indexing, Solr Core, or Frontend. Proceed systematically.

Diagnostic Flowchart  

Common Errors and Solutions  

Enabling Logging  

For deeper diagnostics, enable TypoScript logging (dev/staging only):

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 fires PSR-14 events at central points, which you can utilise 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,
        };
    }
}

Overview of Important Events  

TYPO3 v14: Changes for Developers  

If you are bringing 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 now use strictly typed ViewHelper arguments and 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 removed in v14 in favour of 'searchable' => true per column (primarily affects the backend search, not the Index Queue field mappings).

Production Checklist  

Conclusion  

EXT:solr elevates TYPO3 search to 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 ready to use locally with DDEV in just a few minutes.

The three core takeaways:

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

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