MySQL 8.3.0
Source Code Documentation
Go to the documentation of this file.
1#ifndef SQL_PACK_ROWS_H_
2#define SQL_PACK_ROWS_H_
4/* Copyright (c) 2020, 2023, Oracle and/or its affiliates.
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.
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.
17 This program is distributed in the hope that it will be useful,
18 but WITHOUT ANY WARRANTY; without even the implied warranty of
20 GNU General Public License, version 2.0, for more details.
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 */
27 @file
29 Generic routines for packing rows (possibly from multiple tables
30 at the same time) into strings, and then back again. Used for (at least)
31 hash join, BKA, and streaming aggregation.
32 */
34#include <assert.h>
35#include <stddef.h>
36#include <string.h>
38#include "field_types.h"
39#include "my_bitmap.h"
40#include "my_compiler.h"
42#include "my_inttypes.h"
43#include "my_table_map.h"
45#include "prealloced_array.h"
46#include "sql/field.h"
47#include "sql/handler.h"
48#include "sql/table.h"
49#include "template_utils.h"
51class JOIN;
52class String;
54// Names such as “Column” and “Table” are a tad too generic for the global
55// namespace.
56namespace pack_rows {
58/// A class that represents a field, which also holds a cached value of the
59/// field's data type.
60struct Column {
61 explicit Column(Field *field);
62 Field *const field;
64 // The field type is used frequently, and caching it gains around 30% in some
65 // of our microbenchmarks.
69/// This struct is primarily used for holding the extracted columns in a hash
70/// join or BKA join, or the input columns in a streaming aggregation operation.
71/// When the join or aggregate iterator is constructed, we extract the columns
72/// that are needed to satisfy the SQL query.
73struct Table {
74 explicit Table(TABLE *table_arg);
78 // Whether to copy the NULL flags or not.
79 bool copy_null_flags{false};
81 // Whether to store the actual contents of NULL-complemented rows.
82 // This is needed by AggregateIterator in order to be able to
83 // restore the exact contents of the record buffer for a table
84 // accessed with EQRefIterator, so that the cache in EQRefIterator
85 // is not disturbed.
89/// A structure that contains a list of input tables for a hash join operation,
90/// BKA join operation or a streaming aggregation operation, and some
91/// pre-computed properties for the tables.
93 public:
94 TableCollection() = default;
98 table_map tables_to_store_contents_of_null_rows_for);
100 const Prealloced_array<Table, 4> &tables() const { return m_tables; }
106 bool has_blob_column() const { return m_has_blob_column; }
108 bool store_rowids() const { return m_store_rowids; }
112 }
114 private:
115 void AddTable(TABLE *tab, bool store_contents_of_null_rows);
119 // We frequently use the bitmap to determine which side of the join an Item
120 // belongs to, so precomputing the bitmap saves quite some time.
123 // Sum of the NULL bytes and the row ID for all of the tables.
126 // Whether any of the tables has a BLOB/TEXT column. This is used to determine
127 // whether we need to estimate the row size every time we store a row to the
128 // row buffer or to a chunk file on disk. If this is set to false, we can
129 // pre-allocate any necessary buffers we need during the operation, and thus
130 // eliminate the need for recalculating the row size every time.
131 bool m_has_blob_column = false;
133 bool m_store_rowids = false;
137/// Possible values of the NULL-row flag stored by StoreFromTableBuffers(). It
138/// tells whether or not a row is a NULL-complemented row in which all column
139/// values (including non-nullable columns) are NULL. Additionally, in case it
140/// is a NULL-complemented row, the flag contains information about whether the
141/// buffer contains the actual non-NULL values that were available in the record
142/// buffer at the time the row was stored, or if no column values are stored for
143/// the NULL-complemented row. Usually, no values are stored for
144/// NULL-complemented rows, but it may be necessary in order to avoid corrupting
145/// the internal cache of EQRefIterator. See Table::store_contents_of_null_rows.
146enum class NullRowFlag {
147 /// The row is not a NULL-complemented one.
148 kNotNull,
149 /// The row is NULL-complemented. No column values are stored in the buffer.
151 /// The row is NULL-complemented. The actual non-NULL values that were in the
152 /// record buffer at the time StoreFromTableBuffers() was called, will however
153 /// be available in the buffer.
157/// Count up how many bytes a single row from the given tables will occupy,
158/// in "packed" format. Note that this is an upper bound, so the length after
159/// calling Field::pack may very well be shorter than the size returned by this
160/// function.
162/// The value returned from this function will sum up
163/// 1) The row-id if that is to be kept.
164/// 2) Size of the NULL flags. This includes:
165/// - Space for a NULL flag per nullable column.
166/// - Space for a NULL flag per nullable table (tables on the inner side of
167/// an outer join).
168/// 3) Size of the buffer returned by pack() on all columns marked in the
169/// read_set_internal.
171/// Note that if any of the tables has a BLOB/TEXT column, this function looks
172/// at the data stored in the record buffers. This means that the function can
173/// not be called before reading any rows if tables.has_blob_column is true.
174size_t ComputeRowSizeUpperBound(const TableCollection &tables);
176/// Take the data marked for reading in "tables" and store it in the provided
177/// buffer. What data to store is determined by the read set of each table.
178/// Note that any existing data in "buffer" will be overwritten.
180/// The output buffer will contain the following data for each table in
181/// "tables":
183/// 1) NULL-row flag if the table is nullable.
184/// 2) NULL flags for each nullable column.
185/// 3) The actual data from the columns.
186/// 4) The row ID for each row. This is only stored if the optimizer requested
187/// row IDs when creating the TableCollection.
189/// @retval true if error, false otherwise
190bool StoreFromTableBuffers(const TableCollection &tables, String *buffer);
192/// Take the data in "ptr" and put it back to the tables' record buffers.
193/// The tables must be _exactly_ the same as when the row was created.
194/// That is, it must contain the same tables in the same order, and the read set
195/// of each table must be identical when storing and restoring the row.
196/// If that's not the case, you will end up with undefined and unpredictable
197/// behavior.
199/// Returns a pointer to where we ended reading.
200const uchar *LoadIntoTableBuffers(const TableCollection &tables,
201 const uchar *ptr);
203/// For each of the given tables, request that the row ID is filled in
204/// (the equivalent of calling file->position()) if needed.
206/// @param tables All tables involved in the operation.
207/// @param tables_to_get_rowid_for A bitmap of which tables to actually
208/// get row IDs for. (A table needs to be in both sets to be processed.)
210 table_map tables_to_get_rowid_for);
213 table_map tables_to_get_rowid_for);
215inline bool ShouldCopyRowId(const TABLE *table) {
216 // It is not safe to copy the row ID if we have a NULL-complemented row; the
217 // value is undefined, or the buffer location can even be nullptr.
218 return !table->const_table && !(table->is_nullable() && table->null_row);
222 uchar *dptr) {
223 for (const Table &tbl : tables.tables()) {
224 const TABLE *table = tbl.table;
226 NullRowFlag null_row_flag = NullRowFlag::kNotNull;
227 if (table->is_nullable()) {
228 if (table->has_null_row()) {
229 null_row_flag = tbl.store_contents_of_null_rows && table->has_row()
232 }
233 *dptr++ = static_cast<uchar>(null_row_flag);
234 if (null_row_flag == NullRowFlag::kNullWithData) {
235 assert(table->is_started());
236 // If we want to store the actual values in the table buffer for the
237 // NULL-complemented row, instead of the NULLs, we need to restore the
238 // original null flags first. We reset the flags after we have stored
239 // the column values.
240 tbl.table->restore_null_flags();
241 tbl.table->reset_null_row();
242 }
243 }
245 // Store the NULL flags.
246 if (tbl.copy_null_flags) {
247 memcpy(dptr, table->null_flags, table->s->null_bytes);
248 dptr += table->s->null_bytes;
249 }
251 for (const Column &column : tbl.columns) {
253 column.field->field_index()));
254 if (!column.field->is_null()) {
255 // Store the data in packed format. The packed format will also
256 // include the length of the data if needed.
257 dptr = column.field->pack(dptr);
258 }
259 }
261 if (null_row_flag == NullRowFlag::kNullWithData) {
262 // The null flags were changed in order to get the actual contents of the
263 // null row stored. Restore the original null flags.
264 tbl.table->set_null_row();
265 }
267 if (tables.store_rowids() && ShouldCopyRowId(table)) {
268 // Store the row ID, since it is needed by weedout.
269 memcpy(dptr, table->file->ref, table->file->ref_length);
270 dptr += table->file->ref_length;
271 }
272 }
273 return dptr;
276} // namespace pack_rows
278#endif // SQL_PACK_ROWS_H_
Definition: field.h:574
TABLE * table
Pointer to TABLE object that owns this field.
Definition: field.h:680
uint16 field_index() const
Returns field index.
Definition: field.h:1828
bool is_null(ptrdiff_t row_offset=0) const
Check whether the full table's row is NULL or the Field has value NULL.
Definition: field.h:1217
virtual uchar * pack(uchar *to, const uchar *from, size_t max_length) const
Pack the field into a format suitable for storage and transfer.
Definition: sql_optimizer.h:132
A typesafe replacement for DYNAMIC_ARRAY.
Definition: prealloced_array.h:70
Using this class is fraught with peril, and you need to be very careful when doing so.
Definition: sql_string.h:166
A structure that contains a list of input tables for a hash join operation, BKA join operation or a s...
Definition: pack_rows.h:92
Prealloced_array< Table, 4 > m_tables
Definition: pack_rows.h:117
void AddTable(TABLE *tab, bool store_contents_of_null_rows)
table_map tables_to_get_rowid_for() const
Definition: pack_rows.h:110
bool has_blob_column() const
Definition: pack_rows.h:106
bool store_rowids() const
Definition: pack_rows.h:108
bool m_store_rowids
Definition: pack_rows.h:133
size_t ref_and_null_bytes_size() const
Definition: pack_rows.h:104
table_map m_tables_bitmap
Definition: pack_rows.h:121
table_map m_tables_to_get_rowid_for
Definition: pack_rows.h:134
size_t m_ref_and_null_bytes_size
Definition: pack_rows.h:124
table_map tables_bitmap() const
Definition: pack_rows.h:102
const Prealloced_array< Table, 4 > & tables() const
Definition: pack_rows.h:100
bool m_has_blob_column
Definition: pack_rows.h:131
This file contains the field type.
Column types for MySQL Note: Keep include/mysql/components/services/bits/stored_program_bits....
Definition: field_types.h:54
static bool bitmap_is_set(const MY_BITMAP *map, uint bit)
Definition: my_bitmap.h:94
Header for compiler-dependent features.
Definition: my_compiler.h:98
Some integer typedefs for easier portability.
unsigned char uchar
Definition: my_inttypes.h:51
uint64_t table_map
Definition: my_table_map.h:29
static PFS_engine_table_share_proxy table
mutable_buffer buffer(void *p, size_t n) noexcept
Definition: buffer.h:417
void PrepareForRequestRowId(const Prealloced_array< Table, 4 > &tables, table_map tables_to_get_rowid_for)
bool ShouldCopyRowId(const TABLE *table)
Definition: pack_rows.h:215
bool StoreFromTableBuffers(const TableCollection &tables, String *buffer)
Take the data marked for reading in "tables" and store it in the provided buffer.
ALWAYS_INLINE uchar * StoreFromTableBuffersRaw(const TableCollection &tables, uchar *dptr)
Definition: pack_rows.h:221
size_t ComputeRowSizeUpperBound(const TableCollection &tables)
Count up how many bytes a single row from the given tables will occupy, in "packed" format.
const uchar * LoadIntoTableBuffers(const TableCollection &tables, const uchar *ptr)
Take the data in "ptr" and put it back to the tables' record buffers.
void RequestRowId(const Prealloced_array< Table, 4 > &tables, table_map tables_to_get_rowid_for)
For each of the given tables, request that the row ID is filled in (the equivalent of calling file->p...
Possible values of the NULL-row flag stored by StoreFromTableBuffers().
Definition: pack_rows.h:146
@ kNullWithoutData
The row is NULL-complemented. No column values are stored in the buffer.
@ kNotNull
The row is not a NULL-complemented one.
@ kNullWithData
The row is NULL-complemented.
Performance schema instrumentation interface.
Definition: table.h:1403
MY_BITMAP read_set_internal
A bitmap of fields that are explicitly referenced by the query.
Definition: table.h:1698
A class that represents a field, which also holds a cached value of the field's data type.
Definition: pack_rows.h:60
const enum_field_types field_type
Definition: pack_rows.h:66
Field *const field
Definition: pack_rows.h:62
Column(Field *field)
This struct is primarily used for holding the extracted columns in a hash join or BKA join,...
Definition: pack_rows.h:73
Table(TABLE *table_arg)
bool copy_null_flags
Definition: pack_rows.h:79
bool store_contents_of_null_rows
Definition: pack_rows.h:86
Prealloced_array< Column, 8 > columns
Definition: pack_rows.h:76
TABLE * table
Definition: pack_rows.h:75