1. Was SearchCriteria in Magento 2 wirklich ist

SearchCriteria Magento 2 ist die standardisierte Sprache, mit der Repositorys Listenabfragen beschreiben. Statt direkt in Collections oder SQL zu denken, beschreibt man Filter, Filtergruppen, Seitengröße und Sortierung in einer transportierbaren Struktur. Das ist wichtig, weil Service Contracts nicht nur lokal im Modul, sondern auch in APIs, Integrationen und Tests konsistent funktionieren sollen.

Die Idee ist gut, wird aber oft nur halb verstanden. Viele Entwickler verwenden SearchCriteria Magento 2 wie eine lose Sammlung von Filtern, ohne die semantische Struktur dahinter sauber zu kennen. Dann entstehen Abfragen, die scheinbar laufen, aber falsche Ergebnisse liefern, weil AND und OR anders wirken als gedacht oder weil Pagination instabil wird.

Der Kernpunkt ist: SearchCriteria ist nicht einfach nur ein Builder für „ein paar Where-Bedingungen“. Es ist ein fachlich und technisch definierter Query-Container. Wer das akzeptiert, schreibt verständlichere Repository-Abfragen und muss später weniger Exceptions, Collections oder Sonderfälle über eigene Hilfskonstrukte retten.

2. AND und OR bei SearchCriteria richtig verstehen

Die häufigste Stolperfalle in SearchCriteria Magento 2 ist die Logik von Filtern und Gruppen. Innerhalb einer FilterGroup werden Filter als OR interpretiert. Zwischen mehreren FilterGroups gilt AND. Wer das verwechselt, baut leicht Abfragen, die viel mehr oder viel weniger Datensätze liefern als beabsichtigt.

Das klingt abstrakt, ist aber im Alltag entscheidend. Wenn du etwa Produkte suchst, die aktiv sind und entweder einer bestimmten Website oder einem bestimmten Typ entsprechen, musst du die Bedingungen bewusst gruppieren. Andernfalls wirkt die Abfrage logisch anders als im Kopfmodell des Entwicklers. Genau deshalb sollte man SearchCriteria Magento 2 nicht „zusammenklicken“, sondern als boolesche Struktur entwerfen.

<?php
declare(strict_types=1);

use Magento\Framework\Api\FilterBuilder;
use Magento\Framework\Api\Search\FilterGroupBuilder;
use Magento\Framework\Api\SearchCriteriaBuilder;

$isActiveFilter = $filterBuilder
    ->setField('is_active')
    ->setConditionType('eq')
    ->setValue(1)
    ->create();

$websiteFilter = $filterBuilder
    ->setField('website_id')
    ->setConditionType('eq')
    ->setValue(1)
    ->create();

$typeFilter = $filterBuilder
    ->setField('type_id')
    ->setConditionType('eq')
    ->setValue('simple')
    ->create();

$orGroup = $filterGroupBuilder->setFilters([$websiteFilter, $typeFilter])->create();
$andGroup = $filterGroupBuilder->setFilters([$isActiveFilter])->create();

$criteria = $searchCriteriaBuilder
    ->setFilterGroups([$andGroup, $orGroup])
    ->create();

Diese Struktur bedeutet: aktiv UND (Website 1 ODER Typ simple). Wer dieselben Filter blind in dieselbe Gruppe steckt, bekommt eine andere Aussage. Genau hier trennt sich solides Query-Design von Trial-and-Error. Gute SearchCriteria Magento 2 Implementierungen sind lesbar, weil die Gruppenlogik bewusst formuliert ist.

3. Pagination und Seitengrößen sauber einsetzen

Pagination wird oft als nebensächlicher Parameter behandelt, ist aber in Wahrheit ein wichtiger Teil der Abfragequalität. SearchCriteria Magento 2 erlaubt über setCurrentPage() und setPageSize() eine kontrollierte Teilmenge. Das ist für Admin-Listen, API-Endpunkte und Integrationen zentral, weil Datenmengen sonst unnötig groß, langsam oder speicherintensiv werden.

Wichtig ist dabei die Kombination mit stabiler Sortierung. Eine paginierte Abfrage ohne eindeutige Sortierung kann bei Datenänderungen zwischen zwei Aufrufen unzuverlässige Seiten ergeben. Dann tauchen Datensätze doppelt auf oder verschwinden scheinbar. In stabilen Systemen wird SearchCriteria Magento 2 deshalb nie isoliert nach Seitengröße betrachtet, sondern immer zusammen mit einer nachvollziehbaren Sortierreihenfolge.

$criteria = $searchCriteriaBuilder
    ->setCurrentPage(2)
    ->setPageSize(50)
    ->create();

Auch fachlich ist Pagination wichtig. APIs und Backoffice-Flows sollten nicht mehr Daten laden, als der konkrete Schritt wirklich braucht. Wer alles „zur Sicherheit“ in einem Query holt, hebelt die eigentliche Stärke von Repository und SearchCriteria wieder aus.

Gerade bei Synchronisationen mit externen Systemen ist das entscheidend. Wenn ein Connector seitenweise Daten nachlädt, müssen Seitengröße, Reihenfolge und Änderungsfenster sauber zusammenspielen. Sonst entstehen doppelte Datensätze, Lücken oder unnötig hohe Lastspitzen. Gute SearchCriteria Magento 2 Pagination ist deshalb nicht nur ein UI-Thema, sondern Teil belastbarer Integrationsarchitektur.

4. Sortierung mit SortOrder bewusst steuern

Sortierung in SearchCriteria Magento 2 ist mehr als Kosmetik. Sie beeinflusst Ergebnisstabilität, Usability und teilweise auch Performance. Über SortOrder kann man definieren, nach welchem Feld und in welcher Richtung sortiert wird. Dabei sollte die Sortierung zur fachlichen Frage passen und gleichzeitig für paginierte Ergebnisse reproduzierbar bleiben.

Gerade bei APIs ist das kritisch. Wenn ein Integrationspartner „die nächsten 100 Datensätze“ zieht, braucht er eine verlässliche Reihenfolge. Eine zufällige oder implizite Ordnung produziert schwer nachvollziehbare Folgefehler. Gute SearchCriteria Magento 2 Nutzung trennt daher zwischen Filterlogik und Transportlogik: Welche Daten will ich? Und in welcher Reihenfolge werden sie ausgeliefert?

<?php
declare(strict_types=1);

use Magento\Framework\Api\SortOrder;
use Magento\Framework\Api\SortOrderBuilder;

$sortOrder = $sortOrderBuilder
    ->setField('created_at')
    ->setDirection(SortOrder::SORT_DESC)
    ->create();

$criteria = $searchCriteriaBuilder
    ->addSortOrder($sortOrder)
    ->create();

Besonders in Kombination mit Pagination sollte die Sortierung eindeutig genug sein. Wenn mehrere Datensätze denselben Zeitstempel oder Status haben, kann ein zusätzliches sekundäres Feld sinnvoll werden. Der Anspruch ist nicht Schönheit, sondern Reproduzierbarkeit.

5. SearchCriteria in Repository-Praxis

In der Praxis ist SearchCriteria Magento 2 am wertvollsten, wenn Service Contracts bewusst entworfen sind. Das Repository sollte eine fachlich sinnvolle Liste zurückgeben, nicht nur irgendeine technische Collection-Verpackung. Gute Repositories dokumentieren, welche Felder filterbar sind, welche Condition Types unterstützt werden und welche Sortierfelder stabil funktionieren.

Außerdem lohnt es sich, wiederkehrende Kriterien zentral aufzubauen. Wenn dieselbe Logik an mehreren Stellen gebraucht wird, sollte sie nicht in zehn verschiedenen Klassen neu zusammengesetzt werden. Stattdessen kann ein kleiner Builder oder Query-Service die Suchlogik bündeln. Genau dadurch bleibt SearchCriteria Magento 2 konsistent, statt im Projekt zu einer unübersichtlichen Bastelstruktur zu werden.

Ein weiterer Punkt ist Erwartungsmanagement. SearchCriteria ist stark, aber nicht grenzenlos. Sehr spezielle oder hochoptimierte Datenzugriffe brauchen manchmal dennoch eine eigene Collection-Strategie oder ein separates Read-Modell. Solange man das bewusst entscheidet, ist das kein Widerspruch zum Service-Contract-Ansatz, sondern gutes Engineering.

Im Teamkontext lohnt sich zudem eine kleine Query-Konvention. Welche Felder sind offiziell filterbar? Welche Condition Types gelten als supported? Welche Standards gelten für Default-Sortierung und maximale Seitengröße? Solche Regeln klingen klein, verhindern aber, dass SearchCriteria Magento 2 von Modul zu Modul anders verwendet wird und API-Consumer mit uneinheitlichem Verhalten kämpfen.

6. Typische Fehler

Der häufigste Fehler ist falsches Verständnis von FilterGroups. Danach kommen unklare Pagination, fehlende Sortierung und die Annahme, dass jede komplexe fachliche Abfrage automatisch elegant über ein einziges SearchCriteria laufen müsse. Ebenfalls verbreitet ist, dass Entwickler einzelne Filterbuilder wiederverwenden und dadurch unbeabsichtigt Zustände mitschleppen.

Auch in Reviews sieht man oft SearchCriteria Magento 2 Code, der technisch funktioniert, aber fachlich unlesbar ist. Fünf Filter, drei Gruppen und zwei Sortierungen ohne sprechende Variablennamen erzeugen genau die Art Wartungskosten, die Service Contracts eigentlich reduzieren sollten. Query-Code sollte so lesbar sein wie gute Business-Logik.

Ein weiterer Fehler ist, SearchCriteria dort einzusetzen, wo eigentlich eine gezielte Einzelabfrage oder ein anderer Read-Path besser wäre. Standardisierung ist gut, aber nicht jedes Problem wird durch dieselbe API schöner. Entscheidend ist, dass SearchCriteria Magento 2 bewusst statt reflexhaft eingesetzt wird.

7. SearchCriteria vs. direkte Collection

Die Entscheidung zwischen Repository mit SearchCriteria Magento 2 und direkter Collection ist keine reine Stilfrage. SearchCriteria ist ideal für standardisierte Service-Contract-Abfragen, API-Nutzung und wiederverwendbare Filterlogik. Direkte Collections können sinnvoll sein, wenn ein hochspezialisierter interner Read-Path spezielle Joins, Aggregationen oder Optimierungen braucht.

Die wichtigste Regel bleibt: Repository-Code soll verständlich sein. Wenn SearchCriteria Magento 2 das leistet, ist es der richtige Weg. Wenn es die fachliche Wahrheit eher verdeckt, braucht die Lösung vielleicht einen anderen Zuschnitt.

9. Zusammenfassung

SearchCriteria Magento 2 ist dann stark, wenn FilterGroups, Pagination und Sortierung bewusst und lesbar eingesetzt werden. Gute Repository-Abfragen spiegeln die fachliche Frage wider, statt nur technisch „irgendwie Daten zu holen“.

Die häufigsten Probleme entstehen nicht durch das Framework, sondern durch unklare Boolesche Logik und instabile Seitenergebnisse. Wer SearchCriteria als Query-Sprache ernst nimmt, spart sich viele versteckte Fehler und baut langfristig sauberere Service-Contracts.

10. FAQ: SearchCriteria in Magento 2