MySQL 8.3.0
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, 2023, 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 Index_lookup;
40struct TABLE;
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().
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, Index_lookup *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().
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:
122};
123
124/**
125 An iterator that reads from a table where only a single row is known to be
126 matching, no matter what's on the left side, i.e., WHERE column=<const>.
127 */
128class ConstIterator final : public TableRowIterator {
129 public:
130 // "examined_rows", if not nullptr, is incremented for each successful Read().
132 ha_rows *examined_rows);
133
134 bool Init() override;
135 int Read() override;
136
137 /**
138 Rows from const tables are read once but potentially used
139 multiple times during execution of a query.
140 Ensure such rows are never unlocked during query execution.
141 */
142 void UnlockRow() override {}
143
144 private:
148};
149
150/** An iterator that does a search through a full-text index. */
152 public:
153 // "examined_rows", if not nullptr, is incremented for each successful Read().
155 Item_func_match *ft_func, bool use_order,
156 bool use_limit, ha_rows *examined_rows);
157 ~FullTextSearchIterator() override;
158
159 bool Init() override;
160 int Read() override;
161
162 private:
165 const bool m_use_order;
166 const bool m_use_limit;
168};
169
170/*
171 This is for QS_DYNAMIC_RANGE, i.e., "Range checked for each
172 record". The trace for the range analysis below this point will
173 be printed with different ranges for every record to the left of
174 this table in the join; the range optimizer can either select any
175 RowIterator or a full table scan, and any Read() is just proxied
176 over to that.
177
178 Note in particular that this means the range optimizer will be
179 executed anew on every single call to Init(), and modify the
180 query plan accordingly! It is not clear whether this is an actual
181 win in a typical query.
182 */
184 public:
185 // "examined_rows", if not nullptr, is incremented for each successful Read().
187 ha_rows *examined_rows);
188 ~DynamicRangeIterator() override;
189
190 bool Init() override;
191 int Read() override;
192
193 private:
195
196 // All quicks are allocated on this MEM_ROOT, which is cleared out
197 // between every invocation of the range optimizer.
199
201
202 /**
203 Used by optimizer tracing to decide whether or not dynamic range
204 analysis of this select has been traced already. If optimizer
205 trace option DYNAMIC_RANGE is enabled, range analysis will be
206 traced with different ranges for every record to the left of this
207 table in the join. If disabled, range analysis will only be traced
208 for the first range.
209 */
211
213};
214
215/**
216 Read a table *assumed* to be included in execution of a pushed join.
217 This is the counterpart of RefIterator / EQRefIterator for child
218 tables in a pushed join. As the underlying handler interface for
219 pushed joins are the same for Ref / EQRef operations, we implement
220 both in the same PushedJoinRefIterator class.
221
222 In order to differentiate between a 'range' and 'single-row lookup'
223 in the DebugString(), the class takes a 'bool Unique' C'tor argument.
224 This also offers some optimizations in implementation of ::Read().
225
226 When the table access is performed as part of the pushed join,
227 all 'linked' child columns are prefetched together with the parent row.
228 The handler will then only format the row as required by MySQL and set
229 table status accordingly.
230
231 However, there may be situations where the prepared pushed join was not
232 executed as assumed. It is the responsibility of the handler to handle
233 these situation by letting @c ha_index_read_pushed() then effectively do a
234 plain old' index_read_map(..., HA_READ_KEY_EXACT);
235 */
237 public:
238 // "examined_rows", if not nullptr, is incremented for each successful Read().
240 bool use_order, bool is_unique, ha_rows *examined_rows);
241
242 bool Init() override;
243 int Read() override;
244
245 private:
247 const bool m_use_order;
248 const bool m_is_unique;
251};
252
253/**
254 An iterator that switches between another iterator (typically a RefIterator
255 or similar) and a TableScanIterator.
256
257 This is used when predicates have been pushed down into an IN subquery
258 and then created ref accesses, but said predicates should not be checked for
259 a NULL value (so we need to revert to table scans). See
260 QEP_TAB::access_path() for a more thorough explanation.
261 */
262class AlternativeIterator final : public RowIterator {
263 public:
264 // Takes ownership of "source", and is responsible for
265 // calling Init() on it, but does not hold the memory.
268 unique_ptr_destroy_only<RowIterator> table_scan_iterator,
270
271 bool Init() override;
272
273 int Read() override { return m_iterator->Read(); }
274
275 void SetNullRowFlag(bool is_null_row) override {
276 // Init() may not have been called yet, so just forward to both iterators.
277 m_source_iterator->SetNullRowFlag(is_null_row);
278 m_table_scan_iterator->SetNullRowFlag(is_null_row);
279 }
280
281 void UnlockRow() override { m_iterator->UnlockRow(); }
282
283 private:
284 // If any of these are false during Init(), we are having a NULL IN ( ... ),
285 // and need to fall back to table scan. Extracted from m_ref.
286 std::vector<bool *> m_applicable_cond_guards;
287
288 // Points to either m_source_iterator or m_table_scan_iterator,
289 // depending on the value of applicable_cond_guards. Set up during Init().
291
292 // Points to the last iterator that was Init()-ed. Used to reset the handler
293 // when switching from one iterator to the other.
295
296 // The iterator we are normally reading records from (a RefIterator or
297 // similar).
299
300 // Our fallback iterator (possibly wrapped in a TimingIterator).
302
303 // The underlying table.
305};
306
307#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:262
AlternativeIterator(THD *thd, TABLE *table, unique_ptr_destroy_only< RowIterator > source, unique_ptr_destroy_only< RowIterator > table_scan_iterator, Index_lookup *ref)
Definition: ref_row_iterators.cc:768
std::vector< bool * > m_applicable_cond_guards
Definition: ref_row_iterators.h:286
void UnlockRow() override
Definition: ref_row_iterators.h:281
RowIterator * m_last_iterator_inited
Definition: ref_row_iterators.h:294
int Read() override
Read a single row.
Definition: ref_row_iterators.h:273
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:785
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:275
RowIterator * m_iterator
Definition: ref_row_iterators.h:290
TABLE *const m_table
Definition: ref_row_iterators.h:304
unique_ptr_destroy_only< RowIterator > m_source_iterator
Definition: ref_row_iterators.h:298
unique_ptr_destroy_only< RowIterator > m_table_scan_iterator
Definition: ref_row_iterators.h:301
An iterator that reads from a table where only a single row is known to be matching,...
Definition: ref_row_iterators.h:128
bool m_first_record_since_init
Definition: ref_row_iterators.h:146
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:142
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:147
Index_lookup *const m_ref
Definition: ref_row_iterators.h:145
ConstIterator(THD *thd, TABLE *table, Index_lookup *table_ref, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:76
int Read() override
Read a constant table when there is at most one matching row, using an index lookup.
Definition: ref_row_iterators.cc:96
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:82
Definition: ref_row_iterators.h:183
QEP_TAB * m_qep_tab
Definition: ref_row_iterators.h:194
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:492
~DynamicRangeIterator() override
Definition: ref_row_iterators.cc:484
MEM_ROOT m_mem_root
Definition: ref_row_iterators.h:198
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:210
unique_ptr_destroy_only< RowIterator > m_iterator
Definition: ref_row_iterators.h:200
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:586
DynamicRangeIterator(THD *thd, TABLE *table, QEP_TAB *qep_tab, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:475
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:212
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:245
bool m_first_record_since_init
Definition: ref_row_iterators.h:120
int Read() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:162
bool Init() override
Read row using unique key: eq_ref access method implementation.
Definition: ref_row_iterators.cc:132
Index_lookup *const m_ref
Definition: ref_row_iterators.h:119
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:121
EQRefIterator(THD *thd, TABLE *table, Index_lookup *ref, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:109
An iterator that does a search through a full-text index.
Definition: ref_row_iterators.h:151
Index_lookup *const m_ref
Definition: ref_row_iterators.h:163
const bool m_use_limit
Definition: ref_row_iterators.h:166
const bool m_use_order
Definition: ref_row_iterators.h:165
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:649
Item_func_match *const m_ft_func
Definition: ref_row_iterators.h:164
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:672
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:167
FullTextSearchIterator(THD *thd, TABLE *table, Index_lookup *ref, Item_func_match *ft_func, bool use_order, bool use_limit, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:594
~FullTextSearchIterator() override
Definition: ref_row_iterators.cc:642
Definition: item_func.h:3455
Read a table assumed to be included in execution of a pushed join.
Definition: ref_row_iterators.h:236
int Read() override
Read a single row.
Definition: ref_row_iterators.cc:275
Index_lookup *const m_ref
Definition: ref_row_iterators.h:246
PushedJoinRefIterator(THD *thd, TABLE *table, Index_lookup *ref, bool use_order, bool is_unique, ha_rows *examined_rows)
Definition: ref_row_iterators.cc:250
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:260
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:250
const bool m_use_order
Definition: ref_row_iterators.h:247
const bool m_is_unique
Definition: ref_row_iterators.h:248
bool m_first_record_since_init
Definition: ref_row_iterators.h:249
Definition: sql_executor.h:253
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
RefIterator(THD *thd, TABLE *table, Index_lookup *ref, bool use_order, double expected_rows, ha_rows *examined_rows)
Definition: ref_row_iterators.h:50
bool m_first_record_since_init
Definition: ref_row_iterators.h:67
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:66
Index_lookup *const m_ref
Definition: ref_row_iterators.h:63
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:337
const double m_expected_rows
Definition: ref_row_iterators.h:65
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:713
Index_lookup *const m_ref
Definition: ref_row_iterators.h:86
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:90
const bool m_use_order
Definition: ref_row_iterators.h:87
~RefOrNullIterator() override
Definition: ref_row_iterators.cc:761
bool Init() override
Initialize or reinitialize the iterator.
Definition: ref_row_iterators.cc:696
bool m_is_mvi_unique_filter_enabled
Definition: ref_row_iterators.h:91
RefOrNullIterator(THD *thd, TABLE *table, Index_lookup *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:687
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_lexer_thd.h:35
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:476
my_off_t ha_rows
Definition: my_base.h:1140
Some integer typedefs for easier portability.
static PFS_engine_table_share_proxy table
Definition: pfs.cc:60
PT & ref(PT *tp)
Definition: tablespace_impl.cc:358
repeated Source source
Definition: replication_asynchronous_connection_failover.proto:41
Structure used for index-based lookups.
Definition: sql_opt_exec_shared.h:66
The MEM_ROOT is a simple arena, where allocations are carved out of larger blocks.
Definition: my_alloc.h:82
Definition: table.h:1403