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