Apache Solr + TYPO3: Enterprise-Suche mit Facetten, Autocomplete und Vektorsuche

Die eingebaute TYPO3-Suche durchsucht Seitentitel und Inhalt – für kleine Projekte ausreichend, bei Enterprise-Anforderungen ein Flaschenhals. Wenn Sie tausende Seiten, strukturierte Records und Dateien durchsuchbar machen müssen, brauchen Sie eine dedizierte Suchinfrastruktur. Apache Solr liefert genau das – und die Extension EXT:solr integriert diese Leistungsfähigkeit nahtlos in TYPO3.

Dieser Artikel zeigt, wie EXT:solr funktioniert, was seit Solr 9.8 mit dem Modul language-models (Embedding-/Vektor-Pipeline, z. B. knn_text_to_vector) möglich ist und wie Sie Enterprise-Suche in Ihrem Projekt umsetzen.

Inhaltsverzeichnis  

Was EXT:solr leistet  

EXT:solr verbindet TYPO3 mit einem Apache Solr Server und stellt eine vollständige Enterprise-Suchinfrastruktur bereit:

Architekturübersicht  

Das System besteht aus vier zusammenarbeitenden Komponenten:

So funktioniert der Dokument-Lebenszyklus:

1. Redakteur:innen erstellen oder bearbeiten Inhalte in TYPO3.
2. Das Monitoring erkennt Änderungen über PSR-14 Events und schreibt einen Eintrag in die Index Queue.
3. Ein Scheduler-Task verarbeitet die Queue und sendet Dokumente als JSON an den Solr-Server.
4. Das Such-Plugin im Frontend sendet Abfragen an Solr und rendert Ergebnisse über Fluid-Templates.

Komponentenübersicht  

Versionskompatibilität  

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

Setup in unter 10 Minuten  

Installation via Composer  

composer require apache-solr-for-typo3/solr

Lokale Entwicklung mit DDEV  

Der schnellste Weg zur lokalen Solr-Instanz ist das offizielle DDEV-Addon :

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

Konfigurieren Sie 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'

Und in .ddev/config.yaml die Cores nach dem Start anlegen:

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

Docker-Produktion  

Für die Produktion liefert das offizielle Docker-Image vorkonfigurierte Cores für alle Sprachen:

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  

Zwei Optionen für alle, die keinen eigenen Solr-Server betreiben möchten:

TYPO3 Site-Konfiguration  

Fügen Sie die Verbindung in config/sites/<identifier>/config.yaml hinzu:

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: Das Herzstück  

Die Index Queue ist der zentrale Mechanismus, über den TYPO3-Inhalte in Solr gelangen.

Seiten indexieren  

Seiten werden out of the box indexiert – keine zusätzliche Konfiguration nötig. Der Page-Indexer rendert die Seite und sendet den Inhalt an Solr.

Beliebige Records indexieren  

Jede TYPO3-Tabelle kann über TypoScript in den Index aufgenommen werden. Hier ein Beispiel für 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
            }
        }
    }
}

Die drei Content-Objekte im Überblick:

Dynamische Felder  

EXT:solr verwendet dynamische Feld-Suffixe, um eigene Felder ohne Schema-Änderung hinzuzufügen :

Monitoring  

EXT:solr erkennt Record-Änderungen über PSR-14 Events. Zwei Modi stehen zur Verfügung:

• Sofort (Standard): Änderungen werden direkt während der DataHandler-Operation verarbeitet.
• Verzögert: Änderungen werden in der Event-Queue (tx_solr_eventqueue_item) gesammelt und von einem separaten Scheduler-Task verarbeitet.

Konfiguration über Extension Settings → monitoringType.

Site-Hash-Strategie  

Unter Admin Tools → Einstellungen → Erweiterungskonfiguration → solr steuert siteHashStrategy, wie der Site-Hash in Solr-Dokumenten gebildet wird. Für neue TYPO3-13.4+-Projekte ist siteHashStrategy = 1 (Site-Identifier) empfohlen; in älteren Defaults kann noch die domainbasierte Variante (0, deprecated) aktiv sein. Strategiewechsel erfordert ein vollständiges Neuindexieren.

Suche konfigurieren  

Basiskonfiguration  

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

Facettierte Navigation  

Facetten verwandeln die Suche in ein interaktives Filtererlebnis :

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

Verfügbare Facetten-Typen: options (Standard), queryGroup, hierarchy, dateRange, numericRange.

Autocomplete / Suggest  

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

Highlighting & Rechtschreibprüfung  

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

Vektor- und Hybridsuche mit Solr 9.8+  

Seit Apache Solr 9.8 (Januar 2025) enthält Solr das Solr-Modul language-models (Text-to-Vector, Embedding-Pipeline; in älteren Texten oft „LLM-Modul“) , das semantische Suche auf dem Solr-Server ermöglicht – ohne separate Vektor-Datenbank, ohne zusätzliche Middleware. Klassen und Konfiguration folgen den Paketen org.apache.solr.languagemodels.* / solr.languagemodels.* (je nach Solr-Version bitte die Reference Guide prüfen).

Das LLM-Modul (Solr: „language-models“ / Text-to-Vector)  

Die Pipeline löst das Vocabulary-Mismatch-Problem der klassischen Keyword-Suche: Nutzer:innen formulieren ihre Frage anders als der Inhalt es tut. Texte und Suchanfragen werden in Vektoren umgewandelt, die semantische Ähnlichkeit abbilden.

Unterstützte Embedding-Provider (via LangChain4j ):

Hybridsuche: BM25 + Vektor  

Die stärkste Konfiguration kombiniert klassisches BM25-Ranking mit Vektor-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

So profitieren Sie von exakten Keyword-Treffern und semantischer Ähnlichkeit.

Anwendungsfälle  

Troubleshooting in 6 Schritten  

Wenn die Suche nicht funktioniert, liegt das Problem an einer von vier Stellen: Verbindung, Indexierung, Solr-Core oder Frontend. Gehen Sie systematisch vor.

Diagnose-Flowchart  

Häufige Fehler und Lösungen  

Logging aktivieren  

Für tiefere Diagnose aktivieren Sie TypoScript-Logging (nur dev/staging):

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

Und konfigurieren die Log-Datei 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 für eigene Extensions  

EXT:solr feuert an zentralen Stellen PSR-14 Events , die Sie für eigene Logik nutzen können.

Benutzerdefinierte Felder zu Dokumenten hinzufügen  

<?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,
        };
    }
}

Wichtige Events im Überblick  

TYPO3 v14: Änderungen für Entwickler  

Wenn Sie EXT:solr auf TYPO3 v14 / Fluid 5.0 bringen, sind laut SKILL und Upstream u. a. diese Punkte relevant:

• Fluid 5.0: Such-Templates und Facetten-Partials streng typisierte ViewHelper-Argumente, keine underscore-präfixierten Template-Variablen – eigene Overrides prüfen.
• TypoScriptFrontendController: Custom-Indexer oder Plugins, die $GLOBALS['TSFE'] nutzen, müssen auf Request-Attribute / die neue Frontend-Simulation migrieren.
• TCA: ctrl.searchFields entfällt in v14 zugunsten von 'searchable' => true pro Spalte (betrifft v. a. Backend-Suche, nicht die Index-Queue-Feldmappings).

Produktions-Checkliste  

Fazit  

EXT:solr hebt die TYPO3-Suche auf Enterprise-Niveau – mit Facetten, Autocomplete, Highlighting und seit Solr 9.8 auch mit semantischer Vektorsuche. Die Extension ist ausgereift, wird aktiv von dkd Internet Service gepflegt und ist lokal mit DDEV in wenigen Minuten einsatzbereit.

Die drei zentralen Erkenntnisse:

1. EXT:solr indexiert alles – Seiten, News, Produkte, Dateien. Die Index Queue und PSR-14 Events machen die Integration flexibel und erweiterbar.
2. Vektorsuche auf dem Solr-Server – Das Modul language-models (Text-to-Vector, z. B. knn_text_to_vector) in Solr 9.8+ bringt semantische Suche auf den Solr-Kern; EXT:solr-Integration für alle Schritte prüfen Sie im aktuellen Release.
3. Das Setup ist unkompliziert – DDEV-Addon installieren, Cores konfigurieren, Scheduler-Task erstellen. Fertig.

Wenn Sie entscheiden, ob die Standardsuche für Ihr Projekt reicht oder eine dedizierte Suchinfrastruktur nötig ist: Sobald Sie mehr als einige hundert Seiten haben, strukturierte Daten durchsuchbar machen oder Facetten benötigen – führt kein Weg an Solr vorbei.