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