MySQL 8.0.31
Source Code Documentation
ref_row_iterators.h
Go to the documentation of this file.
1#ifndef SQL_ITERATORS_REF_ROW_ITERATORS_H_
2#define SQL_ITERATORS_REF_ROW_ITERATORS_H_
3
4/* Copyright (c) 2018, 2022, Oracle and/or its affiliates.
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License, version 2.0,
8 as published by the Free Software Foundation.
9
10 This program is also distributed with certain software (including
11 but not limited to OpenSSL) that is licensed under separate terms,
12 as designated in a particular file or component or in included license
13 documentation. The authors of MySQL hereby grant you an additional
14 permission to link the program and your derivative works with the
15 separately licensed software that they have included with MySQL.
16
17 This program is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 GNU General Public License, version 2.0, for more details.
21
22 You should have received a copy of the GNU General Public License
23 along with this program; if not, write to the Free Software
24 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
25
26#include <sys/types.h>
27#include <memory>
28
29#include "my_alloc.h"
30#include "my_bitmap.h"
31#include "my_inttypes.h"
34#include "sql/sql_sort.h"
35
36class Item_func_match;
37class QEP_TAB;
38class THD;
39struct TABLE;
40struct TABLE_REF;
41
42/**
43 For each record on the left side of a join (given in Init()), returns one or
44 more matching rows from the given table, i.e., WHERE column=<ref>.
45 */
46template <bool Reverse>
47class RefIterator final : public TableRowIterator {
48 public:
49 // "examined_rows", if not nullptr, is incremented for each successful Read().
50 RefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
51 double expected_rows, ha_rows *examined_rows)
53 m_ref(ref),
54 m_use_order(use_order),
55 m_expected_rows(expected_rows),
56 m_examined_rows(examined_rows) {}
57 ~RefIterator() override;
58
59 bool Init() override;
60 int Read() override;
61
62 private:
64 const bool m_use_order;
65 const double m_expected_rows;
69};
70
71/**
72 Like RefIterator, but after it's returned all its rows, will also search for
73 rows that match NULL, i.e., WHERE column=<ref> OR column IS NULL.
74 */
75class RefOrNullIterator final : public TableRowIterator {
76 public:
77 // "examined_rows", if not nullptr, is incremented for each successful Read().
78 RefOrNullIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
79 double expected_rows, ha_rows *examined_rows);
80 ~RefOrNullIterator() override;
81
82 bool Init() override;
83 int Read() override;
84
85 private:
87 const bool m_use_order;
89 const double m_expected_rows;
92};
93
94/**
95 Like RefIterator, but used in situations where we're guaranteed to have
96 exactly zero or one rows for each reference (due to e.g. unique constraints).
97 It adds extra buffering to reduce the number of calls to the storage engine in
98 the case where many consecutive rows on the left side contain the same value.
99 */
100class EQRefIterator final : public TableRowIterator {
101 public:
102 // "examined_rows", if not nullptr, is incremented for each successful Read().
103 EQRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, ha_rows *examined_rows);
104
105 bool Init() override;
106 int Read() override;
107 void UnlockRow() override;
108
109 // Performance schema batch mode on EQRefIterator does not make any sense,
110 // since it (by definition) can never scan more than one row. Normally,
111 // we should not get this (for nested loop joins, PFS batch mode is not
112 // enabled if the innermost iterator is an EQRefIterator); however,
113 // we cannot assert(false), since it could happen if we only have
114 // a single table. Thus, just ignore the call should it happen.
115 void StartPSIBatchMode() override {}
116
117 private:
121};
122
123/**
124 An iterator that reads from a table where only a single row is known to be
125 matching, no matter what's on the left side, i.e., WHERE column=<const>.
126 */
127class ConstIterator final : public TableRowIterator {
128 public:
129 // "examined_rows", if not nullptr, is incremented for each successful Read().
130 ConstIterator(THD *thd, TABLE *table, TABLE_REF *table_ref,
131 ha_rows *examined_rows);
132
133 bool Init() override;
134 int Read() override;
135
136 /**
137 Rows from const tables are read once but potentially used
138 multiple times during execution of a query.
139 Ensure such rows are never unlocked during query execution.
140 */
141 void UnlockRow() override {}
142
143 private:
147};
148
149/** An iterator that does a search through a full-text index. */
151 public:
152 // "examined_rows", if not nullptr, is incremented for each successful Read().
154 Item_func_match *ft_func, bool use_order,
155 bool use_limit, ha_rows *examined_rows);
156 ~FullTextSearchIterator() override;
157
158 bool Init() override;
159 int Read() override;
160
161 private:
164 const bool m_use_order;
165 const bool m_use_limit;
167};
168
169/*
170 This is for QS_DYNAMIC_RANGE, i.e., "Range checked for each
171 record". The trace for the range analysis below this point will
172 be printed with different ranges for every record to the left of
173 this table in the join; the range optimizer can either select any
174 RowIterator or a full table scan, and any Read() is just proxied
175 over to that.
176
177 Note in particular that this means the range optimizer will be
178 executed anew on every single call to Init(), and modify the
179 query plan accordingly! It is not clear whether this is an actual
180 win in a typical query.
181 */
183 public:
184 // "examined_rows", if not nullptr, is incremented for each successful Read().
186 ha_rows *examined_rows);
187 ~DynamicRangeIterator() override;
188
189 bool Init() override;
190 int Read() override;
191
192 private:
194
195 // All quicks are allocated on this MEM_ROOT, which is cleared out
196 // between every invocation of the range optimizer.
198
200
201 /**
202 Used by optimizer tracing to decide whether or not dynamic range
203 analysis of this select has been traced already. If optimizer
204 trace option DYNAMIC_RANGE is enabled, range analysis will be
205 traced with different ranges for every record to the left of this
206 table in the join. If disabled, range analysis will only be traced
207 for the first range.
208 */
210
212
213 /**
214 Read set to be used when range optimizer picks covering index. This
215 read set is same as what filter_gcol_for_dynamic_range_scan()
216 sets up after filtering out the base columns for virtually generated
217 columns from the original table read set. By filtering out the base
218 columns, it avoids addition of unneeded columns for hash join/BKA.
219 */
221
222 /**
223 Read set to be used when range optimizer picks a non-covering index
224 or when table scan gets picked. It is setup by adding base columns
225 to the read set setup by filter_gcol_for_dynamic_range_scan().
226 add_virtual_gcol_base_cols() adds the base columns when initializing
227 this iterator.
228 */
230};
231
232/**
233 Read a table *assumed* to be included in execution of a pushed join.
234 This is the counterpart of RefIterator / EQRefIterator for child
235 tables in a pushed join. As the underlying handler interface for
236 pushed joins are the same for Ref / EQRef operations, we implement
237 both in the same PushedJoinRefIterator class.
238
239 In order to differentiate between a 'range' and 'single-row lookup'
240 in the DebugString(), the class takes a 'bool Unique' C'tor argument.
241 This also offers some optimizations in implementation of ::Read().
242
243 When the table access is performed as part of the pushed join,
244 all 'linked' child columns are prefetched together with the parent row.
245 The handler will then only format the row as required by MySQL and set
246 table status accordingly.
247
248 However, there may be situations where the prepared pushed join was not
249 executed as assumed. It is the responsibility of the handler to handle
250 these situation by letting @c ha_index_read_pushed() then effectively do a
251 plain old' index_read_map(..., HA_READ_KEY_EXACT);
252 */
254 public:
255 // "examined_rows", if not nullptr, is incremented for each successful Read().
256 PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
257 bool is_unique, ha_rows *examined_rows);
258
259 bool Init() override;
260 int Read() override;
261
262 private:
264 const bool m_use_order;
265 const bool m_is_unique;
268};
269
270/**
271 An iterator that switches between another iterator (typically a RefIterator
272 or similar) and a TableScanIterator.
273
274 This is used when predicates have been pushed down into an IN subquery
275 and then created ref accesses, but said predicates should not be checked for
276 a NULL value (so we need to revert to table scans). See
277 QEP_TAB::access_path() for a more thorough explanation.
278 */
279class AlternativeIterator final : public RowIterator {
280 public:
281 // Takes ownership of "source", and is responsible for
282 // calling Init() on it, but does not hold the memory.
285 unique_ptr_destroy_only<RowIterator> table_scan_iterator,
286 TABLE_REF *ref);
287
288 bool Init() override;
289
290 int Read() override { return m_iterator->Read(); }
291
292 void SetNullRowFlag(bool is_null_row) override {
293 // Init() may not have been called yet, so just forward to both iterators.
294 m_source_iterator->SetNullRowFlag(is_null_row);
295 m_table_scan_iterator->SetNullRowFlag(is_null_row);
296 }
297
298 void UnlockRow() override { m_iterator->UnlockRow(); }
299
300 private:
301 // If any of these are false during Init(), we are having a NULL IN ( ... ),
302 // and need to fall back to table scan. Extracted from m_ref.
303 std::vector<bool *> m_applicable_cond_guards;
304
305 // Points to either m_source_iterator or m_table_scan_iterator,
306 // depending on the value of applicable_cond_guards. Set up during Init().
308
309 // Points to the last iterator that was Init()-ed. Used to reset the handler
310 // when switching from one iterator to the other.
312
313 // The iterator we are normally reading records from (a RefIterator or
314 // similar).
316
317 // Our fallback iterator (possibly wrapped in a TimingIterator).
319
320 // The underlying table.
322
323 /**
324 A read set we can use when we fall back to table scans,
325 to get the base columns we need for virtual generated columns.
326 See add_virtual_gcol_base_cols().
327 */
329
330 /// The original value of table->read_set.
332};
333
334#endif // SQL_ITERATORS_REF_ROW_ITERATORS_H_
Row iterators that scan a single table without reference to other tables or iterators.
An iterator that switches between another iterator (typically a RefIterator or similar) and a TableSc...
Definition: ref_row_iterators.h:279
std::vector< bool * > m_applicable_cond_guards
Definition: ref_row_iterators.h:303
void UnlockRow() override
Definition: ref_row_iterators.h:298
RowIterator * m_last_iterator_inited
Definition: ref_row_iterators.h:311
int Read() override
Read a single row.
Definition: ref_row_iterators.h:290
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:808
void SetNullRowFlag(bool is_null_row) override
Mark the current row buffer as containing a NULL row or not, so that if you read from it and the flag...
Definition: ref_row_iterators.h:292
RowIterator * m_iterator
Definition: ref_row_iterators.h:307
TABLE *const m_table
Definition: ref_row_iterators.h:321
unique_ptr_destroy_only< RowIterator > m_source_iterator
Definition: ref_row_iterators.h:315
AlternativeIterator(THD *thd, TABLE *table, unique_ptr_destroy_only< RowIterator > source, unique_ptr_destroy_only< RowIterator > table_scan_iterator, TABLE_REF *ref)
Definition: ref_row_iterators.cc:788
MY_BITMAP * m_original_read_set
The original value of table->read_set.
Definition: ref_row_iterators.h:331
MY_BITMAP m_table_scan_read_set
A read set we can use when we fall back to table scans, to get the base columns we need for virtual g...
Definition: ref_row_iterators.h:328
unique_ptr_destroy_only< RowIterator > m_table_scan_iterator
Definition: ref_row_iterators.h:318
An iterator that reads from a table where only a single row is known to be matching,...
Definition: ref_row_iterators.h:127
bool m_first_record_since_init
Definition: ref_row_iterators.h:145
void UnlockRow() override
Rows from const tables are read once but potentially used multiple times during execution of a query.
Definition: ref_row_iterators.h:141
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:146
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:144
int Read() override
Read a constant table when there is at most one matching row, using an index lookup.
Definition: ref_row_iterators.cc:98
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:84
ConstIterator(THD *thd, TABLE *table, TABLE_REF *table_ref, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:78
Definition: ref_row_iterators.h:182
MY_BITMAP m_read_set_with_base_columns
Read set to be used when range optimizer picks a non-covering index or when table scan gets picked.
Definition: ref_row_iterators.h:229
MY_BITMAP * m_read_set_without_base_columns
Read set to be used when range optimizer picks covering index.
Definition: ref_row_iterators.h:220
QEP_TAB * m_qep_tab
Definition: ref_row_iterators.h:193
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:496
~DynamicRangeIterator() override
Definition: ref_row_iterators.cc:490
MEM_ROOT m_mem_root
Definition: ref_row_iterators.h:197
bool m_quick_traced_before
Used by optimizer tracing to decide whether or not dynamic range analysis of this select has been tra...
Definition: ref_row_iterators.h:209
unique_ptr_destroy_only< RowIterator > m_iterator
Definition: ref_row_iterators.h:199
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:606
DynamicRangeIterator(THD *thd, TABLE *table, QEP_TAB *qep_tab, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:477
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:211
Like RefIterator, but used in situations where we're guaranteed to have exactly zero or one rows for ...
Definition: ref_row_iterators.h:100
void UnlockRow() override
Since EQRefIterator may buffer a record, do not unlock it if it was not used in this invocation of EQ...
Definition: ref_row_iterators.cc:247
bool m_first_record_since_init
Definition: ref_row_iterators.h:119
int Read() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:164
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:118
bool Init() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:134
EQRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:111
void StartPSIBatchMode() override
Start performance schema batch mode, if supported (otherwise ignored).
Definition: ref_row_iterators.h:115
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:120
An iterator that does a search through a full-text index.
Definition: ref_row_iterators.h:150
const bool m_use_limit
Definition: ref_row_iterators.h:165
const bool m_use_order
Definition: ref_row_iterators.h:164
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:162
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:669
Item_func_match *const m_ft_func
Definition: ref_row_iterators.h:163
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:692
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:166
FullTextSearchIterator(THD *thd, TABLE *table, TABLE_REF *ref, Item_func_match *ft_func, bool use_order, bool use_limit, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:614
~FullTextSearchIterator() override
Definition: ref_row_iterators.cc:662
Definition: item_func.h:3481
Read a table assumed to be included in execution of a pushed join.
Definition: ref_row_iterators.h:253
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:277
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:263
PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, bool is_unique, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:252
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:262
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:267
const bool m_use_order
Definition: ref_row_iterators.h:264
const bool m_is_unique
Definition: ref_row_iterators.h:265
bool m_first_record_since_init
Definition: ref_row_iterators.h:266
Definition: sql_executor.h:259
For each record on the left side of a join (given in Init()), returns one or more matching rows from ...
Definition: ref_row_iterators.h:47
bool m_first_record_since_init
Definition: ref_row_iterators.h:67
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:66
RefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, double expected_rows, ha_rows *examined_rows)
Definition: ref_row_iterators.h:50
bool m_is_mvi_unique_filter_enabled
Definition: ref_row_iterators.h:68
const bool m_use_order
Definition: ref_row_iterators.h:64
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:339
const double m_expected_rows
Definition: ref_row_iterators.h:65
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:63
int Read() override
Read a single row.
~RefIterator() override
Like RefIterator, but after it's returned all its rows, will also search for rows that match NULL,...
Definition: ref_row_iterators.h:75
bool m_reading_first_row
Definition: ref_row_iterators.h:88
const double m_expected_rows
Definition: ref_row_iterators.h:89
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:733
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:90
const bool m_use_order
Definition: ref_row_iterators.h:87
RefOrNullIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, double expected_rows, ha_rows *examined_rows)
Reading of key with key reference and one part that may be NULL.
Definition: ref_row_iterators.cc:707
~RefOrNullIterator() override
Definition: ref_row_iterators.cc:781
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:716
bool m_is_mvi_unique_filter_enabled
Definition: ref_row_iterators.h:91
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:86
A context for reading through a single table using a chosen access method: index read,...
Definition: row_iterator.h:81
THD * thd() const
Definition: row_iterator.h:227
virtual void UnlockRow()=0
virtual int Read()=0
Read a single row.
For each client connection we create a separate thread with THD serving as a thread/connection descri...
Definition: sql_class.h:922
Definition: row_iterator.h:233
TABLE * table() const
Definition: row_iterator.h:245
This file follows Google coding style, except for the name MEM_ROOT (which is kept for historical rea...
std::unique_ptr< T, Destroy_only< T > > unique_ptr_destroy_only
std::unique_ptr, but only destroying.
Definition: my_alloc.h:488
my_off_t ha_rows
Definition: my_base.h:1139
Some integer typedefs for easier portability.
PT & ref(PT *tp)
Definition: tablespace_impl.cc:358
repeated Source source
Definition: replication_asynchronous_connection_failover.proto:41
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:82
Definition: my_bitmap.h:42
Definition: sql_opt_exec_shared.h:58
Definition: table.h:1396