MySQL 8.0.31
Source Code Documentation
fts0ast.h
Go to the documentation of this file.
1/*****************************************************************************
2
3Copyright (c) 2007, 2022, Oracle and/or its affiliates.
4
5This program is free software; you can redistribute it and/or modify it under
6the terms of the GNU General Public License, version 2.0, as published by the
7Free Software Foundation.
8
9This program is also distributed with certain software (including but not
10limited to OpenSSL) that is licensed under separate terms, as designated in a
11particular file or component or in included license documentation. The authors
12of MySQL hereby grant you an additional permission to link the program and
13your derivative works with the separately licensed software that they have
14included with MySQL.
15
16This program is distributed in the hope that it will be useful, but WITHOUT
17ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
18FOR A PARTICULAR PURPOSE. See the GNU General Public License, version 2.0,
19for more details.
20
21You should have received a copy of the GNU General Public License along with
22this program; if not, write to the Free Software Foundation, Inc.,
2351 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24
25*****************************************************************************/
26
27/** @file include/fts0ast.h
28 The FTS query parser (AST) abstract syntax tree routines
29
30 Created 2007/03/16/03 Sunny Bains
31 *******************************************************/
32
33#ifndef INNOBASE_FST0AST_H
34#define INNOBASE_FST0AST_H
35
36#include "ha_prototypes.h"
37#include "mem0mem.h"
38
39/* The type of AST Node */
41 FTS_AST_OPER, /*!< Operator */
42 FTS_AST_NUMB, /*!< Number */
43 FTS_AST_TERM, /*!< Term (or word) */
44 FTS_AST_TEXT, /*!< Text string */
45 FTS_AST_PARSER_PHRASE_LIST, /*!< Phase for plugin parser
46 The difference from text type
47 is that we tokenize text into
48 term list */
49 FTS_AST_LIST, /*!< Expression list */
50 FTS_AST_SUBEXP_LIST /*!< Sub-Expression list */
51};
52
53/* The FTS query operators that we support */
55 FTS_NONE, /*!< No operator */
56
57 FTS_IGNORE, /*!< Ignore rows that contain
58 this word */
59
60 FTS_EXIST, /*!< Include rows that contain
61 this word */
62
63 FTS_NEGATE, /*!< Include rows that contain
64 this word but rank them
65 lower*/
66
67 FTS_INCR_RATING, /*!< Increase the rank for this
68 word*/
69
70 FTS_DECR_RATING, /*!< Decrease the rank for this
71 word*/
72
73 FTS_DISTANCE, /*!< Proximity distance */
74 FTS_IGNORE_SKIP, /*!< Transient node operator
75 signifies that this is a
76 FTS_IGNORE node, and ignored in
77 the first pass of
78 fts_ast_visit() */
79 FTS_EXIST_SKIP /*!< Transient node operator
80 signifies that this ia a
81 FTS_EXIST node, and ignored in
82 the first pass of
83 fts_ast_visit() */
84};
85
86/* Data types used by the FTS parser */
87struct fts_lexer_t;
88struct fts_ast_node_t;
89struct fts_ast_state_t;
90struct fts_ast_string_t;
91
93
94/********************************************************************
95Parse the string using the lexer setup within state.*/
96int fts_parse(
97 /* out: 0 on OK, 1 on error */
98 fts_ast_state_t *state); /*!< in: ast state instance.*/
99
100/********************************************************************
101Create an AST operator node */
103 void *arg, /*!< in: ast state */
104 fts_ast_oper_t oper); /*!< in: ast operator */
105/********************************************************************
106Create an AST term node, makes a copy of ptr */
108 void *arg, /*!< in: ast state */
109 const fts_ast_string_t *ptr); /*!< in: term string */
110/********************************************************************
111Create an AST text node */
113 void *arg, /*!< in: ast state */
114 const fts_ast_string_t *ptr); /*!< in: text string */
115/********************************************************************
116Create an AST expr list node */
118 void *arg, /*!< in: ast state */
119 fts_ast_node_t *expr); /*!< in: ast expr */
120/********************************************************************
121Create a sub-expression list node. This function takes ownership of
122expr and is responsible for deleting it. */
124 /* out: new node */
125 void *arg, /*!< in: ast state instance */
126 fts_ast_node_t *expr); /*!< in: ast expr instance */
127/********************************************************************
128Set the wildcard attribute of a term.*/
129extern void fts_ast_term_set_wildcard(
130 fts_ast_node_t *node); /*!< in: term to change */
131/********************************************************************
132Set the proximity attribute of a text node. */
133void fts_ast_text_set_distance(fts_ast_node_t *node, /*!< in/out: text node */
134 ulint distance); /*!< in: the text proximity
135 distance */
136/** Free a fts_ast_node_t instance.
137 @return next node to free */
139 fts_ast_node_t *node); /*!< in: node to free */
140/********************************************************************
141Add a sub-expression to an AST*/
143 fts_ast_node_t *list, /*!< in: list node instance */
144 fts_ast_node_t *node); /*!< in: (sub) expr to add */
145/********************************************************************
146Print the AST node recursively.*/
147extern void fts_ast_node_print(
148 fts_ast_node_t *node); /*!< in: ast node to print */
149/********************************************************************
150Free node and expr allocations.*/
151extern void fts_ast_state_free(fts_ast_state_t *state); /*!< in: state instance
152 to free */
153/** Check only union operation involved in the node
154@param[in] node ast node to check
155@return true if the node contains only union else false. */
157
158/** Traverse the AST - in-order traversal.
159 @return DB_SUCCESS if all went well */
160[[nodiscard]] dberr_t fts_ast_visit(
161 fts_ast_oper_t oper, /*!< in: FTS operator */
162 fts_ast_node_t *node, /*!< in: instance to traverse*/
163 fts_ast_callback visitor, /*!< in: callback */
164 void *arg, /*!< in: callback arg */
165 bool *has_ignore); /*!< out: whether we encounter
166 and ignored processing an
167 operator, currently we only
168 ignore FTS_IGNORE operator */
169/********************************************************************
170Create a lex instance.*/
171[[nodiscard]] fts_lexer_t *fts_lexer_create(
172 bool boolean_mode, /*!< in: query type */
173 const byte *query, /*!< in: query string */
174 ulint query_len) /*!< in: query string len */
175 MY_ATTRIBUTE((malloc));
176/********************************************************************
177Free an fts_lexer_t instance.*/
178void fts_lexer_free(fts_lexer_t *fts_lexer); /*!< in: lexer instance to
179 free */
180
181/**
182Create an ast string object, with NUL-terminator, so the string
183has one more byte than len
184@param[in] str pointer to string
185@param[in] len length of the string
186@return ast string with NUL-terminator */
188
189/**
190Free an ast string instance
191@param[in,out] ast_str string to free */
193
194/**
195Translate ast string of type FTS_AST_NUMB to unsigned long by strtoul
196@param[in] ast_str string to translate
197@param[in] base the base
198@return translated number */
199ulint fts_ast_string_to_ul(const fts_ast_string_t *ast_str, int base);
200
201/* String of length len.
202We always store the string of length len with a terminating '\0',
203regardless of there is any 0x00 in the string itself */
205 /*!< Pointer to string. */
206 byte *str;
207
208 /*!< Length of the string. */
210};
211
212/* Query term type */
214 fts_ast_string_t *ptr; /*!< Pointer to term string.*/
215 bool wildcard; /*!< true if wild card set.*/
216};
217
218/* Query text type */
220 fts_ast_string_t *ptr; /*!< Pointer to text string.*/
221 ulint distance; /*!< > 0 if proximity distance
222 set */
223};
224
225/* The list of nodes in an expr list */
227 fts_ast_node_t *head; /*!< Children list head */
228 fts_ast_node_t *tail; /*!< Children list tail */
229};
230
231/* FTS AST node to store the term, text, operator and sub-expressions.*/
233 fts_ast_type_t type; /*!< The type of node */
234 fts_ast_text_t text; /*!< Text node */
235 fts_ast_term_t term; /*!< Term node */
236 fts_ast_oper_t oper; /*!< Operator value */
237 fts_ast_list_t list; /*!< Expression list */
238 fts_ast_node_t *next; /*!< Link for expr list */
239 fts_ast_node_t *next_alloc; /*!< For tracking allocations */
240 bool visited; /*!< whether this node is
241 already processed */
243 /* Used by plugin parser */
244 fts_ast_node_t *up_node; /*!< Direct up node */
245 bool go_up; /*!< Flag if go one level up */
246};
247
248/* To track state during parsing */
250 mem_heap_t *heap; /*!< Heap to use for alloc */
251 fts_ast_node_t *root; /*!< If all goes OK, then this
252 will point to the root.*/
253
254 fts_ast_list_t list; /*!< List of nodes allocated */
255
256 fts_lexer_t *lexer; /*!< Lexer callback + arg */
257 CHARSET_INFO *charset; /*!< charset used for
258 tokenization */
259 /* Used by plugin parser */
260 fts_ast_node_t *cur_node; /*!< Current node into which
261 we add new node */
262 int depth; /*!< Depth of parsing state */
263};
264
265/** Create an AST term node, makes a copy of ptr for plugin parser
266 @return node */
268 /*==========i=====================*/
269 void *arg, /*!< in: ast state */
270 const char *ptr, /*!< in: term string */
271 const ulint len); /*!< in: term string length */
272
273/** Create an AST phrase list node for plugin parser
274 @return node */
276 void *arg); /*!< in: ast state */
277
278#ifdef UNIV_DEBUG
280#endif /* UNIV_DEBUG */
281
282#endif /* INNOBASE_FSTS0AST_H */
dberr_t
Definition: db0err.h:38
fts_ast_oper_t
Definition: fts0ast.h:54
@ FTS_IGNORE_SKIP
Transient node operator signifies that this is a FTS_IGNORE node, and ignored in the first pass of ft...
Definition: fts0ast.h:74
@ FTS_EXIST_SKIP
Transient node operator signifies that this ia a FTS_EXIST node, and ignored in the first pass of fts...
Definition: fts0ast.h:79
@ FTS_DISTANCE
Proximity distance.
Definition: fts0ast.h:73
@ FTS_INCR_RATING
Increase the rank for this word.
Definition: fts0ast.h:67
@ FTS_DECR_RATING
Decrease the rank for this word.
Definition: fts0ast.h:70
@ FTS_EXIST
Include rows that contain this word.
Definition: fts0ast.h:60
@ FTS_NONE
No operator.
Definition: fts0ast.h:55
@ FTS_IGNORE
Ignore rows that contain this word.
Definition: fts0ast.h:57
@ FTS_NEGATE
Include rows that contain this word but rank them lower.
Definition: fts0ast.h:63
void fts_ast_string_free(fts_ast_string_t *ast_str)
Free an ast string instance.
Definition: fts0ast.cc:676
fts_lexer_t * fts_lexer_create(bool boolean_mode, const byte *query, ulint query_len)
Definition: fts0pars.cc:1923
void fts_ast_text_set_distance(fts_ast_node_t *node, ulint distance)
in: the text proximity distance
Definition: fts0ast.cc:381
fts_ast_node_t * fts_ast_add_node(fts_ast_node_t *list, fts_ast_node_t *node)
in: (sub) expr to add
Definition: fts0ast.cc:334
void fts_lexer_free(fts_lexer_t *fts_lexer)
in: lexer instance to free
Definition: fts0pars.cc:1953
bool fts_ast_node_check_union(fts_ast_node_t *node)
Check only union operation involved in the node.
Definition: fts0ast.cc:492
fts_ast_node_t * fts_ast_create_node_term_for_parser(void *arg, const char *ptr, const ulint len)
Create an AST term node, makes a copy of ptr for plugin parser.
Definition: fts0ast.cc:161
fts_ast_node_t * fts_ast_create_node_subexp_list(void *arg, fts_ast_node_t *expr)
in: ast expr instance
Definition: fts0ast.cc:261
const char * fts_ast_node_type_get(fts_ast_type_t type)
Definition: fts0ast.cc:693
dberr_t(* fts_ast_callback)(fts_ast_oper_t, fts_ast_node_t *, void *)
Definition: fts0ast.h:92
int fts_parse(fts_ast_state_t *state)
in: ast state instance.
Definition: fts0pars.cc:1984
fts_ast_node_t * fts_ast_free_node(fts_ast_node_t *node)
Free a fts_ast_node_t instance.
Definition: fts0ast.cc:289
ulint fts_ast_string_to_ul(const fts_ast_string_t *ast_str, int base)
Translate ast string of type FTS_AST_NUMB to unsigned long by strtoul.
Definition: fts0ast.cc:688
fts_ast_node_t * fts_ast_create_node_phrase_list(void *arg)
Create an AST phrase list node for plugin parser.
Definition: fts0ast.cc:227
fts_ast_node_t * fts_ast_create_node_list(void *arg, fts_ast_node_t *expr)
in: ast expr
Definition: fts0ast.cc:244
fts_ast_string_t * fts_ast_string_create(const byte *str, ulint len)
Create an ast string object, with NUL-terminator, so the string has one more byte than len.
Definition: fts0ast.cc:655
fts_ast_node_t * fts_ast_create_node_term(void *arg, const fts_ast_string_t *ptr)
in: term string
Definition: fts0ast.cc:97
fts_ast_type_t
Definition: fts0ast.h:40
@ FTS_AST_NUMB
Number.
Definition: fts0ast.h:42
@ FTS_AST_TERM
Term (or word)
Definition: fts0ast.h:43
@ FTS_AST_PARSER_PHRASE_LIST
Phase for plugin parser The difference from text type is that we tokenize text into term list.
Definition: fts0ast.h:45
@ FTS_AST_OPER
Operator.
Definition: fts0ast.h:41
@ FTS_AST_SUBEXP_LIST
Sub-Expression list.
Definition: fts0ast.h:50
@ FTS_AST_TEXT
Text string.
Definition: fts0ast.h:44
@ FTS_AST_LIST
Expression list.
Definition: fts0ast.h:49
void fts_ast_state_free(fts_ast_state_t *state)
in: state instance to free
Definition: fts0ast.cc:396
dberr_t fts_ast_visit(fts_ast_oper_t oper, fts_ast_node_t *node, fts_ast_callback visitor, void *arg, bool *has_ignore)
Traverse the AST - in-order traversal.
Definition: fts0ast.cc:519
void fts_ast_term_set_wildcard(fts_ast_node_t *node)
in: term to change
Definition: fts0ast.cc:361
fts_ast_node_t * fts_ast_create_node_oper(void *arg, fts_ast_oper_t oper)
in: ast operator
Definition: fts0ast.cc:80
fts_ast_node_t * fts_ast_create_node_text(void *arg, const fts_ast_string_t *ptr)
in: text string
Definition: fts0ast.cc:190
void fts_ast_node_print(fts_ast_node_t *node)
in: ast node to print
Definition: fts0ast.cc:484
int fts_lexer(YYSTYPE *, fts_lexer_t *)
Definition: fts0pars.cc:1969
Prototypes for global functions in ha_innodb.cc that are called by InnoDB C code.
#define malloc(A)
Definition: lexyy.cc:914
The memory management.
static char * query
Definition: myisam_ftdump.cc:44
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1063
bool distance(const dd::Spatial_reference_system *srs, const Geometry *g1, const Geometry *g2, double *distance, bool *is_null) noexcept
Computes the distance between two geometries.
Definition: distance.cc:39
std::list< T, ut::allocator< T > > list
Specialization of list which uses ut_allocator.
Definition: ut0new.h:2859
required string type
Definition: replication_group_member_actions.proto:33
Definition: m_ctype.h:382
Definition: fts0ast.h:226
fts_ast_node_t * tail
Children list tail.
Definition: fts0ast.h:228
fts_ast_node_t * head
Children list head.
Definition: fts0ast.h:227
Definition: fts0ast.h:232
fts_ast_oper_t oper
Operator value.
Definition: fts0ast.h:236
fts_ast_type_t type
The type of node.
Definition: fts0ast.h:233
fts_ast_node_t * next
Link for expr list.
Definition: fts0ast.h:238
bool visited
whether this node is already processed
Definition: fts0ast.h:240
bool go_up
Flag if go one level up.
Definition: fts0ast.h:245
fts_ast_list_t list
Expression list.
Definition: fts0ast.h:237
fts_ast_term_t term
Term node.
Definition: fts0ast.h:235
fts_ast_text_t text
Text node.
Definition: fts0ast.h:234
fts_ast_node_t * up_node
Direct up node.
Definition: fts0ast.h:244
fts_ast_node_t * next_alloc
For tracking allocations.
Definition: fts0ast.h:239
trx_t * trx
Definition: fts0ast.h:242
Definition: fts0ast.h:249
fts_ast_list_t list
List of nodes allocated.
Definition: fts0ast.h:254
fts_ast_node_t * root
If all goes OK, then this will point to the root.
Definition: fts0ast.h:251
fts_ast_node_t * cur_node
Current node into which we add new node.
Definition: fts0ast.h:260
int depth
Depth of parsing state.
Definition: fts0ast.h:262
CHARSET_INFO * charset
charset used for tokenization
Definition: fts0ast.h:257
mem_heap_t * heap
Heap to use for alloc.
Definition: fts0ast.h:250
fts_lexer_t * lexer
Lexer callback + arg.
Definition: fts0ast.h:256
Definition: fts0ast.h:204
byte * str
< Pointer to string.
Definition: fts0ast.h:206
ulint len
Definition: fts0ast.h:209
Definition: fts0ast.h:213
bool wildcard
true if wild card set.
Definition: fts0ast.h:215
fts_ast_string_t * ptr
Pointer to term string.
Definition: fts0ast.h:214
Definition: fts0ast.h:219
fts_ast_string_t * ptr
Pointer to text string.
Definition: fts0ast.h:220
ulint distance
> 0 if proximity distance set
Definition: fts0ast.h:221
Definition: fts0pars.cc:109
The info structure stored at the beginning of a heap block.
Definition: mem0mem.h:299
Definition: trx0trx.h:680
unsigned long int ulint
Definition: univ.i:407