API:Query/de

Das action=query-Modul erlaubt es dem Benutzer die meisten Arten von Informationen aus der Datenbank abzurufen, es lehnt sich grob an die veraltete (und mittlerweile deaktivierte) query.php an. Zusätzlich kann man mit den Querys auch die für die Write-API notwendigen Tokens erhalten, welche zum Bearbeiten, verschieben usw. von Artikeln gebraucht werden.

Das Query-Modul setzt sich wiederum aus mehreren Submodulen zusammen, von denen jedes eine eigene Funktion hat. Mehrere Querymodule lassen sich gemeinsam verwenden.

Prinzipiell gibt es 3 Arten von Submodulen:
 * Meta-Informationen - Informationen über die Wiki selbst und den angemeldeten Benutzer
 * Eigenschaften - Seiteninformationen und -inhalte abrufen
 * Listen - Seiten nach bestimmten Kriterien auflisten lassen

Unabhängig davon hat das Query-Modul auch ein paar eigene Funktionen.

Seiten auswählen
Es gibt zwei Arten, Seiten auszuwählen: Die Seiten direkt angeben oder Generatoren verwenden, um die Seitenliste dynamisch zu generieren.

Um eine Seite direkt anzugeben, gibt es drei Wege:
 * Den -Parameter, z.B.
 * Den -Parameter, z.B.
 * Den -Parameter, z.B.
 * Die meisten Module werden bei einer übergebenen Revisions-ID die dazugehörige Seiten-ID verwenden. Nur prop=revisions nutzt derzeit die RevisionsID direkt

Man sollte beachten, dass die Titel-Liste eine "langsame Abfrage" im Sinne der darstellt, also auf 50 Titel pro Aufruf (oder 500 für Benutzer mit  -Recht) begrenzt ist.

Mit der Verwenden der Abfragen als Generator befasst sich ein eigener Absatz

Seitentitel normalisieren
Einen Seitentitel zu normalisieren bedeutet, ihn in seine "Normalform" zu überführen, also den ersten Buchstaben groß schreiben, Unterstriche durch Leerzeichen ersetzen, Übersetzung von Namensräumen und dergleichen. Dies geschieht automatisch bei allen Query-Modulen.

Fehlende Seiten und ungültige Titel
Titel, deren Seiten nicht existieren oder die üngültig sind, erscheinen trotzdem in der Antwort im Abschnitt, aber ihnen wird der Parameter   (fehlt) oder  (ungültig) angehängt. In Ausgabeformaten, die numerische Arrayschlüssel unterstützen (JSON oder PHP serialisiert), bekommen solcherlei ungültige oder fehlende Artikel negative Seiten-IDs. Query-Module ignorieren in der Regel ungültige/fehlende Seiten, da sich mit diesen keine sinnvolle Abfrage gestalten lässt

Weiterleitungen auflösen
Weiterleitungen können automatisch aufgelöst werden, so dass das Ziel der Weiterleitung anstelle des gegebenen Titels zurückgegeben / in der Abfrage genutzt wird. Das folgende Beispiel ist nicht wirklich sinnvoll, weil es keines der möglichen Abfrage-Module nutzt, aber es zeigt, wie der -Parameter funktioniert. Sowohl die Normalisierung als auch die Weiterleitungsauflösung können auftreten. Bei doppelten Weiterleitungen wird bis zum "Ziel-Artikel" aufgelöst, zirkuläre Weiterleitungen (siehe nächster Absatz) können dazu führen, dass keine Seite im Antwort-Abschnitt  zu finden sind.

Zirkuläre Weiterleitungen
Für das folgende Beispiel wird angenommen, es existieren die Weiterleitungen Seite1 &rarr; Seite2 &rarr; Seite3 &rarr; Seite1, also ein Ringschluss. Weiterhin verwenden wir mit Absicht einen nicht-normalisierten Seitennamen "seite1":

Man beachte besonders das Fehlen eines Antwort-Abschnitts

Begrenzungen
Alle Abfragen (insbesondere die Listen) liefern nur eine begrenzte Anzahl an Ergebnissen in einer Antwort. Die Grenze liegt standardmäßig bei 10 Ergebnissen, und kann bei den meisten Abfragen auf 500 für "normale" Benutzer bzw. 5000 für Bots und Administratoren (bzw. Benutzer mit dem  Recht) gesetzt werden. Weiterhin können einzelne Module die erlaubte Anzahl an Ergebnissen noch weiter einschränken.

Falls nicht klar ist, welches Limit grade für eine Abfrage gilt bzw. möglich ist, kann man auch als Wert  einsetzen. In diesem Fall wird zusätzlich ein Abfrage-Abschnitt  mit zurückgegeben, in welchem das verwendete Limit spezifiziert wird.

Fehler
Wenn man den limit-Wert in einer Abfrage zu hoch setzt, wird ein Fehler wie der folgende zurückgegeben:
 * code: aplimit
 * info: aplimit may not be over 500 (set to 1000) for users
 * Deutsch: aplimit darf bei Benutzern nicht höher sein als 500 (gegeben: 1000) (Der Präfix  wird in der Fehlermeldung durch den Präfix des meldenden Moduls ausgetauscht).

Abfragen fortsetzen
Häufig muss man Abfragen fortsetzen, weil (auch wegen der erwähnten Begrenzungen) nicht alle möglichen Ergebnisse bereits geliefert wurden. Hierzu gibt es be unvollständigen Abfragen den Abschnitt.

Hier kann man dann den Parameter  benutzen, um den nächsten Block an Ergebnissen zu bekommen:

Generatoren
Einige Query-Module lassen sich als Generatoren (oder Titellisten-Erzeuger) einsetzen (dies ist bei den entsprechenden Modulen extra vermerkt). Mit diesen Generatoren kann man andere Query-Module ansteuern, wobei die Ausgabe des Generators den Parameter,   oder   ersetzt. Nur ein generator if je Abfrage erlaubt (eine Verschachtelung von Generatoren ist also nicht möglich).

Parametern, die an den verwendeten Generator weitergeleitet werden sollen, muss ein 'g' vorangestellt werden, also zum Beispiel bei  statt   dann   bleiben ohne Effekt.

Beispiel
Als Beispiel die Nutzung von :

Weitere Beispiele für Generatoren finden sich bei den einzelnen Listen-Abfragen.