MySQL 8.0.29
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, bool use_order,
104 ha_rows *examined_rows);
105
106 bool Init() override;
107 int Read() override;
108 void UnlockRow() override;
109
110 // Performance schema batch mode on EQRefIterator does not make any sense,
111 // since it (by definition) can never scan more than one row. Normally,
112 // we should not get this (for nested loop joins, PFS batch mode is not
113 // enabled if the innermost iterator is an EQRefIterator); however,
114 // we cannot assert(false), since it could happen if we only have
115 // a single table. Thus, just ignore the call should it happen.
116 void StartPSIBatchMode() override {}
117
118 private:
120 const bool m_use_order;
123};
124
125/**
126 An iterator that reads from a table where only a single row is known to be
127 matching, no matter what's on the left side, i.e., WHERE column=<const>.
128 */
129class ConstIterator final : public TableRowIterator {
130 public:
131 // "examined_rows", if not nullptr, is incremented for each successful Read().
132 ConstIterator(THD *thd, TABLE *table, TABLE_REF *table_ref,
133 ha_rows *examined_rows);
134
135 bool Init() override;
136 int Read() override;
137
138 /**
139 Rows from const tables are read once but potentially used
140 multiple times during execution of a query.
141 Ensure such rows are never unlocked during query execution.
142 */
143 void UnlockRow() override {}
144
145 private:
149};
150
151/** An iterator that does a search through a full-text index. */
153 public:
154 // "examined_rows", if not nullptr, is incremented for each successful Read().
156 Item_func_match *ft_func, bool use_order,
157 bool use_limit, ha_rows *examined_rows);
158 ~FullTextSearchIterator() override;
159
160 bool Init() override;
161 int Read() override;
162
163 private:
166 const bool m_use_order;
167 const bool m_use_limit;
169};
170
171/*
172 This is for QS_DYNAMIC_RANGE, i.e., "Range checked for each
173 record". The trace for the range analysis below this point will
174 be printed with different ranges for every record to the left of
175 this table in the join; the range optimizer can either select any
176 RowIterator or a full table scan, and any Read() is just proxied
177 over to that.
178
179 Note in particular that this means the range optimizer will be
180 executed anew on every single call to Init(), and modify the
181 query plan accordingly! It is not clear whether this is an actual
182 win in a typical query.
183 */
185 public:
186 // "examined_rows", if not nullptr, is incremented for each successful Read().
188 ha_rows *examined_rows);
189 ~DynamicRangeIterator() override;
190
191 bool Init() override;
192 int Read() override;
193
194 private:
196
197 // All quicks are allocated on this MEM_ROOT, which is cleared out
198 // between every invocation of the range optimizer.
200
202
203 /**
204 Used by optimizer tracing to decide whether or not dynamic range
205 analysis of this select has been traced already. If optimizer
206 trace option DYNAMIC_RANGE is enabled, range analysis will be
207 traced with different ranges for every record to the left of this
208 table in the join. If disabled, range analysis will only be traced
209 for the first range.
210 */
212
214
215 /**
216 Read set to be used when range optimizer picks covering index. This
217 read set is same as what filter_gcol_for_dynamic_range_scan()
218 sets up after filtering out the base columns for virtually generated
219 columns from the original table read set. By filtering out the base
220 columns, it avoids addition of unneeded columns for hash join/BKA.
221 */
223
224 /**
225 Read set to be used when range optimizer picks a non-covering index
226 or when table scan gets picked. It is setup by adding base columns
227 to the read set setup by filter_gcol_for_dynamic_range_scan().
228 add_virtual_gcol_base_cols() adds the base columns when initializing
229 this iterator.
230 */
232};
233
234/**
235 Read a table *assumed* to be included in execution of a pushed join.
236 This is the counterpart of RefIterator / EQRefIterator for child
237 tables in a pushed join. As the underlying handler interface for
238 pushed joins are the same for Ref / EQRef operations, we implement
239 both in the same PushedJoinRefIterator class.
240
241 In order to differentiate between a 'range' and 'single-row lookup'
242 in the DebugString(), the class takes a 'bool Unique' C'tor argument.
243 This also offers some optimizations in implementation of ::Read().
244
245 When the table access is performed as part of the pushed join,
246 all 'linked' child colums are prefetched together with the parent row.
247 The handler will then only format the row as required by MySQL and set
248 table status accordingly.
249
250 However, there may be situations where the prepared pushed join was not
251 executed as assumed. It is the responsibility of the handler to handle
252 these situation by letting @c ha_index_read_pushed() then effectively do a
253 plain old' index_read_map(..., HA_READ_KEY_EXACT);
254 */
256 public:
257 // "examined_rows", if not nullptr, is incremented for each successful Read().
258 PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
259 bool is_unique, ha_rows *examined_rows);
260
261 bool Init() override;
262 int Read() override;
263
264 private:
266 const bool m_use_order;
267 const bool m_is_unique;
270};
271
272/**
273 An iterator that switches between another iterator (typically a RefIterator
274 or similar) and a TableScanIterator.
275
276 This is used when predicates have been pushed down into an IN subquery
277 and then created ref accesses, but said predicates should not be checked for
278 a NULL value (so we need to revert to table scans). See
279 QEP_TAB::access_path() for a more thorough explanation.
280 */
281class AlternativeIterator final : public RowIterator {
282 public:
283 // Takes ownership of "source", and is responsible for
284 // calling Init() on it, but does not hold the memory.
287 unique_ptr_destroy_only<RowIterator> table_scan_iterator,
288 TABLE_REF *ref);
289
290 bool Init() override;
291
292 int Read() override { return m_iterator->Read(); }
293
294 void SetNullRowFlag(bool is_null_row) override {
295 // Init() may not have been called yet, so just forward to both iterators.
296 m_source_iterator->SetNullRowFlag(is_null_row);
297 m_table_scan_iterator->SetNullRowFlag(is_null_row);
298 }
299
300 void UnlockRow() override { m_iterator->UnlockRow(); }
301
302 private:
303 // If any of these are false during Init(), we are having a NULL IN ( ... ),
304 // and need to fall back to table scan. Extracted from m_ref.
305 std::vector<bool *> m_applicable_cond_guards;
306
307 // Points to either m_source_iterator or m_table_scan_iterator,
308 // depending on the value of applicable_cond_guards. Set up during Init().
310
311 // Points to the last iterator that was Init()-ed. Used to reset the handler
312 // when switching from one iterator to the other.
314
315 // The iterator we are normally reading records from (a RefIterator or
316 // similar).
318
319 // Our fallback iterator (possibly wrapped in a TimingIterator).
321
322 // The underlying table.
324
325 /**
326 A read set we can use when we fall back to table scans,
327 to get the base columns we need for virtual generated columns.
328 See add_virtual_gcol_base_cols().
329 */
331
332 /// The original value of table->read_set.
334};
335
336#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:281
std::vector< bool * > m_applicable_cond_guards
Definition: ref_row_iterators.h:305
void UnlockRow() override
Definition: ref_row_iterators.h:300
RowIterator * m_last_iterator_inited
Definition: ref_row_iterators.h:313
int Read() override
Read a single row.
Definition: ref_row_iterators.h:292
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:810
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:294
RowIterator * m_iterator
Definition: ref_row_iterators.h:309
TABLE *const m_table
Definition: ref_row_iterators.h:323
unique_ptr_destroy_only< RowIterator > m_source_iterator
Definition: ref_row_iterators.h:317
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:790
MY_BITMAP * m_original_read_set
The original value of table->read_set.
Definition: ref_row_iterators.h:333
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:330
unique_ptr_destroy_only< RowIterator > m_table_scan_iterator
Definition: ref_row_iterators.h:320
An iterator that reads from a table where only a single row is known to be matching,...
Definition: ref_row_iterators.h:129
bool m_first_record_since_init
Definition: ref_row_iterators.h:147
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:143
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:148
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:146
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:184
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:231
MY_BITMAP * m_read_set_without_base_columns
Read set to be used when range optimizer picks covering index.
Definition: ref_row_iterators.h:222
QEP_TAB * m_qep_tab
Definition: ref_row_iterators.h:195
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:498
~DynamicRangeIterator() override
Definition: ref_row_iterators.cc:492
MEM_ROOT m_mem_root
Definition: ref_row_iterators.h:199
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:211
unique_ptr_destroy_only< RowIterator > m_iterator
Definition: ref_row_iterators.h:201
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:608
DynamicRangeIterator(THD *thd, TABLE *table, QEP_TAB *qep_tab, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:479
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:213
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:249
bool m_first_record_since_init
Definition: ref_row_iterators.h:121
const bool m_use_order
Definition: ref_row_iterators.h:120
int Read() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:166
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:119
bool Init() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:135
EQRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, 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:116
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:122
An iterator that does a search through a full-text index.
Definition: ref_row_iterators.h:152
const bool m_use_limit
Definition: ref_row_iterators.h:167
const bool m_use_order
Definition: ref_row_iterators.h:166
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:164
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:671
Item_func_match *const m_ft_func
Definition: ref_row_iterators.h:165
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:694
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:168
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:616
~FullTextSearchIterator() override
Definition: ref_row_iterators.cc:664
Definition: item_func.h:3447
Read a table assumed to be included in execution of a pushed join.
Definition: ref_row_iterators.h:255
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:279
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:265
PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, bool is_unique, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:254
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:264
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:269
const bool m_use_order
Definition: ref_row_iterators.h:266
const bool m_is_unique
Definition: ref_row_iterators.h:267
bool m_first_record_since_init
Definition: ref_row_iterators.h:268
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:341
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:735
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:709
~RefOrNullIterator() override
Definition: ref_row_iterators.cc:783
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:718
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:60
THD * thd() const
Definition: row_iterator.h:195
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:945
Definition: row_iterator.h:201
TABLE * table() const
Definition: row_iterator.h:213
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:1394