MySQL  8.0.27
Source Code Documentation
ref_row_iterators.h
Go to the documentation of this file.
1 #ifndef SQL_REF_ROW_ITERATORS_H
2 #define SQL_REF_ROW_ITERATORS_H
3 
4 /* Copyright (c) 2018, 2021, 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"
33 #include "sql/row_iterator.h"
34 #include "sql/sql_sort.h"
35 
36 class Item_func_match;
37 class QEP_TAB;
38 class THD;
39 struct TABLE;
40 struct 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  */
46 template <bool Reverse>
47 class 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 
58  bool Init() override;
59  int Read() override;
60 
61  private:
62  TABLE_REF *const m_ref;
63  const bool m_use_order;
64  const double m_expected_rows;
67 };
68 
69 /**
70  Like RefIterator, but after it's returned all its rows, will also search for
71  rows that match NULL, i.e., WHERE column=<ref> OR column IS NULL.
72  */
73 class RefOrNullIterator final : public TableRowIterator {
74  public:
75  // "examined_rows", if not nullptr, is incremented for each successful Read().
76  RefOrNullIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
77  double expected_rows, ha_rows *examined_rows);
78 
79  bool Init() override;
80  int Read() override;
81 
82  private:
83  TABLE_REF *const m_ref;
84  const bool m_use_order;
86  const double m_expected_rows;
88 };
89 
90 /**
91  Like RefIterator, but used in situations where we're guaranteed to have
92  exactly zero or one rows for each reference (due to e.g. unique constraints).
93  It adds extra buffering to reduce the number of calls to the storage engine in
94  the case where many consecutive rows on the left side contain the same value.
95  */
96 class EQRefIterator final : public TableRowIterator {
97  public:
98  // "examined_rows", if not nullptr, is incremented for each successful Read().
99  EQRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
100  ha_rows *examined_rows);
101 
102  bool Init() override;
103  int Read() override;
104  void UnlockRow() override;
105 
106  // Performance schema batch mode on EQRefIterator does not make any sense,
107  // since it (by definition) can never scan more than one row. Normally,
108  // we should not get this (for nested loop joins, PFS batch mode is not
109  // enabled if the innermost iterator is an EQRefIterator); however,
110  // we cannot assert(false), since it could happen if we only have
111  // a single table. Thus, just ignore the call should it happen.
112  void StartPSIBatchMode() override {}
113 
114  private:
115  TABLE_REF *const m_ref;
116  const bool m_use_order;
119 };
120 
121 /**
122  An iterator that reads from a table where only a single row is known to be
123  matching, no matter what's on the left side, i.e., WHERE column=<const>.
124  */
125 class ConstIterator final : public TableRowIterator {
126  public:
127  // "examined_rows", if not nullptr, is incremented for each successful Read().
128  ConstIterator(THD *thd, TABLE *table, TABLE_REF *table_ref,
129  ha_rows *examined_rows);
130 
131  bool Init() override;
132  int Read() override;
133 
134  /**
135  Rows from const tables are read once but potentially used
136  multiple times during execution of a query.
137  Ensure such rows are never unlocked during query execution.
138  */
139  void UnlockRow() override {}
140 
141  private:
142  TABLE_REF *const m_ref;
145 };
146 
147 /** An iterator that does a search through a full-text index. */
149  public:
150  // "examined_rows", if not nullptr, is incremented for each successful Read().
152  Item_func_match *ft_func, bool use_order,
153  bool use_limit, ha_rows *examined_rows);
154  ~FullTextSearchIterator() override;
155 
156  bool Init() override;
157  int Read() override;
158 
159  private:
160  TABLE_REF *const m_ref;
162  const bool m_use_order;
163  const bool m_use_limit;
165 };
166 
167 /*
168  This is for QS_DYNAMIC_RANGE, i.e., "Range checked for each
169  record". The trace for the range analysis below this point will
170  be printed with different ranges for every record to the left of
171  this table in the join; the range optimizer can either select any
172  QUICK_SELECT_I (aka IndexRangeScanIterator) or a full table
173  scan, and any Read() is just proxied over to that.
174 
175  Note in particular that this means the range optimizer will be
176  executed anew on every single call to Init(), and modify the
177  query plan accordingly! It is not clear whether this is an actual
178  win in a typical query.
179  */
181  public:
182  // "examined_rows", if not nullptr, is incremented for each successful Read().
184  ha_rows *examined_rows);
185  ~DynamicRangeIterator() override;
186 
187  bool Init() override;
188  int Read() override;
189 
190  private:
192 
193  // All quicks are allocated on this MEM_ROOT, which is cleared out
194  // between every invocation of the range optimizer.
196 
198 
199  /**
200  Used by optimizer tracing to decide whether or not dynamic range
201  analysis of this select has been traced already. If optimizer
202  trace option DYNAMIC_RANGE is enabled, range analysis will be
203  traced with different ranges for every record to the left of this
204  table in the join. If disabled, range analysis will only be traced
205  for the first range.
206  */
207  bool m_quick_traced_before = false;
208 
210 
211  /**
212  Read set to be used when range optimizer picks covering index. This
213  read set is same as what filter_gcol_for_dynamic_ranage_scan()
214  sets up after filtering out the base columns for virtually generated
215  columns from the original table read set. By filtering out the base
216  columns, it avoids addition of unneeded columns for hash join/BKA.
217  */
219 
220  /**
221  Read set to be used when range optimizer picks a non-covering index
222  or when table scan gets picked. It is setup by adding base columns
223  to the read set setup by filter_gcol_for_dynamic_range_scan().
224  add_virtual_gcol_base_cols() adds the base columns when initializing
225  this iterator.
226  */
228 };
229 
230 /**
231  Read a table *assumed* to be included in execution of a pushed join.
232  This is the counterpart of RefIterator / EQRefIterator for child
233  tables in a pushed join. As the underlying handler interface for
234  pushed joins are the same for Ref / EQRef operations, we implement
235  both in the same PushedJoinRefIterator class.
236 
237  In order to differentiate between a 'range' and 'single-row lookup'
238  in the DebugString(), the class takes a 'bool Unique' C'tor argument.
239  This also offers some optimizations in implementation of ::Read().
240 
241  When the table access is performed as part of the pushed join,
242  all 'linked' child colums are prefetched together with the parent row.
243  The handler will then only format the row as required by MySQL and set
244  table status accordingly.
245 
246  However, there may be situations where the prepared pushed join was not
247  executed as assumed. It is the responsibility of the handler to handle
248  these situation by letting @c ha_index_read_pushed() then effectively do a
249  plain old' index_read_map(..., HA_READ_KEY_EXACT);
250  */
252  public:
253  // "examined_rows", if not nullptr, is incremented for each successful Read().
254  PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order,
255  bool is_unique, ha_rows *examined_rows);
256 
257  bool Init() override;
258  int Read() override;
259 
260  private:
261  TABLE_REF *const m_ref;
262  const bool m_use_order;
263  const bool m_is_unique;
266 };
267 
268 /**
269  An iterator that switches between another iterator (typically a RefIterator
270  or similar) and a TableScanIterator.
271 
272  This is used when predicates have been pushed down into an IN subquery
273  and then created ref accesses, but said predicates should not be checked for
274  a NULL value (so we need to revert to table scans). See
275  QEP_TAB::pick_table_access_method() for a more thorough explanation.
276  */
277 class AlternativeIterator final : public RowIterator {
278  public:
279  // Takes ownership of "source", and is responsible for
280  // calling Init() on it, but does not hold the memory.
281  AlternativeIterator(THD *thd, TABLE *table,
283  unique_ptr_destroy_only<RowIterator> table_scan_iterator,
284  TABLE_REF *ref);
285 
286  bool Init() override;
287 
288  int Read() override { return m_iterator->Read(); }
289 
290  void SetNullRowFlag(bool is_null_row) override {
291  // Init() may not have been called yet, so just forward to both iterators.
292  m_source_iterator->SetNullRowFlag(is_null_row);
293  m_table_scan_iterator->SetNullRowFlag(is_null_row);
294  }
295 
296  void UnlockRow() override { m_iterator->UnlockRow(); }
297 
298  private:
299  // If any of these are false during Init(), we are having a NULL IN ( ... ),
300  // and need to fall back to table scan. Extracted from m_ref.
301  std::vector<bool *> m_applicable_cond_guards;
302 
303  // Points to either m_source_iterator or m_table_scan_iterator,
304  // depending on the value of applicable_cond_guards. Set up during Init().
306 
307  // Points to the last iterator that was Init()-ed. Used to reset the handler
308  // when switching from one iterator to the other.
310 
311  // The iterator we are normally reading records from (a RefIterator or
312  // similar).
314 
315  // Our fallback iterator (possibly wrapped in a TimingIterator).
317 
318  // The underlying table.
319  TABLE *const m_table;
320 
321  /**
322  A read set we can use when we fall back to table scans,
323  to get the base columns we need for virtual generated columns.
324  See add_virtual_gcol_base_cols().
325  */
327 
328  /// The original value of table->read_set.
330 };
331 
332 #endif // SQL_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:277
std::vector< bool * > m_applicable_cond_guards
Definition: ref_row_iterators.h:301
void UnlockRow() override
Definition: ref_row_iterators.h:296
RowIterator * m_last_iterator_inited
Definition: ref_row_iterators.h:309
int Read() override
Read a single row.
Definition: ref_row_iterators.h:288
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:290
RowIterator * m_iterator
Definition: ref_row_iterators.h:305
TABLE *const m_table
Definition: ref_row_iterators.h:319
unique_ptr_destroy_only< RowIterator > m_source_iterator
Definition: ref_row_iterators.h:313
MY_BITMAP * m_original_read_set
The original value of table->read_set.
Definition: ref_row_iterators.h:329
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:326
unique_ptr_destroy_only< RowIterator > m_table_scan_iterator
Definition: ref_row_iterators.h:316
An iterator that reads from a table where only a single row is known to be matching,...
Definition: ref_row_iterators.h:125
bool m_first_record_since_init
Definition: ref_row_iterators.h:143
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:139
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:144
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:142
Definition: ref_row_iterators.h:180
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:227
MY_BITMAP * m_read_set_without_base_columns
Read set to be used when range optimizer picks covering index.
Definition: ref_row_iterators.h:218
QEP_TAB * m_qep_tab
Definition: ref_row_iterators.h:191
MEM_ROOT m_mem_root
Definition: ref_row_iterators.h:195
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:207
unique_ptr_destroy_only< RowIterator > m_iterator
Definition: ref_row_iterators.h:197
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:209
Like RefIterator, but used in situations where we're guaranteed to have exactly zero or one rows for ...
Definition: ref_row_iterators.h:96
bool m_first_record_since_init
Definition: ref_row_iterators.h:117
const bool m_use_order
Definition: ref_row_iterators.h:116
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:115
void StartPSIBatchMode() override
Start performance schema batch mode, if supported (otherwise ignored).
Definition: ref_row_iterators.h:112
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:118
An iterator that does a search through a full-text index.
Definition: ref_row_iterators.h:148
const bool m_use_limit
Definition: ref_row_iterators.h:163
const bool m_use_order
Definition: ref_row_iterators.h:162
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:160
Item_func_match *const m_ft_func
Definition: ref_row_iterators.h:161
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:164
Definition: item_func.h:3444
Read a table assumed to be included in execution of a pushed join.
Definition: ref_row_iterators.h:251
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:261
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:265
const bool m_use_order
Definition: ref_row_iterators.h:262
const bool m_is_unique
Definition: ref_row_iterators.h:263
bool m_first_record_since_init
Definition: ref_row_iterators.h:264
Definition: sql_executor.h:256
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:66
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:65
RefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, double expected_rows, ha_rows *examined_rows)
Definition: ref_row_iterators.h:50
const bool m_use_order
Definition: ref_row_iterators.h:63
const double m_expected_rows
Definition: ref_row_iterators.h:64
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:62
int Read() override
Read a single row.
Like RefIterator, but after it's returned all its rows, will also search for rows that match NULL,...
Definition: ref_row_iterators.h:73
bool m_reading_first_row
Definition: ref_row_iterators.h:85
const double m_expected_rows
Definition: ref_row_iterators.h:86
ha_rows *const m_examined_rows
Definition: ref_row_iterators.h:87
const bool m_use_order
Definition: ref_row_iterators.h:84
TABLE_REF *const m_ref
Definition: ref_row_iterators.h:83
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:190
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:821
Definition: row_iterator.h:196
TABLE * table() const
Definition: row_iterator.h:208
void UnlockRow() override
Since EQRefIterator may buffer a record, do not unlock it if it was not used in this invocation of EQ...
Definition: sql_executor.cc:3732
int Read() override
Read a single row.
Definition: sql_executor.cc:3762
int Read() override
Read row using unique key: eq_ref access method implementation.
Definition: sql_executor.cc:3649
int Read() override
Read a single row.
Definition: sql_executor.cc:4192
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: sql_executor.cc:4173
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:3942
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:4182
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:4139
PushedJoinRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, bool is_unique, ha_rows *examined_rows)
Definition: sql_executor.cc:3737
~DynamicRangeIterator() override
Definition: sql_executor.cc:3936
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:4257
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:3804
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:3747
bool Init() override
Read row using unique key: eq_ref access method implementation.
Definition: sql_executor.cc:3618
int Read() override
Read a single row.
Definition: sql_executor.cc:4158
EQRefIterator(THD *thd, TABLE *table, TABLE_REF *ref, bool use_order, ha_rows *examined_rows)
Definition: sql_executor.cc:3594
int Read() override
Read a constant table when there is at most one matching row, using an index lookup.
Definition: sql_executor.cc:3525
AlternativeIterator(THD *thd, TABLE *table, unique_ptr_destroy_only< RowIterator > source, unique_ptr_destroy_only< RowIterator > table_scan_iterator, TABLE_REF *ref)
Definition: sql_executor.cc:4237
bool Init() override
Initialize or reinitialize the iterator.
Definition: sql_executor.cc:3511
ConstIterator(THD *thd, TABLE *table, TABLE_REF *table_ref, ha_rows *examined_rows)
Definition: sql_executor.cc:3505
FullTextSearchIterator(THD *thd, TABLE *table, TABLE_REF *ref, Item_func_match *ft_func, bool use_order, bool use_limit, ha_rows *examined_rows)
Definition: sql_executor.cc:4084
int Read() override
Read a single row.
Definition: sql_executor.cc:4045
~FullTextSearchIterator() override
Definition: sql_executor.cc:4132
DynamicRangeIterator(THD *thd, TABLE *table, QEP_TAB *qep_tab, ha_rows *examined_rows)
Definition: sql_executor.cc:3923
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:464
my_off_t ha_rows
Definition: my_base.h:1138
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:78
Definition: my_bitmap.h:41
Definition: sql_opt_exec_shared.h:59
Definition: table.h:1394