MySQL 8.4.3
Source Code Documentation
table_function.h
Go to the documentation of this file.
1/* Copyright (c) 2017, 2024, 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 designed to work 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 either included with
13 the program or referenced in the documentation.
14
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 GNU General Public License, version 2.0, for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with this program; if not, write to the Free Software
22 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
23
24#ifndef TABLE_FUNCTION_INCLUDED
25#define TABLE_FUNCTION_INCLUDED
26
27#include <assert.h>
28#include <sys/types.h>
29#include <array> // std::array
30
31#include "my_inttypes.h"
32#include "my_table_map.h"
33#include "sql-common/json_dom.h" // Json_wrapper
34#include "sql-common/json_path.h" // Json_path
35#include "sql/create_field.h"
36#include "sql/enum_query_type.h"
37#include "sql/mem_root_array.h"
38#include "sql/psi_memory_key.h" // key_memory_JSON
39#include "sql/sql_const.h" // Item_processor, enum_walk
40#include "sql/sql_list.h" // List
41#include "sql/table.h" // TABLE
42
43class Field;
44class Item;
45class String;
47class THD;
48
49/**
50 Class representing a table function.
51*/
52
54 protected:
55 /// Table function's result table
57 /// Whether the table function was already initialized
58 bool inited;
59
60 public:
61 explicit Table_function() : table(nullptr), inited(false) {}
62
63 virtual ~Table_function() = default;
64 /**
65 Create, but not instantiate the result table
66
67 @param thd thread handler
68 @param options options to create table
69 @param table_alias table's alias
70
71 @returns
72 true on error
73 false on success
74 */
76 const char *table_alias);
77 /**
78 Write current record to the result table and handle overflow to disk
79
80 @returns
81 true on error
82 false on success
83 */
84 bool write_row();
85
86 /**
87 Returns a field with given index
88
89 @param i field's index
90
91 @returns
92 field with given index
93 */
94 Field *get_field(uint i) {
95 assert(i < table->s->fields);
96 return table->field[i];
97 }
98 /**
99 Delete all rows in the table
100 */
101 void empty_table();
102
103 /**
104 Set the default row
105 */
106 void default_row() {}
107 /**
108 Initialize table function
109 @returns
110 true on error
111 false on success
112 */
113 virtual bool init() = 0;
114 /**
115 Initialize table function after the result table has been created
116 @returns
117 true on error
118 false on success
119 */
120 virtual bool init_args();
121 /**
122 Execute the table function - fill the result table
123 @returns
124 true on error
125 false on success
126 */
127 virtual bool fill_result_table() = 0;
128 /**
129 Returns table function's name
130 */
131 virtual const char *func_name() const = 0;
132 /**
133 Return table_map of tables used by the function
134 */
135 virtual table_map used_tables() const { return 0; }
136 /**
137 Print table function
138
139 @param thd thread handler
140 @param str string to print to
141 @param query_type type of the query
142
143 @returns
144 true on error
145 false on success
146 */
147 virtual bool print(const THD *thd, String *str,
148 enum_query_type query_type) const = 0;
149 /**
150 Clean up table function after one execution
151 */
152 void cleanup() { do_cleanup(); }
153
154 /**
155 Destroy table function object after all executions are complete
156 */
157 void destroy() { this->~Table_function(); }
158
159 virtual bool walk(Item_processor processor, enum_walk walk, uchar *arg) = 0;
160
161 private:
162 /**
163 Get the list of fields to create the result table
164 */
166 /**
167 Initialize table function's arguments
168
169 @returns
170 true on error
171 false on success
172 */
173 virtual bool do_init_args() = 0;
175 virtual void do_cleanup() {}
176};
177
178/****************************************************************************
179 JSON_TABLE function
180****************************************************************************/
181
182/// Type of columns for JSON_TABLE function
183enum class enum_jt_column {
185 JTC_PATH,
188};
189
190/// Types of ON EMPTY/ON ERROR clauses for JSON_TABLE and JSON_VALUE.
191/// @note uint16 enum base limitation is necessary for YYSTYPE.
193 ERROR,
195 DEFAULT,
197};
198
199/**
200 JT_data_source is used as a data source. It's assigned to each NESTED PATH
201 node.
202*/
203
205 public:
206 /// Vector of found values
208 /// Iterator for vector above
210 /// JSON data to seek columns' paths in
212 /// Current m_rowid, used for ORDINALITY columns
214 /**
215 true <=> NESTED PATH associated with this element is producing records.
216 Used to turn off (set to null) sibling NESTED PATHs, when one of them is
217 used to fill result table.
218 */
220
222
223 void cleanup();
224};
225
226/**
227 Reason for skipping a NESTED PATH
228*/
230 JTS_NONE = 0, // NESTED PATH isn't skipped
231 JTS_EOD, // No more data
232 JTS_SIBLING // Skipped due to other sibling NESTED PATH is running
234
235/// Column description for JSON_TABLE function
237 public:
238 /// Column type
240 /// Type of ON ERROR clause
242 /// Type of ON EMPTY clause
244 /// Default value string for ON EMPTY clause
246 /// Parsed JSON for default value of ON MISSING clause
248 /// Default value string for ON ERROR clause
250 /// Parsed JSON string for ON ERROR clause
252 /// List of nested columns, valid only for NESTED PATH
254 /// Nested path
256 /// parsed nested path
258 /// An element in table function's data source array
260 /**
261 Element in table function's data source array to feed data to child
262 nodes. Valid only for NESTED PATH.
263 */
265 /// Next sibling NESTED PATH
267 /// Previous sibling NESTED PATH
269 /// Index of field in the result table
270 int m_field_idx{-1};
271
272 public:
275 Json_on_response_type on_err, Item *error_default,
276 Json_on_response_type on_miss, Item *missing_default)
277 : m_jtc_type(col_type),
278 m_on_error(on_err),
279 m_on_empty(on_miss),
280 m_default_empty_string(missing_default),
281 m_default_error_string(error_default),
285 m_nested_columns(cols),
288 void cleanup() {}
289
290 /**
291 Fill a json table column
292
293 @details Fills a column with data, according to specification in
294 JSON_TABLE. This function handles all kinds of columns:
295 Ordinality) just saves the counter into the column's field
296 Path) extracts value, saves it to the column's field and handles
297 ON ERROR/ON EMPTY clauses
298 Exists) checks the path existence and saves either 1 or 0 into result
299 field
300 Nested path) matches the path expression against data source. If there're
301 matches, this function sets NESTED PATH's iterator over those
302 matches and resets ordinality counter.
303
304 @param[in] table_function the JSON table function
305 @param[out] skip true <=> it's a NESTED PATH node and its path
306 expression didn't return any matches or a
307 previous sibling NESTED PATH clause still producing
308 records, thus all columns of this NESTED PATH node
309 should be skipped
310
311 @returns
312 false column is filled
313 true an error occurred, execution should be stopped
314 */
315 bool fill_column(Table_function_json *table_function, jt_skip_reason *skip);
316};
317
318#define MAX_NESTED_PATH 16
319
321 /// Array of JSON Data Source for each NESTED PATH clause
322 std::array<JT_data_source, MAX_NESTED_PATH> m_jds;
323 /// List of fields for tmp table creation
325 /// Tree of COLUMN clauses
327 /// Array of all columns - the flattened tree above
329 /// JSON_TABLE's alias, for error reporting
330 const char *m_table_alias;
331
332 /** Whether source data has been parsed. */
334 /// JSON_TABLE's data source expression
336
337 public:
338 Table_function_json(const char *alias, Item *a,
340
342 for (uint i = 0; i < m_all_columns.size(); i++)
344 }
345
346 /**
347 Returns function's name
348 */
349 const char *func_name() const override { return "json_table"; }
350 /**
351 Initialize the table function before creation of result table
352
353 @returns
354 true on error
355 false on success
356 */
357 bool init() override;
358
359 /**
360 Execute table function
361
362 @returns
363 true on error
364 false on success
365 */
366 bool fill_result_table() override;
367
368 /**
369 Return table_map of tables used by function's data source
370 */
371 table_map used_tables() const override;
372
373 /**
374 JSON_TABLE printout
375
376 @param thd thread handler
377 @param str string to print to
378 @param query_type type of query
379
380 @returns
381 true on error
382 false on success
383 */
384 bool print(const THD *thd, String *str,
385 enum_query_type query_type) const override;
386
387 bool walk(Item_processor processor, enum_walk walk, uchar *arg) override;
388
389 private:
390 /**
391 Fill the result table
392
393 @returns
394 true on error
395 false on success
396 */
397 bool fill_json_table();
398
399 /**
400 Initialize columns and lists for json table
401
402 @details This function does several things:
403 1) sets up list of fields (vt_list) for result table creation
404 2) fills array of all columns (m_all_columns) for execution
405 3) for each column that has default ON EMPTY or ON ERROR clauses, checks
406 the value to be proper json and initializes column appropriately
407 4) for each column that involves path, the path is checked to be correct.
408 The function goes recursively, starting from the top NESTED PATH clause
409 and going in the depth-first way, traverses the tree of columns.
410
411 @param nest_idx index of parent's element in the nesting data array
412 @param parent Parent of the NESTED PATH clause being initialized
413
414 @returns
415 false ok
416 true an error occurred
417 */
418 bool init_json_table_col_lists(uint *nest_idx, Json_table_column *parent);
419 /**
420 A helper function which sets all columns under given NESTED PATH column
421 to nullptr. Used to evaluate sibling NESTED PATHS.
422
423 @param root root NESTED PATH column
424 @param [out] last last column which belongs to the given NESTED PATH
425 */
427
428 /**
429 Return list of fields to create result table from
430 */
432 bool do_init_args() override;
433 void do_cleanup() override;
434};
435
436/**
437 Print ON EMPTY or ON ERROR clauses.
438
439 @param thd thread handler
440 @param str the string to print to
441 @param query_type formatting options
442 @param on_empty true for ON EMPTY, false for ON ERROR
443 @param response_type the type of the ON ERROR/ON EMPTY response
444 @param default_string the default string in case of DEFAULT type
445*/
446void print_on_empty_or_error(const THD *thd, String *str,
447 enum_query_type query_type, bool on_empty,
448 Json_on_response_type response_type,
449 const Item *default_string);
450#endif /* TABLE_FUNCTION_INCLUDED */
Kerberos Client Authentication nullptr
Definition: auth_kerberos_client_plugin.cc:251
Create_field is a description a field/column that may or may not exists in a table.
Definition: create_field.h:51
Definition: field.h:575
Base class that is used to represent any kind of expression in a relational query.
Definition: item.h:936
JT_data_source is used as a data source.
Definition: table_function.h:204
Json_wrapper_vector v
Vector of found values.
Definition: table_function.h:207
Json_wrapper_vector::iterator it
Iterator for vector above.
Definition: table_function.h:209
void cleanup()
Definition: table_function.cc:773
bool producing_records
true <=> NESTED PATH associated with this element is producing records.
Definition: table_function.h:219
Json_wrapper jdata
JSON data to seek columns' paths in.
Definition: table_function.h:211
JT_data_source()
Definition: table_function.h:221
uint m_rowid
Current m_rowid, used for ORDINALITY columns.
Definition: table_function.h:213
A JSON path expression.
Definition: json_path.h:353
Column description for JSON_TABLE function.
Definition: table_function.h:236
Json_wrapper m_default_empty_json
Parsed JSON for default value of ON MISSING clause.
Definition: table_function.h:247
Item * m_default_empty_string
Default value string for ON EMPTY clause.
Definition: table_function.h:245
List< Json_table_column > * m_nested_columns
List of nested columns, valid only for NESTED PATH.
Definition: table_function.h:253
Item * m_default_error_string
Default value string for ON ERROR clause.
Definition: table_function.h:249
Item * m_path_string
Nested path.
Definition: table_function.h:255
Json_on_response_type m_on_empty
Type of ON EMPTY clause.
Definition: table_function.h:243
Json_table_column(enum_jt_column col_type, Item *path, Json_on_response_type on_err, Item *error_default, Json_on_response_type on_miss, Item *missing_default)
Definition: table_function.h:274
JT_data_source * m_jds_elt
An element in table function's data source array.
Definition: table_function.h:259
Json_wrapper m_default_error_json
Parsed JSON string for ON ERROR clause.
Definition: table_function.h:251
Json_table_column(Item *path, List< Json_table_column > *cols)
Definition: table_function.h:283
bool fill_column(Table_function_json *table_function, jt_skip_reason *skip)
Fill a json table column.
Definition: table_function.cc:333
~Json_table_column()
Definition: table_function.cc:487
Json_on_response_type m_on_error
Type of ON ERROR clause.
Definition: table_function.h:241
int m_field_idx
Index of field in the result table.
Definition: table_function.h:270
enum_jt_column m_jtc_type
Column type.
Definition: table_function.h:239
Json_table_column * m_prev_nested
Previous sibling NESTED PATH.
Definition: table_function.h:268
Json_path m_path_json
parsed nested path
Definition: table_function.h:257
Json_table_column * m_next_nested
Next sibling NESTED PATH.
Definition: table_function.h:266
void cleanup()
Definition: table_function.h:288
Json_table_column(enum_jt_column type)
Definition: table_function.h:273
JT_data_source * m_child_jds_elt
Element in table function's data source array to feed data to child nodes.
Definition: table_function.h:264
Abstraction for accessing JSON values irrespective of whether they are (started out as) binary JSON v...
Definition: json_dom.h:1153
Definition: sql_list.h:467
A typesafe replacement for DYNAMIC_ARRAY.
Definition: mem_root_array.h:426
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:167
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_lexer_thd.h:36
Definition: table_function.h:320
Table_function_json(const char *alias, Item *a, List< Json_table_column > *cols)
Definition: table_function.cc:101
List< Json_table_column > * m_columns
Tree of COLUMN clauses.
Definition: table_function.h:326
List< Create_field > * get_field_list() override
Return list of fields to create result table from.
Definition: table_function.cc:116
~Table_function_json() override
Definition: table_function.h:341
bool walk(Item_processor processor, enum_walk walk, uchar *arg) override
Definition: table_function.cc:110
bool fill_result_table() override
Execute table function.
Definition: table_function.cc:605
std::array< JT_data_source, MAX_NESTED_PATH > m_jds
Array of JSON Data Source for each NESTED PATH clause.
Definition: table_function.h:322
void do_cleanup() override
Definition: table_function.cc:766
List< Json_table_column > m_vt_list
List of fields for tmp table creation.
Definition: table_function.h:324
const char * func_name() const override
Returns function's name.
Definition: table_function.h:349
void set_subtree_to_null(Json_table_column *root, Json_table_column **last)
A helper function which sets all columns under given NESTED PATH column to nullptr.
Definition: table_function.cc:316
bool init() override
Initialize the table function before creation of result table.
Definition: table_function.cc:295
const char * m_table_alias
JSON_TABLE's alias, for error reporting.
Definition: table_function.h:330
bool print(const THD *thd, String *str, enum_query_type query_type) const override
JSON_TABLE printout.
Definition: table_function.cc:753
bool is_source_parsed
Whether source data has been parsed.
Definition: table_function.h:333
Item * source
JSON_TABLE's data source expression.
Definition: table_function.h:335
bool do_init_args() override
Check whether given default values can be saved to fields.
Definition: table_function.cc:234
Mem_root_array< Json_table_column * > m_all_columns
Array of all columns - the flattened tree above.
Definition: table_function.h:328
bool fill_json_table()
Fill the result table.
Definition: table_function.cc:549
table_map used_tables() const override
Return table_map of tables used by function's data source.
Definition: table_function.cc:762
bool init_json_table_col_lists(uint *nest_idx, Json_table_column *parent)
Initialize columns and lists for json table.
Definition: table_function.cc:121
Class representing a table function.
Definition: table_function.h:53
Field * get_field(uint i)
Returns a field with given index.
Definition: table_function.h:94
virtual table_map used_tables() const
Return table_map of tables used by the function.
Definition: table_function.h:135
void destroy()
Destroy table function object after all executions are complete.
Definition: table_function.h:157
bool write_row()
Write current record to the result table and handle overflow to disk.
Definition: table_function.cc:72
virtual const char * func_name() const =0
Returns table function's name.
void empty_table()
Delete all rows in the table.
Definition: table_function.cc:85
bool create_result_table(THD *thd, ulonglong options, const char *table_alias)
Create, but not instantiate the result table.
Definition: table_function.cc:63
virtual ~Table_function()=default
Table_function()
Definition: table_function.h:61
virtual void do_cleanup()
Definition: table_function.h:175
virtual bool init()=0
Initialize table function.
virtual bool print(const THD *thd, String *str, enum_query_type query_type) const =0
Print table function.
virtual bool walk(Item_processor processor, enum_walk walk, uchar *arg)=0
virtual bool do_init_args()=0
Initialize table function's arguments.
virtual List< Create_field > * get_field_list()=0
Get the list of fields to create the result table.
virtual bool init_args()
Initialize table function after the result table has been created.
Definition: table_function.cc:90
void default_row()
Set the default row.
Definition: table_function.h:106
bool inited
Whether the table function was already initialized.
Definition: table_function.h:58
void cleanup()
Clean up table function after one execution.
Definition: table_function.h:152
TABLE * table
Table function's result table.
Definition: table_function.h:56
virtual bool fill_result_table()=0
Execute the table function - fill the result table.
bool setup_table_function(THD *thd)
Setup a table function to use materialization.
Definition: sql_derived.cc:991
enum_query_type
Query type constants (usable as bitmap flags).
Definition: enum_query_type.h:31
JSON DOM.
This file contains interface support for the JSON path abstraction.
Some integer typedefs for easier portability.
unsigned long long int ulonglong
Definition: my_inttypes.h:56
unsigned char uchar
Definition: my_inttypes.h:52
uint16_t uint16
Definition: my_inttypes.h:65
uint64_t table_map
Definition: my_table_map.h:30
static char * path
Definition: mysqldump.cc:149
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1081
static size_t skip(size_t pos_start, size_t match_len)
Definition: uri.cc:82
Definition: options.cc:57
PSI_memory_key key_memory_JSON
Definition: psi_memory_key.cc:53
required string type
Definition: replication_group_member_actions.proto:34
File containing constants that can be used throughout the server.
enum_walk
Enumeration for {Item,Query_block[_UNIT],Table_function}walk.
Definition: sql_const.h:287
bool(Item::*)(unsigned char *) Item_processor
Processor type for {Item,Query_block[_UNIT],Table_function}walk.
Definition: sql_const.h:305
Definition: table.h:1406
Field ** field
Definition: table.h:1449
Json_on_response_type
Types of ON EMPTY/ON ERROR clauses for JSON_TABLE and JSON_VALUE.
Definition: table_function.h:192
enum_jt_column
Type of columns for JSON_TABLE function.
Definition: table_function.h:183
jt_skip_reason
Reason for skipping a NESTED PATH.
Definition: table_function.h:229
@ JTS_EOD
Definition: table_function.h:231
@ JTS_SIBLING
Definition: table_function.h:232
@ JTS_NONE
Definition: table_function.h:230
void print_on_empty_or_error(const THD *thd, String *str, enum_query_type query_type, bool on_empty, Json_on_response_type response_type, const Item *default_string)
Print ON EMPTY or ON ERROR clauses.
Definition: table_function.cc:643