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