MySQL  8.0.27
Source Code Documentation
table_function.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2021, 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/create_field.h"
33 #include "sql/enum_query_type.h"
34 #include "sql/json_dom.h" // Json_wrapper
35 #include "sql/json_path.h" // Json_path
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 
42 class Field;
43 class Item;
44 class String;
46 class THD;
47 
48 /**
49  Class representing a table function.
50 */
51 
53  protected:
54  /// Table function's result table
56  /// Whether the table funciton 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
182 enum class enum_jt_column {
184  JTC_PATH,
185  JTC_EXISTS,
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,
193  NULL_VALUE,
194  DEFAULT,
195  IMPLICIT
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
232 };
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
254  Item *m_path_string{nullptr};
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),
281  m_path_string(path) {}
284  m_nested_columns(cols),
285  m_path_string(path) {}
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 
319 class Table_function_json final : public Table_function {
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 
340  ~Table_function_json() override {
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 */
445 void 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:590
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:762
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:354
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:325
~Json_table_column()
Definition: table_function.cc:478
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:1167
size_t size() const
Definition: mem_root_array.h:399
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:165
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:821
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:596
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:755
const char * func_name() const override
Returns function's name.
Definition: table_function.h:348
List< Json_table_column > m_vt_list
List of fields for tmp table creation.
Definition: table_function.h:323
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:308
bool init() override
Initialize the table function before creation of result table.
Definition: table_function.cc:287
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:744
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:753
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:540
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
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
void empty_table()
Delete all rows in the table.
Definition: table_function.cc:82
Field * get_field(uint i)
Returns a field with given index.
Definition: table_function.h:93
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 bool init_args()
Initialize table function after the result table has been created.
Definition: table_function.cc:87
virtual List< Create_field > * get_field_list()=0
Get the list of fields to create the result table.
virtual const char * func_name() const =0
Returns table function's name.
void default_row()
Set the default row.
Definition: table_function.h:105
bool inited
Whether the table funciton 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.
Dialog Client Authentication nullptr
Definition: dialog.cc:352
enum_query_type
Query type constants (usable as bitmap flags).
Definition: enum_query_type.h:30
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:130
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1056
static size_t skip(size_t pos_start, size_t match_len)
Definition: uri.cc:83
Definition: options.cc:45
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.
bool(Item::* Item_processor)(uchar *arg)
Processor type for {Item,Query_block[_UNIT],Table_function}walk.
Definition: sql_const.h:452
enum_walk
Enumeration for {Item,Query_block[_UNIT],Table_function}walk.
Definition: sql_const.h:434
bool setup_table_function(THD *thd)
Setup a table function to use materialization.
Definition: sql_derived.cc:755
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:634
unsigned int uint
Definition: uca-dump.cc:29