MySQL 8.4.3
Source Code Documentation
opt_explain.h
Go to the documentation of this file.
1/* Copyright (c) 2011, 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 OPT_EXPLAIN_INCLUDED
25#define OPT_EXPLAIN_INCLUDED
26
27/**
28 @file sql/opt_explain.h
29 EXPLAIN @<command@>.
30
31Single table UPDATE/DELETE commands are explained by the
32explain_single_table_modification() function.
33
34A query expression (complete SELECT query possibly including
35subqueries and unions), INSERT...SELECT and multitable UPDATE/DELETE
36commands are explained like this:
37
38(1) explain_query_expression()
39
40Is the entry point. Forwards the job to explain_query_expression().
41
42(2) explain_query_expression()
43
44Is for a Query_expression, prepares, optimizes, explains one JOIN for each
45"top-level" Query_blocks of the unit (like: all SELECTs of a UNION; but not
46subqueries), and one or more JOIN for the post processing block Query_block of
47set operations (e.g. UNION), see query_term.h; each JOIN explain (JOIN::exec())
48calls explain_query_specification()
49
50(3) explain_query_specification()
51
52Is for a single Query_block (post processing or not, see query_term.h).
53It needs a prepared and optimized JOIN, for which it builds the EXPLAIN rows.
54But it also launches the EXPLAIN process for "inner units" (==subqueries of this
55Query_block), by calling explain_query_expression() for each of them.
56*/
57
58#include "my_base.h"
59#include "my_sqlcommand.h"
60#include "my_thread_local.h"
63#include "sql/query_result.h" // Query_result_send
64#include "sql/sql_cmd.h" // Sql_cmd
66#include "sys/types.h"
67
68class Item;
69class Query_block;
71class Query_term;
72class String;
73class THD;
74struct AccessPath;
75struct TABLE;
76template <class T>
77class mem_root_deque;
78
79extern const char *join_type_str[];
80
81/** Table modification plan for JOIN-less statements (update/delete) */
83 public:
84 THD *const thd; ///< Owning thread
85 const enum_mod_type
86 mod_type; ///< Modification type - MT_INSERT/MT_UPDATE/etc
87 TABLE *table; ///< Table to modify
88
91 Item *condition{nullptr};
92 uint key; ///< Key to use
93 ha_rows limit; ///< Limit
94 bool need_tmp_table; ///< Whether tmp table needs to be used
95 bool need_sort; ///< Whether to use filesort
96 bool used_key_is_modified; ///< Whether the key used to scan is modified
97 const char *message; ///< Arbitrary message
98 bool zero_result; ///< true <=> plan will not be executed
99 ha_rows examined_rows; ///< # of rows expected to be examined in the table
100
101 Modification_plan(THD *thd_arg, enum_mod_type mt, TABLE *table_arg,
102 enum join_type type_arg, AccessPath *quick_arg,
103 Item *condition_arg, uint key_arg, ha_rows limit_arg,
104 bool need_tmp_table_arg, bool need_sort_arg,
105 bool used_key_is_modified_arg, ha_rows rows);
106
107 Modification_plan(THD *thd_arg, enum_mod_type mt, TABLE *table_arg,
108 const char *message_arg, bool zero_result_arg,
109 ha_rows rows);
110
112
113 private:
114 void register_in_thd();
115};
116
117/**
118 EXPLAIN functionality for Query_result_insert, Query_result_update and
119 Query_result_delete.
120
121 This class objects substitute Query_result_insert, Query_result_update and
122 Query_result_delete data interceptor objects to implement EXPLAIN for INSERT,
123 REPLACE and multi-table UPDATE and DELETE queries.
124 Query_result_explain class object initializes tables like Query_result_insert,
125 Query_result_update or Query_result_delete data interceptor do, but it
126 suppresses table data modification by the underlying interceptor object.
127 Thus, we can use Query_result_explain object in the context of EXPLAIN INSERT/
128 REPLACE/UPDATE/DELETE query like we use Query_result_send in the context of
129 EXPLAIN SELECT command:
130 1) in presence of lex->describe flag, pass Query_result_explain object to
131 execution function,
132 2) it calls prepare(), optimize() and start_execution() functions
133 to mark modified tables etc.
134*/
135
137 protected:
138 /**
139 Pointer to underlying Query_result_insert, Query_result_update or
140 Query_result_delete object.
141 */
143
144 public:
146 Query_result *interceptor_arg)
147 : Query_result_send(), interceptor(interceptor_arg) {
148 unit = unit_arg;
149 }
150 bool use_protocol_adapter() const override { return false; }
151
152 protected:
154 Query_expression *u) override {
155 return Query_result_send::prepare(thd, list, u) ||
156 interceptor->prepare(thd, list, u);
157 }
158
159 bool start_execution(THD *thd) override {
162 }
163
164 void cleanup() override {
167 }
168};
169
170/**
171 * Wrapper class for writing EXPLAIN output to a user variable.
172 *
173 * This class overrides Query_result_send::send_data() to write the output of
174 * the EXPLAIN query to the user variable specified by m_variable_name.
175 */
177 public:
179 std::string_view variable_name)
180 : Query_result_explain(expr, child), m_variable_name(variable_name) {}
181
183 uint) override {
184 return false;
185 }
186
187 bool send_data(THD *thd, const mem_root_deque<Item *> &items) override;
188
189 bool send_eof(THD *thd) override;
190
191 private:
192 std::string_view m_variable_name;
193};
194
195bool explain_single_table_modification(THD *explain_thd, const THD *query_thd,
196 const Modification_plan *plan,
197 Query_block *select);
198bool explain_query(THD *explain_thd, const THD *query_thd,
199 Query_expression *unit);
200bool explain_query_specification(THD *explain_thd, const THD *query_thd,
201 Query_term *query_term,
203
205 public:
208
211 }
212
213 bool execute(THD *thd) override;
214
215 private:
216 /// connection_id in EXPLAIN FOR CONNECTION <connection_id>
218};
219
220// Used to generate the "query" field in JSON explain object.
221void print_query_for_explain(const THD *query_thd, Query_expression *unit,
222 String *str);
223
224#endif /* OPT_EXPLAIN_INCLUDED */
Base class that is used to represent any kind of expression in a relational query.
Definition: item.h:936
Table modification plan for JOIN-less statements (update/delete)
Definition: opt_explain.h:82
TABLE * table
Table to modify.
Definition: opt_explain.h:87
ha_rows limit
Limit.
Definition: opt_explain.h:93
THD *const thd
Owning thread.
Definition: opt_explain.h:84
const enum_mod_type mod_type
Modification type - MT_INSERT/MT_UPDATE/etc.
Definition: opt_explain.h:86
uint key
Key to use.
Definition: opt_explain.h:92
bool need_sort
Whether to use filesort.
Definition: opt_explain.h:95
Modification_plan(THD *thd_arg, enum_mod_type mt, TABLE *table_arg, enum join_type type_arg, AccessPath *quick_arg, Item *condition_arg, uint key_arg, ha_rows limit_arg, bool need_tmp_table_arg, bool need_sort_arg, bool used_key_is_modified_arg, ha_rows rows)
Modification_plan's constructor, to represent that we will use an access method on the table.
Definition: opt_explain.cc:2574
Item * condition
Definition: opt_explain.h:91
bool zero_result
true <=> plan will not be executed
Definition: opt_explain.h:98
void register_in_thd()
Definition: opt_explain.cc:2540
enum join_type type
Definition: opt_explain.h:89
bool used_key_is_modified
Whether the key used to scan is modified.
Definition: opt_explain.h:96
ha_rows examined_rows
Definition: opt_explain.h:99
~Modification_plan()
Definition: opt_explain.cc:2633
bool need_tmp_table
Whether tmp table needs to be used.
Definition: opt_explain.h:94
const char * message
Arbitrary message.
Definition: opt_explain.h:97
AccessPath * range_scan
Definition: opt_explain.h:90
This class represents a query block, aka a query specification, which is a query consisting of a SELE...
Definition: sql_lex.h:1163
This class represents a query expression (one query block or several query blocks combined with UNION...
Definition: sql_lex.h:626
Wrapper class for writing EXPLAIN output to a user variable.
Definition: opt_explain.h:176
Query_result_explain_into_var(Query_expression *expr, Query_result *child, std::string_view variable_name)
Definition: opt_explain.h:178
bool send_eof(THD *thd) override
Definition: opt_explain.cc:2654
std::string_view m_variable_name
Definition: opt_explain.h:192
bool send_result_set_metadata(THD *, const mem_root_deque< Item * > &, uint) override
Definition: opt_explain.h:182
bool send_data(THD *thd, const mem_root_deque< Item * > &items) override
Definition: opt_explain.cc:2643
EXPLAIN functionality for Query_result_insert, Query_result_update and Query_result_delete.
Definition: opt_explain.h:136
bool prepare(THD *thd, const mem_root_deque< Item * > &list, Query_expression *u) override
Perform preparation specific to the query expression or DML statement.
Definition: opt_explain.h:153
bool start_execution(THD *thd) override
Prepare for execution of the query expression or DML statement.
Definition: opt_explain.h:159
Query_result_explain(Query_expression *unit_arg, Query_result *interceptor_arg)
Definition: opt_explain.h:145
void cleanup() override
Cleanup after this execution.
Definition: opt_explain.h:164
bool use_protocol_adapter() const override
Definition: opt_explain.h:150
Query_result * interceptor
Pointer to underlying Query_result_insert, Query_result_update or Query_result_delete object.
Definition: opt_explain.h:142
Definition: query_result.h:191
void cleanup() override
Cleanup after this execution.
Definition: query_result.h:207
Definition: query_result.h:58
virtual bool prepare(THD *, const mem_root_deque< Item * > &, Query_expression *u)
Perform preparation specific to the query expression or DML statement.
Definition: query_result.h:99
virtual void cleanup()
Cleanup after this execution.
Definition: query_result.h:152
Query_expression * unit
Definition: query_result.h:60
virtual bool start_execution(THD *)
Prepare for execution of the query expression or DML statement.
Definition: query_result.h:114
Query term tree structure.
Definition: query_term.h:209
Definition: opt_explain.h:204
my_thread_id m_thread_id
connection_id in EXPLAIN FOR CONNECTION <connection_id>
Definition: opt_explain.h:217
bool execute(THD *thd) override
Entry point for EXPLAIN CONNECTION: locates the connection by its ID, takes proper locks,...
Definition: opt_explain.cc:2433
Sql_cmd_explain_other_thread(my_thread_id thread_id)
Definition: opt_explain.h:206
enum_sql_command sql_command_code() const override
Return the command code for this statement.
Definition: opt_explain.h:209
Representation of an SQL command.
Definition: sql_cmd.h:83
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
A (partial) implementation of std::deque allocating its blocks on a MEM_ROOT.
Definition: mem_root_deque.h:111
This file includes constants used by all storage engines.
my_off_t ha_rows
Definition: my_base.h:1141
enum_sql_command
Definition: my_sqlcommand.h:46
@ SQLCOM_EXPLAIN_OTHER
Definition: my_sqlcommand.h:182
static my_thread_id thread_id
Definition: my_thr_init.cc:63
uint32 my_thread_id
Definition: my_thread_local.h:34
std::string str(const mysqlrouter::ConfigGenerator::Options::Endpoint &ep)
Definition: config_generator.cc:1081
std::list< T, ut::allocator< T > > list
Specialization of list which uses ut_allocator.
Definition: ut0new.h:2879
const char * join_type_str[]
Definition: opt_explain.cc:118
bool explain_query_specification(THD *explain_thd, const THD *query_thd, Query_term *query_term, enum_parsing_context ctx)
Explain query_block's join.
Definition: opt_explain.cc:2017
bool explain_query(THD *explain_thd, const THD *query_thd, Query_expression *unit)
EXPLAIN handling for SELECT, INSERT/REPLACE SELECT, and multi-table UPDATE/DELETE queries.
Definition: opt_explain.cc:2247
bool explain_single_table_modification(THD *explain_thd, const THD *query_thd, const Modification_plan *plan, Query_block *select)
EXPLAIN handling for single-table INSERT VALUES, UPDATE, and DELETE queries.
Definition: opt_explain.cc:1906
void print_query_for_explain(const THD *query_thd, Query_expression *unit, String *str)
This code which prints the extended description is not robust against malformed queries,...
Definition: opt_explain.cc:2181
EXPLAIN FORMAT=<format> <command>.
enum_mod_type
Definition: opt_explain_format.h:138
enum_parsing_context
Names for different query parse tree parts.
Definition: parse_tree_node_base.h:61
Representation of an SQL command.
Common types of the Optimizer, used by optimization and execution.
join_type
Definition: sql_opt_exec_shared.h:186
@ JT_UNKNOWN
Definition: sql_opt_exec_shared.h:188
Access paths are a query planning structure that correspond 1:1 to iterators, in that an access path ...
Definition: access_path.h:213
Definition: table.h:1406