MySQL  8.0.18
Source Code Documentation
table_function.h
Go to the documentation of this file.
1 /* Copyright (c) 2017, 2019, Oracle and/or its affiliates. All rights reserved.
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 <sys/types.h>
27 #include <array> // std::array
28 
29 #include "field.h" // Field
30 #include "json_dom.h" // Json_wrapper
31 #include "json_path.h" // Json_path
32 #include "lex_string.h"
33 #include "my_dbug.h"
34 #include "my_inttypes.h"
35 #include "my_table_map.h"
36 #include "psi_memory_key.h" // key_memory_JSON
37 #include "sql/create_field.h"
38 #include "sql/enum_query_type.h"
39 
40 #include "sql/mem_root_array.h"
41 #include "sql_list.h" // List
42 #include "table.h" // TABLE
43 
44 class Item;
45 class String;
46 class THD;
47 
48 /**
49  Class representing a table function.
50 */
51 
53  protected:
54  /// Thread handler
55  THD *thd;
56  /// Table function's result table
58  /// Whether the table funciton was already initialized
59  bool inited;
60 
61  public:
62  Table_function(THD *thd_arg) : thd(thd_arg), table(nullptr), inited(false) {}
63 
64  virtual ~Table_function() {}
65  /**
66  Create, but not instantiate the result table
67 
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  */
75  bool create_result_table(ulonglong options, 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  DBUG_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 str string to print to
139  @param query_type type of the query
140 
141  @returns
142  true on error
143  false on success
144  */
145  virtual bool print(String *str, enum_query_type query_type) = 0;
146  /**
147  Clean up table function
148  */
149  void cleanup() {
150  do_cleanup();
151  table = nullptr;
152  inited = false;
153  }
154  /**
155  Retruns thread handler
156 
157  @returns
158  thread handler
159  */
160  inline THD *get_thd() { return thd; }
161 
162  virtual bool walk(Item_processor processor, enum_walk walk, uchar *arg) = 0;
163 
164  private:
165  /**
166  Get the list of fields to create the result table
167  */
168  virtual List<Create_field> *get_field_list() = 0;
169  /**
170  Initialize table function's arguments
171 
172  @returns
173  true on error
174  false on success
175  */
176  virtual bool do_init_args() = 0;
178  virtual void do_cleanup() {}
179 };
180 
181 /****************************************************************************
182  JSON_TABLE function
183 ****************************************************************************/
184 
185 /// Type of columns for JSON_TABLE function
186 enum class enum_jt_column {
188  JTC_PATH,
189  JTC_EXISTS,
191 };
192 
193 /// Types of ON ERROR/ON EMPTY clause for JSON_TABLE function
194 /// @note uint16 enum base limitation is necessary for YYSTYPE.
195 enum class enum_jtc_on : uint16 {
196  JTO_ERROR,
197  JTO_NULL,
198  JTO_DEFAULT,
200 };
201 
202 /**
203  JT_data_source is used as a data source. It's assigned to each NESTED PATH
204  node.
205 */
206 
208  public:
209  /// Vector of found values
211  /// Iterator for vector above
213  /// JSON data to seek columns' paths in
215  /// Current m_rowid, used for ORDINALITY columns
217  /**
218  true <=> NESTED PATH associated with this element is producing records.
219  Used to turn off (set to null) sibling NESTED PATHs, when one of them is
220  used to fill result table.
221  */
223 
226 
227  void cleanup();
228 };
229 
230 /**
231  Reason for skipping a NESTED PATH
232 */
234  JTS_NONE = 0, // NESTED PATH isn't skipped
235  JTS_EOD, // No more data
236  JTS_SIBLING // Skipped due to other sibling NESTED PATH is running
237 };
238 
239 /// Column description for JSON_TABLE function
241  public:
242  /// Column type
244  /// Type of ON ERROR clause
246  /// Type of ON EMPTY clause
248  /// Default value string for ON EMPTY clause
250  /// Parsed JSON for default value of ON MISSING clause
252  /// Default value string for ON ERROR clause
254  /// Parsed JSON string for ON ERROR clause
256  /// List of nested columns, valid only for NESTED PATH
258  /// Nested path
260  /// parsed nested path
262  /// An element in table function's data source array
264  /**
265  Element in table function's data source array to feed data to child
266  nodes. Valid only for NESTED PATH.
267  */
269  /// Next sibling NESTED PATH
271  /// Previous sibling NESTED PATH
273  /// Index of field in the result table
274  int m_field_idx{-1};
275 
276  public:
278  : m_jtc_type(type),
279  m_jds_elt(nullptr),
280  m_child_jds_elt(nullptr),
281  m_next_nested(nullptr),
282  m_prev_nested(nullptr),
283  m_field_idx(-1) {}
285  enum_jtc_on on_err, const LEX_STRING error_def,
286  enum_jtc_on on_miss, const LEX_STRING &missing_def)
287  : m_jtc_type(col_type),
288  m_on_error(on_err),
289  m_on_empty(on_miss),
290  m_default_empty_str(missing_def),
291  m_default_error_str(error_def),
292  m_path_str(path) {}
295  m_nested_columns(cols),
296  m_path_str(path) {}
297  void cleanup();
298 
299  /**
300  Process JSON_TABLE's column
301 
302  @param fld field to save data to, if applicable, NULL otherwise
303  @param[out] skip whether current NESTED PATH column should be
304  completely skipped
305  @returns
306  true on error
307  false on success
308  */
309  bool fill_column(Field *fld, jt_skip_reason *skip);
310 };
311 
312 #define MAX_NESTED_PATH 16
313 
315  /// Array of JSON Data Source for each NESTED PATH clause
316  std::array<JT_data_source, MAX_NESTED_PATH> m_jds;
317  /// List of fields for tmp table creation
319  /// Tree of COLUMN clauses
321  /// Array of all columns - the flattened tree above
323  /// JSON_TABLE's alias, for error reporting
324  const char *m_table_alias;
325 
326  /** Whether source data has been parsed. */
328  /// JSON_TABLE's data source expression
330 
331  public:
332  Table_function_json(THD *thd_arg, const char *alias, Item *a,
334 
335  /**
336  Returns function's name
337  */
338  const char *func_name() const override { return "json_table"; }
339  /**
340  Initialize the table function before creation of result table
341 
342  @returns
343  true on error
344  false on success
345  */
346  bool init() override;
347 
348  /**
349  Execute table function
350 
351  @returns
352  true on error
353  false on success
354  */
355  bool fill_result_table() override;
356 
357  /**
358  Return table_map of tables used by function's data source
359  */
360  table_map used_tables() override;
361 
362  /**
363  JSON_TABLE printout
364 
365  @param str string to print to
366  @param query_type type of query
367 
368  @returns
369  true on error
370  false on success
371  */
372  bool print(String *str, enum_query_type query_type) override;
373 
374  bool walk(Item_processor processor, enum_walk walk, uchar *arg) override;
375 
376  private:
377  /**
378  Fill the result table
379 
380  @returns
381  true on error
382  false on success
383  */
384  bool fill_json_table();
385 
386  /**
387  Prepare lists used to create tmp table and function execution
388 
389  @param nest_idx index of parent's element in the nesting data array
390  @param parent Parent of the NESTED PATH clause being initialized
391 
392  @returns
393  true on error
394  false on success
395  */
396  bool init_json_table_col_lists(uint *nest_idx, Json_table_column *parent);
397  /**
398  Set all underlying columns of a NESTED PATH to nullptr
399 
400  @param root root NESTED PATH column
401  @param [out] last last column which belongs to the given NESTED PATH
402  */
404  /**
405  Helper function to print single NESTED PATH column
406 
407  @param col column to print
408  @param str string to print to
409  @param query_type type of the query
410 
411  @returns
412  true on error
413  false on success
414  */
416  enum_query_type query_type);
417 
418  /**
419  Return list of fields to create result table from
420  */
422  bool do_init_args() override;
423  void do_cleanup() override;
424 };
425 #endif /* TABLE_FUNCTION_INCLUDED */
Abstraction for accessing JSON values irrespective of whether they are (started out as) binary JSON v...
Definition: json_dom.h:1141
Definition: table_function.h:314
Item * source
JSON_TABLE&#39;s data source expression.
Definition: table_function.h:329
unsigned long long int ulonglong
Definition: my_inttypes.h:55
std::array< JT_data_source, MAX_NESTED_PATH > m_jds
Array of JSON Data Source for each NESTED PATH clause.
Definition: table_function.h:316
unsigned char uchar
Definition: my_inttypes.h:51
bool fill_json_table()
Fill the result table.
Definition: table_function.cc:610
Field * get_field(uint i)
Returns a field with given index.
Definition: table_function.h:93
const char * m_table_alias
JSON_TABLE&#39;s alias, for error reporting.
Definition: table_function.h:324
ulonglong table_map
Definition: my_table_map.h:32
Definition: mysql_lex_string.h:34
List< Json_table_column > m_vt_list
List of fields for tmp table creation.
Definition: table_function.h:318
void cleanup()
Definition: table_function.cc:804
void empty_table()
Delete all rows in the table.
Definition: table_function.cc:82
virtual void do_cleanup()
Definition: table_function.h:178
Some integer typedefs for easier portability.
LEX_STRING m_default_empty_str
Default value string for ON EMPTY clause.
Definition: table_function.h:249
virtual table_map used_tables()
Return table_map of tables used by the function.
Definition: table_function.h:134
Definition: field.h:700
Table_function(THD *thd_arg)
Definition: table_function.h:62
JT_data_source * m_jds_elt
An element in table function&#39;s data source array.
Definition: table_function.h:263
LEX_STRING m_path_str
Nested path.
Definition: table_function.h:259
bool producing_records
true <=> NESTED PATH associated with this element is producing records.
Definition: table_function.h:222
Json_table_column(LEX_STRING path, List< Json_table_column > *cols)
Definition: table_function.h:293
Mem_root_array< Json_table_column * > m_all_columns
Array of all columns - the flattened tree above.
Definition: table_function.h:322
Json_table_column * m_prev_nested
Previous sibling NESTED PATH.
Definition: table_function.h:272
bool create_result_table(ulonglong options, const char *table_alias)
Create, but not instantiate the result table.
Definition: table_function.cc:62
bool init() override
Initialize the table function before creation of result table.
Definition: table_function.cc:325
const char * func_name() const override
Returns function&#39;s name.
Definition: table_function.h:338
~JT_data_source()
Definition: table_function.h:225
bool fill_result_table() override
Execute table function.
Definition: table_function.cc:668
enum_walk
Enumeration for {Item,SELECT_LEX[_UNIT],Table_function}walk.
Definition: sql_const.h:435
Json_path m_path_json
parsed nested path
Definition: table_function.h:261
enum_jt_column m_jtc_type
Column type.
Definition: table_function.h:243
bool inited
Whether the table funciton was already initialized.
Definition: table_function.h:59
enum_query_type
Query type constants (usable as bitmap flags).
Definition: enum_query_type.h:30
THD * thd
Thread handler.
Definition: table_function.h:55
virtual const char * func_name() const =0
Returns table function&#39;s name.
bool is_source_parsed
Whether source data has been parsed.
Definition: table_function.h:327
Using this class is fraught with peril, and you need to be very careful when doing so...
Definition: sql_string.h:161
virtual bool init()=0
Initialize table function.
Definition: table.h:1301
List< Create_field > * get_field_list() override
Return list of fields to create result table from.
Definition: table_function.cc:113
Column description for JSON_TABLE function.
Definition: table_function.h:240
Definition: table_function.h:234
Json_table_column * m_next_nested
Next sibling NESTED PATH.
Definition: table_function.h:270
uint m_rowid
Current m_rowid, used for ORDINALITY columns.
Definition: table_function.h:216
Json_wrapper_vector v
Vector of found values.
Definition: table_function.h:210
virtual bool walk(Item_processor processor, enum_walk walk, uchar *arg)=0
jt_skip_reason
Reason for skipping a NESTED PATH.
Definition: table_function.h:233
#define DBUG_ASSERT(A)
Definition: my_dbug.h:197
static size_t skip(size_t pos_start, size_t match_len)
Definition: uri.cc:83
Definition: table_function.h:236
void cleanup()
Definition: table_function.cc:548
virtual bool do_init_args()=0
Initialize table function&#39;s arguments.
virtual bool fill_result_table()=0
Execute the table function - fill the result table.
Json_table_column(enum_jt_column type)
Definition: table_function.h:277
THD * get_thd()
Retruns thread handler.
Definition: table_function.h:160
enum_jt_column
Type of columns for JSON_TABLE function.
Definition: table_function.h:186
bool walk(Item_processor processor, enum_walk walk, uchar *arg) override
Definition: table_function.cc:107
LEX_STRING m_default_error_str
Default value string for ON ERROR clause.
Definition: table_function.h:253
static char * path
Definition: mysqldump.cc:125
JSON DOM.
enum_jtc_on m_on_empty
Type of ON EMPTY clause.
Definition: table_function.h:247
uint16_t uint16
Definition: my_inttypes.h:64
void do_cleanup() override
Definition: table_function.cc:796
Definition: item.h:668
unsigned int uint
Definition: uca-dump.cc:29
#define final(a, b, c)
Definition: hash.c:109
JT_data_source is used as a data source.
Definition: table_function.h:207
int m_field_idx
Index of field in the result table.
Definition: table_function.h:274
JT_data_source * m_child_jds_elt
Element in table function&#39;s data source array to feed data to child nodes.
Definition: table_function.h:268
JT_data_source()
Definition: table_function.h:224
bool print(String *str, enum_query_type query_type) override
JSON_TABLE printout.
Definition: table_function.cc:786
List< Json_table_column > * m_nested_columns
List of nested columns, valid only for NESTED PATH.
Definition: table_function.h:257
A typesafe replacement for DYNAMIC_ARRAY.
Definition: mem_root_array.h:398
Json_wrapper_vector::iterator it
Iterator for vector above.
Definition: table_function.h:212
bool do_init_args() override
Check whether given default values can be saved to fields.
Definition: table_function.cc:274
bool(Item::* Item_processor)(uchar *arg)
Processor type for {Item,SELECT_LEX[_UNIT],Table_function}walk.
Definition: sql_const.h:453
table_map used_tables() override
Return table_map of tables used by function&#39;s data source.
Definition: table_function.cc:794
void set_subtree_to_null(Json_table_column *root, Json_table_column **last)
Set all underlying columns of a NESTED PATH to nullptr.
Definition: table_function.cc:363
Class representing a table function.
Definition: table_function.h:52
Json_wrapper m_default_empty_json
Parsed JSON for default value of ON MISSING clause.
Definition: table_function.h:251
virtual bool init_args()
Initialize table function after the result table has been created.
Definition: table_function.cc:87
int type
Definition: http_common.h:411
Create_field is a description a field/column that may or may not exists in a table.
Definition: create_field.h:50
virtual ~Table_function()
Definition: table_function.h:64
static const Query_options options
Definition: show_query_builder.cc:48
Json_table_column(enum_jt_column col_type, const LEX_STRING &path, enum_jtc_on on_err, const LEX_STRING error_def, enum_jtc_on on_miss, const LEX_STRING &missing_def)
Definition: table_function.h:284
void default_row()
Set the default row.
Definition: table_function.h:105
Table_function_json(THD *thd_arg, const char *alias, Item *a, List< Json_table_column > *cols)
Definition: table_function.cc:98
bool write_row()
Write current record to the result table and handle overflow to disk.
Definition: table_function.cc:71
enum_jtc_on
Types of ON ERROR/ON EMPTY clause for JSON_TABLE function.
Definition: table_function.h:195
enum_jtc_on m_on_error
Type of ON ERROR clause.
Definition: table_function.h:245
PSI_memory_key key_memory_JSON
Definition: psi_memory_key.cc:52
Json_wrapper m_default_error_json
Parsed JSON string for ON ERROR clause.
Definition: table_function.h:255
bool setup_table_function(THD *thd)
Setup a table function to use materialization.
Definition: sql_derived.cc:624
virtual bool print(String *str, enum_query_type query_type)=0
Print table function.
List< Json_table_column > * m_columns
Tree of COLUMN clauses.
Definition: table_function.h:320
A JSON path expression.
Definition: json_path.h:351
Json_wrapper jdata
JSON data to seek columns&#39; paths in.
Definition: table_function.h:214
bool init_json_table_col_lists(uint *nest_idx, Json_table_column *parent)
Prepare lists used to create tmp table and function execution.
Definition: table_function.cc:163
Json_wrapper * iterator
Definition: prealloced_array.h:93
Field ** field
Definition: table.h:1330
virtual List< Create_field > * get_field_list()=0
Get the list of fields to create the result table.
void cleanup()
Clean up table function.
Definition: table_function.h:149
#define false
Definition: config_static.h:43
This file contains interface support for the JSON path abstraction.
Definition: table_function.h:235
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:778
TABLE * table
Table function&#39;s result table.
Definition: table_function.h:57
bool fill_column(Field *fld, jt_skip_reason *skip)
Process JSON_TABLE&#39;s column.
Definition: table_function.cc:406
bool print_nested_path(Json_table_column *col, String *str, enum_query_type query_type)
Helper function to print single NESTED PATH column.
Definition: table_function.cc:720