Einführung in dynamische Abfragen

Dynamische Abfragen beziehen sich auf Abfragen, die von Drupal dynamisch erstellt werden und nicht als expliziter Abfrage-String vorliegen. Alle Insert-, Update-, Delete- und Merge-Abfragen müssen dynamisch sein. Select-Abfragen können statisch oder dynamisch sein. Daher bezieht sich „dynamische Abfrage“ meist auf eine dynamische Select-Abfrage.

Hinweis: In 90 % der Fälle mit Select-Abfragen verwenden Sie statische Abfragen. Wenn Sie jedoch auf einem kritischen Performance-Pfad sind, sollten Sie aus Performance-Gründen query() statt select() verwenden. Nutzen Sie dynamische Abfragen nur, wenn sich Teile der Abfrage unterscheiden (z. B. bedingtes Hinzufügen von WHERE-Klauseln je nach Kontext) oder wenn die Abfrage veränderbar sein soll.

Alle dynamisch erstellten Abfragen werden mit einem Query-Objekt erzeugt, das vom entsprechenden Datenbank-Verbindungsobjekt angefordert wird. Wie bei statischen Abfragen kann in den meisten Fällen eine prozedurale Wrapperfunktion für das Query-Objekt genutzt werden. Die weiteren Query-Anweisungen werden als Methodenaufrufe des Query-Objekts ausgeführt.

Dynamische Select-Abfragen werden mit der Methode select() wie folgt gestartet:

$database = \Drupal::database();
$query = $database->select('mytable', 'mt', $options);

Hier ist mytable die Basistabelle der Abfrage, also die erste Tabelle nach dem FROM-Operator. Beachten Sie, dass keine Klammern um den Tabellennamen notwendig sind, der Query-Builder übernimmt dies automatisch. Der zweite Parameter ist der Tabellen-Alias. Falls nicht angegeben, wird der Tabellenname verwendet. Das Array $options ist optional und identisch mit dem $options-Array bei statischen Abfragen.

Der Rückgabewert von $database->select() ist ein Objekt vom Typ Select. Der Typ der Variablen $query ist somit Select. Dieses Objekt bietet eine umfangreiche Liste von Methoden wie fields(), joins() und group(), mit denen die Abfrage weiter definiert werden kann.

Dynamische Select-Abfragen können sehr einfach oder sehr komplex sein. Nachfolgend betrachten wir die einzelnen Bestandteile eines einfachen Abfrageaufbaus. Komplexere Methoden wie Joins werden auf den folgenden Seiten behandelt.

Gesamtbild

Hier ein relativ einfaches Beispiel für eine Benutzer-Tabelle.

Angenommen, wir wollen eine dynamische Abfrage erstellen, die in etwa der folgenden statischen Abfrage entspricht:

$result = $database->query("SELECT uid, name, status, created, access FROM {users} u WHERE uid <> 0 LIMIT 50 OFFSET 0");

Der dynamische Gegenpart beginnt so:

// Erzeuge ein Select-Objekt.
$database = \Drupal::database();
$query = $database->select('users', 'u');
 
// Füge Details zur Abfrage hinzu: eine Bedingung, Felder und einen Bereich.
$query->condition('u.uid', 0, '<>');
$query->fields('u', ['uid', 'name', 'status', 'created', 'access']);
$query->range(0, 50);

Dies wird oft mit einem verkürzten Syntax geschrieben, bei dem mehrere Methodenaufrufe des $query-Objekts verknüpft werden. Der obige Code wird daher häufig wie folgt geschrieben:

// Erzeuge ein Select-Objekt.
$query = $database->select('users', 'u');
 
// Füge Details zur Abfrage hinzu: eine Bedingung, Felder und einen Bereich.
$query->condition('u.uid', 0, '<>')
  ->fields('u', ['uid', 'name', 'status', 'created', 'access'])
  ->range(0, 50);

Man kann den Code noch weiter vereinfachen, indem man den Aufruf von $database->select() direkt mit Methodenaufrufen für das zurückgegebene Objekt kombiniert. So erhält man:

// Erzeuge ein Select-Objekt und füge direkt Details hinzu:
// Bedingung, Felder und Bereich.
$query = $database->select('users', 'u')
  ->condition('u.uid', 0, '<>')
  ->fields('u', ['uid', 'name', 'status', 'created', 'access'])
  ->range(0, 50);

Dies ist die vereinfachte Form der Abfrage, wie sie auch von der Benutzerverwaltungsseite genutzt wird und als Referenz dienen kann.

Ausführen der Abfrage

Sobald die Abfrage aufgebaut ist, rufen Sie execute() auf, um die Abfrage zu kompilieren und auszuführen.

$result = $query->execute();

execute() gibt ein Result-Set-/Statement-Objekt zurück, identisch zu dem Objekt, das von $database->query() zurückgegeben wird, und kann genauso durchlaufen oder ausgelesen werden:

$result = $query->execute();
foreach ($result as $record) {
  // Mit jedem $record etwas machen.
}

Hinweis: Seien Sie vorsichtig bei der Verwendung folgender Methoden mit mehrspaltigen dynamischen Abfragen:

• fetchField()
• fetchAllKeyed()
• fetchCol()

Diese Methoden erfordern derzeit numerische Spaltenindizes (0, 1, 2 usw.) und nicht Tabellennamen-Aliase. Da der Query-Builder jedoch keine garantierte Reihenfolge der zurückgegebenen Felder gewährleistet, kann die Spaltenreihenfolge vom Erwarteten abweichen. Insbesondere Ausdrücke werden immer nach den Feldern eingefügt, auch wenn sie zuerst hinzugefügt wurden. (Dieses Problem betrifft nicht statische Abfragen, die die Spalten immer in der angegebenen Reihenfolge zurückgeben.)

Debugging

Um die SQL-Abfrage zu inspizieren, die ein Query-Objekt zu einem bestimmten Zeitpunkt seiner Lebensdauer nutzt, drucken Sie das Query-Objekt aus. Um die Argumente zu prüfen, geben Sie das Array aus, das von der Methode arguments() zurückgegeben wird:

echo $query;
print_r($query->__toString());
print_r($query->arguments());