plugin_ftparser.h 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
  1. /* Copyright (c) 2005 MySQL AB, 2009 Sun Microsystems, Inc.
  2. Use is subject to license terms.
  3. This program is free software; you can redistribute it and/or modify
  4. it under the terms of the GNU General Public License as published by
  5. the Free Software Foundation; version 2 of the License.
  6. This program is distributed in the hope that it will be useful,
  7. but WITHOUT ANY WARRANTY; without even the implied warranty of
  8. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  9. GNU General Public License for more details.
  10. You should have received a copy of the GNU General Public License
  11. along with this program; if not, write to the Free Software
  12. Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
  13. #ifndef _my_plugin_ftparser_h
  14. #define _my_plugin_ftparser_h
  15. #include "plugin.h"
  16. #ifdef __cplusplus
  17. extern "C" {
  18. #endif
  19. /*************************************************************************
  20. API for Full-text parser plugin. (MYSQL_FTPARSER_PLUGIN)
  21. */
  22. #define MYSQL_FTPARSER_INTERFACE_VERSION 0x0100
  23. /* Parsing modes. Set in MYSQL_FTPARSER_PARAM::mode */
  24. enum enum_ftparser_mode
  25. {
  26. /*
  27. Fast and simple mode. This mode is used for indexing, and natural
  28. language queries.
  29. The parser is expected to return only those words that go into the
  30. index. Stopwords or too short/long words should not be returned. The
  31. 'boolean_info' argument of mysql_add_word() does not have to be set.
  32. */
  33. MYSQL_FTPARSER_SIMPLE_MODE= 0,
  34. /*
  35. Parse with stopwords mode. This mode is used in boolean searches for
  36. "phrase matching."
  37. The parser is not allowed to ignore words in this mode. Every word
  38. should be returned, including stopwords and words that are too short
  39. or long. The 'boolean_info' argument of mysql_add_word() does not
  40. have to be set.
  41. */
  42. MYSQL_FTPARSER_WITH_STOPWORDS= 1,
  43. /*
  44. Parse in boolean mode. This mode is used to parse a boolean query string.
  45. The parser should provide a valid MYSQL_FTPARSER_BOOLEAN_INFO
  46. structure in the 'boolean_info' argument to mysql_add_word().
  47. Usually that means that the parser should recognize boolean operators
  48. in the parsing stream and set appropriate fields in
  49. MYSQL_FTPARSER_BOOLEAN_INFO structure accordingly. As for
  50. MYSQL_FTPARSER_WITH_STOPWORDS mode, no word should be ignored.
  51. Instead, use FT_TOKEN_STOPWORD for the token type of such a word.
  52. */
  53. MYSQL_FTPARSER_FULL_BOOLEAN_INFO= 2
  54. };
  55. /*
  56. Token types for boolean mode searching (used for the type member of
  57. MYSQL_FTPARSER_BOOLEAN_INFO struct)
  58. FT_TOKEN_EOF: End of data.
  59. FT_TOKEN_WORD: Regular word.
  60. FT_TOKEN_LEFT_PAREN: Left parenthesis (start of group/sub-expression).
  61. FT_TOKEN_RIGHT_PAREN: Right parenthesis (end of group/sub-expression).
  62. FT_TOKEN_STOPWORD: Stopword.
  63. */
  64. enum enum_ft_token_type
  65. {
  66. FT_TOKEN_EOF= 0,
  67. FT_TOKEN_WORD= 1,
  68. FT_TOKEN_LEFT_PAREN= 2,
  69. FT_TOKEN_RIGHT_PAREN= 3,
  70. FT_TOKEN_STOPWORD= 4
  71. };
  72. /*
  73. This structure is used in boolean search mode only. It conveys
  74. boolean-mode metadata to the MySQL search engine for every word in
  75. the search query. A valid instance of this structure must be filled
  76. in by the plugin parser and passed as an argument in the call to
  77. mysql_add_word (the callback function in the MYSQL_FTPARSER_PARAM
  78. structure) when a query is parsed in boolean mode.
  79. type: The token type. Should be one of the enum_ft_token_type values.
  80. yesno: Whether the word must be present for a match to occur:
  81. >0 Must be present
  82. <0 Must not be present
  83. 0 Neither; the word is optional but its presence increases the relevance
  84. With the default settings of the ft_boolean_syntax system variable,
  85. >0 corresponds to the '+' operator, <0 corrresponds to the '-' operator,
  86. and 0 means neither operator was used.
  87. weight_adjust: A weighting factor that determines how much a match
  88. for the word counts. Positive values increase, negative - decrease the
  89. relative word's importance in the query.
  90. wasign: The sign of the word's weight in the query. If it's non-negative
  91. the match for the word will increase document relevance, if it's
  92. negative - decrease (the word becomes a "noise word", the less of it the
  93. better).
  94. trunc: Corresponds to the '*' operator in the default setting of the
  95. ft_boolean_syntax system variable.
  96. */
  97. typedef struct st_mysql_ftparser_boolean_info
  98. {
  99. enum enum_ft_token_type type;
  100. int yesno;
  101. int weight_adjust;
  102. char wasign;
  103. char trunc;
  104. /* These are parser state and must be removed. */
  105. char prev;
  106. char *quot;
  107. } MYSQL_FTPARSER_BOOLEAN_INFO;
  108. /*
  109. The following flag means that buffer with a string (document, word)
  110. may be overwritten by the caller before the end of the parsing (that is
  111. before st_mysql_ftparser::deinit() call). If one needs the string
  112. to survive between two successive calls of the parsing function, she
  113. needs to save a copy of it. The flag may be set by MySQL before calling
  114. st_mysql_ftparser::parse(), or it may be set by a plugin before calling
  115. st_mysql_ftparser_param::mysql_parse() or
  116. st_mysql_ftparser_param::mysql_add_word().
  117. */
  118. #define MYSQL_FTFLAGS_NEED_COPY 1
  119. /*
  120. An argument of the full-text parser plugin. This structure is
  121. filled in by MySQL server and passed to the parsing function of the
  122. plugin as an in/out parameter.
  123. mysql_parse: A pointer to the built-in parser implementation of the
  124. server. It's set by the server and can be used by the parser plugin
  125. to invoke the MySQL default parser. If plugin's role is to extract
  126. textual data from .doc, .pdf or .xml content, it might extract
  127. plaintext from the content, and then pass the text to the default
  128. MySQL parser to be parsed.
  129. mysql_add_word: A server callback to add a new word. When parsing
  130. a document, the server sets this to point at a function that adds
  131. the word to MySQL full-text index. When parsing a search query,
  132. this function will add the new word to the list of words to search
  133. for. The boolean_info argument can be NULL for all cases except
  134. when mode is MYSQL_FTPARSER_FULL_BOOLEAN_INFO.
  135. ftparser_state: A generic pointer. The plugin can set it to point
  136. to information to be used internally for its own purposes.
  137. mysql_ftparam: This is set by the server. It is used by MySQL functions
  138. called via mysql_parse() and mysql_add_word() callback. The plugin
  139. should not modify it.
  140. cs: Information about the character set of the document or query string.
  141. doc: A pointer to the document or query string to be parsed.
  142. length: Length of the document or query string, in bytes.
  143. flags: See MYSQL_FTFLAGS_* constants above.
  144. mode: The parsing mode. With boolean operators, with stopwords, or
  145. nothing. See enum_ftparser_mode above.
  146. */
  147. typedef struct st_mysql_ftparser_param
  148. {
  149. int (*mysql_parse)(struct st_mysql_ftparser_param *,
  150. const char *doc, int doc_len);
  151. int (*mysql_add_word)(struct st_mysql_ftparser_param *,
  152. const char *word, int word_len,
  153. MYSQL_FTPARSER_BOOLEAN_INFO *boolean_info);
  154. void *ftparser_state;
  155. void *mysql_ftparam;
  156. const struct charset_info_st *cs;
  157. const char *doc;
  158. int length;
  159. unsigned int flags;
  160. enum enum_ftparser_mode mode;
  161. } MYSQL_FTPARSER_PARAM;
  162. /*
  163. Full-text parser descriptor.
  164. interface_version is, e.g., MYSQL_FTPARSER_INTERFACE_VERSION.
  165. The parsing, initialization, and deinitialization functions are
  166. invoked per SQL statement for which the parser is used.
  167. */
  168. struct st_mysql_ftparser
  169. {
  170. int interface_version;
  171. int (*parse)(MYSQL_FTPARSER_PARAM *param);
  172. int (*init)(MYSQL_FTPARSER_PARAM *param);
  173. int (*deinit)(MYSQL_FTPARSER_PARAM *param);
  174. };
  175. #ifdef __cplusplus
  176. }
  177. #endif
  178. #endif