Skip navigation links
MySQL 5.1 Referenzhandbuch :: 26 MySQL erweitern :: 26.2 Die MySQL-Plug-In-Schnittstelle :: 26.2.5 Schreiben von Plug-Ins :: 26.2.5.2 Typspezifische Plug-In-Strukturen und -Funktionen
26.2.5.3 Erzeugen einer Plug-In-Bibliothek »
Section Navigation      [Toggle]

26.2.5.2. Typspezifische Plug-In-Strukturen und -Funktionen

In der st_mysql_plugin-Struktur, die eine allgemeine Plug-In-Deklaration definiert, verweist der Bestandteil info auf einen typspezifischen Plug-In-Deskriptor. Bei einem Volltext-Parser-Plug-In entspricht dieser Deskriptor der st_mysql_ftparser-Struktur in der plugin.h-Datei: 

struct st_mysql_ftparser
{
  int interface_version;
  int (*parse)(MYSQL_FTPARSER_PARAM *param);
  int (*init)(MYSQL_FTPARSER_PARAM *param);
  int (*deinit)(MYSQL_FTPARSER_PARAM *param);
};

Wie die Strukturdefinition zeigt, hat der Deskriptor eine Versionsnummer (MYSQL_FTPARSER_INTERFACE_VERSION für Volltext-Parser-Plug-Ins) und enthält Zeiger auf drei Funktionen. Die Bestandteile init und deinit sollten auf eine Funktion verweisen oder auf 0 gesetzt werden, wenn die Funktion nicht gebraucht wird. Der Bestandteil parse muss auf die Parse-Funktion verweisen.

Ein Volltext-Parser-Plug-In wird für zwei Dinge verwendet: Indizierung und Suchoperationen. In beiden Fällen ruft der Server die Initialisierungs- und Deinitialisierungsfunktion am Anfang und am Ende der Verarbeitung jeder SQL-Anweisung auf, in der das Plug-In benutzt wird. Während der Verarbeitung der Anweisung ruft der Server die Parsing-Hauptfunktion jedoch kontextabhängig auf:

  • Zum Indizieren ruft der Server den Parser für jeden zu indizierenden Spaltenwert auf.

  • In Suchoperationen ruft der Server den Parser auf, um den Such-String zu parsen. Ebenso kann der Parser für Zeilen aufgerufen werden, die von der Anweisung verarbeitet werden. Im Modus für natürliche Sprache braucht der Server den Parser nicht aufzurufen. Ini Phrasensuchen im booleschen Modus oder Suchen in natürlicher Sprache mit Abfrageerweiterung (Query Expansion) wird der Parser eingesetzt, um in den Spaltenwerten Informationen zu parsen, die nicht im Index vorliegen. Wenn eine Suche nach einer Spalte mit FULLTEXT-Index im booleschen Modus durchgeführt wird, wird ebenfalls der eingebaute Parser aufgerufen. (Plug-Ins sind mit konkreten Indizes verbunden. Ist kein Index vorhanden, wird auch kein Plug-In verwendet.)

Beachten Sie, dass die Plug-In-Deklaration im Plug-In-Bibliotheksdeskriptor Initialisierungs- und Deinitialisierungsfunktionen hat, ebenso wie der Plug-In-Deskriptor, auf den sie verweist. Diese Funktionspaare dienen unterschiedlichen Zwecken und werden aus unterschiedlichen Gründen aufgerufen:

  • Für die Plug-In-Deklaration im Plug-In-Bibliotheksdeskriptor werden die Initialisierungs- und Deinitialisierungsfunktionen beim Laden und Entladen des Plug-Ins aufgerufen.

  • Für den Plug-In-Deskriptor werden die Initialisierungs- und Deinitialisierungsfunktionen für jede SQL-Anweisung aufgerufen, in der das Plug-In benutzt wird.

Jede API-Funktion, die im Plug-In-Deskriptor genannt ist, sollte null bei einem Erfolg und einen von null verschiedenen Wert bei einem Misserfolg zurückgeben, und jede sollte ein Argument entgegennehmen, das auf eine MYSQL_FTPARSER_PARAM-Struktur verweist, die den Parsing-Kontext enthält. Die Struktur ist wie folgt definiert: 

typedef struct st_mysql_ftparser_param
{
  int (*mysql_parse)(void *param, byte *doc, uint doc_len);
  int (*mysql_add_word)(void *param, byte *word, uint word_len,
                        MYSQL_FTPARSER_BOOLEAN_INFO *boolean_info);
  void *ftparser_state;
  void *mysql_ftparam;
  CHARSET_INFO *cs;
  byte *doc;
  uint length;
  int mode;
} MYSQL_FTPARSER_PARAM;

Die Bestandteile der Struktur werden folgendermaßen benutzt:

  • mysql_parse

    Ein Zeiger auf eine Callback-Funktion, die den eingebauten Parser des Servers aufruft. Diesen Callback verwenden Sie, wenn das Plug-In als Frontend des eingebauten Parsers fungiert. Wenn also die Plug-In-Parsing-Funktion aufgerufen wird, soll sie die Eingabe verarbeiten, um den Inhalt zu extrahieren, und diesen dann an den mysql_parse-Callback übergeben.

    Der erste Parameter dieser Callback-Funktion sollte der mysql_ftparam-Teil der Struktur des Parsing-Kontextes sein. Das heißt: Wenn param auf die Struktur verweist, wird der Callback folgendermaßen aufgerufen: 

    param->mysql_parse(param->mysql_ftparam, ...);

    Ein Frontend-Plug-In kann Text extrahieren und komplett oder häppchenweise an den eingebauten Parser übergeben. Im zweiten Fall behandelt der eingebaute Parser die Textstücke, als befänden sich implizite Wortgrenzen zwischen ihnen.

  • mysql_add_word

    Ein Zeiger auf eine Callback-Funktion, die einem Volltextindex oder der Liste der Suchbegriffe ein Wort hinzufügt. Diesen Callback verwenden Sie, wenn das Parser-Plug-In den eingebauten Parser ersetzen soll. Das bedeutet: Wenn die Parsing-Funktion des Plug-Ins aufgerufen wird, soll sie die Eingabe in Wörter parsen und für jedes Wort den mysql_add_word-Callback aufrufen.

    Der erste Parameter dieser Callback-Funktion soll der mysql_ftparam-Teil der Struktur des Parsing-Kontexts sein. Das heißt: Wenn param auf die Struktur verweist, wird der Callback wie folgt aufgerufen: 

    param->mysql_add_word(param->mysql_ftparam, ...);

  • ftparser_state

    Dies ist ein generischer Zeiger. Das Plug-In kann ihn auf die Informationen verweisen lassen, die es intern für seine eigenen Zwecke benutzt.

  • mysql_ftparam

    Wird durch den Server eingestellt und als erstes Argument an den mysql_parse- oder mysql_add_word-Callback übergeben.

  • cs

    Verweist auf den Zeichensatz für den Text, oder auf 0, wenn diese Information nicht zur Verfügung steht.

  • doc

    Ein Zeiger auf den zu parsenden Text.

  • length

    Die Länge des zu parsenden Texts in Bytes.

  • mode

    Der Parsing-Modus. Dieser Wert ist eine der folgenden Konstanten:

    • MYSQL_FTPARSER_SIMPLE_MODE

      Parsen im schnellen, einfachen Modus. Dies wird für Indizes und für Anfragen mit natürlichen Sprachen verwendet. Der Parser sollte an den Server nur die zu indizierenden Wörter übergeben. Wenn er Längenbeschränkungen oder eine Liste mit zu ignorierenden Stoppwörtern verwendet, soll er die hierdurch ausgeschlossenen Wörter nicht an den Server übergeben.

    • MYSQL_FTPARSER_WITH_STOPWORDS

      Parsen im Stoppwortmodus. Dies wird bei booleschen Suchoperationen für den Abgleich von Begriffen verwendet. Der Parser sollte alle Wörter an den Server übergeben, auch Stoppwörter oder Wörter, die die normalen Längenbeschränkungen übersteigen.

    • MYSQL_FTPARSER_FULL_BOOLEAN_INFO

      Parsen im booleschen Modus. Wird zum Parsen von booleschen Anfrage-Strings genutzt. Der Parser soll nicht nur Wörter, sondern auch Operatoren für den booleschen Modus erkennen, und diese als Token mit dem mysql_add_word-Callback an den Server übergeben. Um dem Server zu sagen, welche Art von Token übergeben wird, muss das Plug-In eine MYSQL_FTPARSER_BOOLEAN_INFO-Struktur ausfüllen und einen Zeiger auf diese Struktur mit übergeben.

Wenn der Parser im booleschen Modus aufgerufen wird, hat param->mode den Wert MYSQL_FTPARSER_FULL_BOOLEAN_INFO. Die MYSQL_FTPARSER_BOOLEAN_INFO-Struktur, die der Parser zur Übergabe von Token-Informationen an den Server benutzt, sieht folgendermaßen aus: 

typedef struct st_mysql_ftparser_boolean_info
{
  enum enum_ft_token_type type;
  int yesno;
  int weight_adjust;
  bool wasign;
  bool trunc;
  /* Diese sind im Parser-Zustand und müssen entfernt werden. */
  byte prev;
  byte *quot;
} MYSQL_FTPARSER_BOOLEAN_INFO;

Der Parser sollte die Bestandteile der Struktur folgendermaßen ausfüllen:

  • type

    Der Token-Typ. Dies sollte einer der Werte der folgenden Tabelle sein:

    Typ Bedeutung
    FT_TOKEN_EOF Ende der Daten
    FT_TOKEN_WORD Ein normales Wort
    FT_TOKEN_LEFT_PAREN Beginn einer Gruppe oder eines Teilausdrucks
    FT_TOKEN_RIGHT_PAREN Ende einer Gruppe oder eines Teilausdrucks
    FT_TOKEN_STOPWORD Ein Stoppwort

  • yesno

    Gibt an, ob das Wort vorhanden sein muss, damit eine Übereinstimmung festgestellt wird. 0 bedeutet, dass das Wort optional ist, sein Vorhandensein jedoch die Relevanz der Übereinstimmung erhöht. Werte größer 0 bedeuten, dass das Wort obligatorisch ist, und Werte kleiner 0, dass es nicht vorhanden sein darf.

  • weight_adjust

    Ein Gewichtsfaktor, der festlegt, wie viel eine Übereinstimmung für das Wort zählt. Indem man diesen Faktor herauf- oder heruntersetzt, beeinflusst man die Bedeutung, die dieses Wort in Relevanzberechnungen hat. Ist der Wert null, so erfolgt keine Anpassung der Gewichtung. Werte größer oder kleiner null bedeuten ein höheres oder geringeres Gewicht. Die Beispiele unter Abschnitt 12.7.1, „Boolesche Volltextsuche“, die <- und >-Operatoren verwenden, zeigen, wie Gewichtung funktioniert.

  • wasign

    Das Vorzeichen des Gewichtungsfaktors. Ein negativer Wert verhält sich wie der boolesche Suchoperator ~, der dafür sorgt, dass das Wort in negativer Weise zur Relevanz beiträgt.

  • trunc

    Zeigt an, ob der Abgleich in derselben Weise durchgeführt wird, als ob der Kappungsoperator * im booleschen Modus angegeben worden wäre.

Plug-Ins sollten nicht die Bestandteile prev und quot der MYSQL_FTPARSER_BOOLEAN_INFO-Struktur benutzen.

Dies ist eine Übersetzung des MySQL-Referenzhandbuchs, das sich auf dev.mysql.com befindet. Das ursprüngliche Referenzhandbuch ist auf Englisch, und diese Übersetzung ist nicht notwendigerweise so aktuell wie die englische Ausgabe. Das vorliegende deutschsprachige Handbuch behandelt MySQL bis zur Version 5.1.