MySQL 8.4.3
Source Code Documentation
histograms Namespace Reference

Namespaces

namespace  equi_height
 

Classes

class  Background_error_handler
 Custom error handling for histogram updates from the background thread. More...
 
class  Equi_height
 
class  Error_context
 Error context to validate given JSON object which represents a histogram. More...
 
class  Histogram
 Histogram base class. More...
 
struct  Histogram_comparator
 Histogram comparator. More...
 
struct  Histogram_psi_key_alloc
 
struct  HistogramSetting
 A simple struct containing the settings for a histogram to be built. More...
 
class  Singleton
 
struct  SingletonBucket
 
class  Value_map
 Value_map class. More...
 
class  Value_map_base
 The abstract base class for all Value_map types. More...
 

Typedefs

using value_map_collection = std::map< uint16, std::unique_ptr< histograms::Value_map_base >, std::less< uint16 >, Histogram_key_allocator< std::pair< const uint16, std::unique_ptr< histograms::Value_map_base > > > >
 
template<class T >
using Histogram_key_allocator = Stateless_allocator< T, Histogram_psi_key_alloc >
 
template<class T >
using value_map_allocator = Mem_root_allocator< std::pair< const T, ha_rows > >
 
template<typename T >
using value_map_type = std::map< T, ha_rows, Histogram_comparator, value_map_allocator< T > >
 
using columns_set = std::set< std::string, std::less< std::string >, Histogram_key_allocator< std::string > >
 
using results_map = std::map< std::string, Message, std::less< std::string >, Histogram_key_allocator< std::pair< const std::string, Message > > >
 

Enumerations

enum class  Message {
  FIELD_NOT_FOUND , UNSUPPORTED_DATA_TYPE , TEMPORARY_TABLE , ENCRYPTED_TABLE ,
  VIEW , HISTOGRAM_CREATED , MULTIPLE_TABLES_SPECIFIED , COVERED_BY_SINGLE_PART_UNIQUE_INDEX ,
  NO_HISTOGRAM_FOUND , HISTOGRAM_DELETED , SERVER_READ_ONLY , MULTIPLE_COLUMNS_SPECIFIED ,
  SYSTEM_SCHEMA_NOT_SUPPORTED , JSON_FORMAT_ERROR , JSON_NOT_AN_OBJECT , JSON_MISSING_ATTRIBUTE ,
  JSON_WRONG_ATTRIBUTE_TYPE , JSON_WRONG_BUCKET_TYPE_2 , JSON_WRONG_BUCKET_TYPE_4 , JSON_WRONG_DATA_TYPE ,
  JSON_UNSUPPORTED_DATA_TYPE , JSON_UNSUPPORTED_HISTOGRAM_TYPE , JSON_UNSUPPORTED_CHARSET , JSON_INVALID_SAMPLING_RATE ,
  JSON_INVALID_NUM_BUCKETS_SPECIFIED , JSON_INVALID_FREQUENCY , JSON_INVALID_NUM_DISTINCT , JSON_VALUE_FORMAT_ERROR ,
  JSON_VALUE_OUT_OF_RANGE , JSON_VALUE_NOT_ASCENDING_1 , JSON_VALUE_NOT_ASCENDING_2 , JSON_VALUE_DESCENDING_IN_BUCKET ,
  JSON_CUMULATIVE_FREQUENCY_NOT_ASCENDING , JSON_INVALID_NULL_VALUES_FRACTION , JSON_INVALID_TOTAL_FREQUENCY , JSON_NUM_BUCKETS_MORE_THAN_SPECIFIED ,
  JSON_IMPOSSIBLE_EMPTY_EQUI_HEIGHT
}
 
enum class  enum_operator {
  EQUALS_TO , GREATER_THAN , LESS_THAN , IS_NULL ,
  IS_NOT_NULL , LESS_THAN_OR_EQUAL , GREATER_THAN_OR_EQUAL , NOT_EQUALS_TO ,
  BETWEEN , NOT_BETWEEN , IN_LIST , NOT_IN_LIST
}
 The different operators we can ask histogram statistics for selectivity estimations. More...
 
enum class  Value_map_type {
  INVALID , STRING , INT , UINT ,
  DOUBLE , DECIMAL , DATE , TIME ,
  DATETIME , ENUM , SET
}
 Datatypes that a Value_map and histogram can hold (including the invalid type). More...
 

Functions

template<class T >
static bool FitsIntoBuckets (const Value_map< T > &value_map, ha_rows max_bucket_values, size_t max_buckets)
 
template<class T >
static ha_rows FindBucketMaxValues (const Value_map< T > &value_map, size_t max_buckets)
 
static ha_rows EstimateDistinctValues (double sampling_rate, ha_rows bucket_distinct_values, ha_rows bucket_unary_values)
 
static Value_map_type field_type_to_value_map_type (const enum_field_types field_type, const bool is_unsigned)
 Convert from enum_field_types to Value_map_type. More...
 
static Value_map_type field_type_to_value_map_type (const Field *field)
 Get the Value_map_type from a Field object. More...
 
static type_conversion_status check_value_aux (Field *field, const double *nr)
 Helper function for check_value(). More...
 
static type_conversion_status check_value_aux (Field *field, const String *str)
 
static type_conversion_status check_value_aux (Field *field, const longlong *nr)
 
static type_conversion_status check_value_aux (Field *field, const ulonglong *nr)
 
static type_conversion_status check_value_aux (Field *field, MYSQL_TIME *ltime)
 
static type_conversion_status check_value_aux (Field *field, const my_decimal *mdec)
 
static bool lock_for_write (THD *thd, const MDL_key &mdl_key)
 Lock a column statistic MDL key for writing (exclusive lock). More...
 
template<class T >
Histogrambuild_histogram (MEM_ROOT *mem_root, const Value_map< T > &value_map, size_t num_buckets, const std::string &db_name, const std::string &tbl_name, const std::string &col_name)
 Create a histogram from a value map. More...
 
static bool covered_by_single_part_index (const THD *thd, const Field *field)
 Check if a field is covered by a single-part unique index (primary key or unique index). More...
 
static bool prepare_value_maps (const Mem_root_array< HistogramSetting > &settings, value_map_collection &value_maps, size_t *row_size_bytes)
 Prepare one Value_map for each field we are creating histogram statistics for. More...
 
static bool fill_value_maps (const Mem_root_array< HistogramSetting > &settings, double sample_percentage, const TABLE *table, value_map_collection &value_maps)
 Read data from a table into the provided Value_maps. More...
 
static bool is_using_data (const HistogramSetting &setting)
 
static void resolve_histogram_fields (THD *thd, TABLE *table, Mem_root_array< HistogramSetting > *settings, results_map &results)
 Resolve histogram fields on the supplied collection of histogram update settings. More...
 
static bool update_histogram_using_data (THD *thd, Table_ref *table, const HistogramSetting &setting, results_map &results)
 Builds a histogram from a user-supplied JSON string and persists it to the dictionary. More...
 
bool update_histograms (THD *thd, Table_ref *table, Mem_root_array< HistogramSetting > *settings, results_map &results)
 Create or update histograms for a set of columns of a given table. More...
 
bool update_share_histograms (THD *thd, Table_ref *table)
 Retrieve an updated snapshot of the histograms on a table directly from the dictionary (in an inefficient manner, querying all columns) and inserts this snapshot in the Table_histograms_collection on the TABLE_SHARE. More...
 
static bool lock_table_histograms (THD *thd, TABLE *table)
 Acquire exclusive metadata locks on histograms for all columns. More...
 
static bool supports_histogram_updates (THD *thd, Table_ref *table)
 A collection of checks to determine whether the session context and table properties support histogram updates. More...
 
static bool retrieve_auto_update_histogram_settings (THD *thd, Table_ref *table, Mem_root_array< HistogramSetting > *settings)
 Collects the settings for automatically updated histograms on a table. More...
 
bool auto_update_table_histograms (THD *thd, Table_ref *table)
 Updates existing histograms on a table that were specified with the AUTO UPDATE option. More...
 
static loglevel log_level (const Sql_condition *condition)
 
static void write_diagnostics_area_to_error_log (THD *thd, std::string db_name, std::string table_name)
 Writes messages from the diagnostics area to the error log. More...
 
static void prepare_session_context (THD *thd)
 Prepare the session context for histogram updates. More...
 
static void cleanup_session_context (THD *thd)
 Clean up the session context following histogram updates. More...
 
static bool is_hidden_by_system (const dd::Column *col)
 Determine whether a column is hidden from the user. More...
 
bool auto_update_table_histograms_from_background_thread (THD *thd, const std::string &db_name, const std::string &table_name)
 Updates existing histograms on a table that were specified with the AUTO UPDATE option. More...
 
bool drop_all_histograms (THD *thd, Table_ref &table, const dd::Table &original_table_def, results_map &results)
 Drop histograms for all columns in a given table. More...
 
bool drop_histograms (THD *thd, Table_ref &table, const columns_set &columns, results_map &results)
 Drop histograms for a set of columns in a given table. More...
 
static bool rename_histogram (THD *thd, const char *old_schema_name, const char *old_table_name, const char *new_schema_name, const char *new_table_name, const char *column_name, results_map &results)
 Rename a single histogram from a old schema/table name to a new schema/table name. More...
 
bool rename_histograms (THD *thd, const char *old_schema_name, const char *old_table_name, const char *new_schema_name, const char *new_table_name, results_map &results)
 Rename histograms for all columns in a given table. More...
 
bool find_histogram (THD *thd, const std::string &schema_name, const std::string &table_name, const std::string &column_name, const Histogram **histogram)
 
static bool get_temporal (Item *item, Value_map_type preferred_type, MYSQL_TIME *time_value)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< double > &, size_t, const std::string &, const std::string &, const std::string &)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< String > &, size_t, const std::string &, const std::string &, const std::string &)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< ulonglong > &, size_t, const std::string &, const std::string &, const std::string &)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< longlong > &, size_t, const std::string &, const std::string &, const std::string &)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< MYSQL_TIME > &, size_t, const std::string &, const std::string &, const std::string &)
 
template Histogrambuild_histogram (MEM_ROOT *, const Value_map< my_decimal > &, size_t, const std::string &, const std::string &, const std::string &)
 
bool empty (const Histogram &histogram)
 Return true if 'histogram' was built on an empty table. More...
 
template<typename T >
DeepCopy (const T &src, MEM_ROOT *mem_root, bool *error)
 Returns a deep copy of the input argument. More...
 
template<>
String DeepCopy (const String &src, MEM_ROOT *mem_root, bool *error)
 

Variables

static constexpr int MAX_NUMBER_OF_HISTOGRAM_BUCKETS = 1024
 
static std::map< const Value_map_type, const std::string > value_map_type_to_str
 
static const double INVALID_NULL_VALUES_FRACTION = -1.0
 The default (and invalid) value for "m_null_values_fraction". More...
 
static const size_t HISTOGRAM_MAX_COMPARE_LENGTH = 42
 The maximum number of characters to evaluate when building histograms. More...
 

Typedef Documentation

◆ columns_set

using histograms::columns_set = typedef std::set<std::string, std::less<std::string>, Histogram_key_allocator<std::string> >

◆ Histogram_key_allocator

◆ results_map

using histograms::results_map = typedef std::map<std::string, Message, std::less<std::string>, Histogram_key_allocator<std::pair<const std::string, Message> >>

◆ value_map_allocator

template<class T >
using histograms::value_map_allocator = typedef Mem_root_allocator<std::pair<const T, ha_rows> >

◆ value_map_collection

using histograms::value_map_collection = typedef std::map< uint16, std::unique_ptr<histograms::Value_map_base>, std::less<uint16>, Histogram_key_allocator< std::pair<const uint16, std::unique_ptr<histograms::Value_map_base> >> >

◆ value_map_type

template<typename T >
using histograms::value_map_type = typedef std::map<T, ha_rows, Histogram_comparator, value_map_allocator<T> >

Enumeration Type Documentation

◆ enum_operator

enum class histograms::enum_operator
strong

The different operators we can ask histogram statistics for selectivity estimations.

Enumerator
EQUALS_TO 
GREATER_THAN 
LESS_THAN 
IS_NULL 
IS_NOT_NULL 
LESS_THAN_OR_EQUAL 
GREATER_THAN_OR_EQUAL 
NOT_EQUALS_TO 
BETWEEN 
NOT_BETWEEN 
IN_LIST 
NOT_IN_LIST 

◆ Message

enum class histograms::Message
strong
Enumerator
FIELD_NOT_FOUND 
UNSUPPORTED_DATA_TYPE 
TEMPORARY_TABLE 
ENCRYPTED_TABLE 
VIEW 
HISTOGRAM_CREATED 
MULTIPLE_TABLES_SPECIFIED 
COVERED_BY_SINGLE_PART_UNIQUE_INDEX 
NO_HISTOGRAM_FOUND 
HISTOGRAM_DELETED 
SERVER_READ_ONLY 
MULTIPLE_COLUMNS_SPECIFIED 
SYSTEM_SCHEMA_NOT_SUPPORTED 
JSON_FORMAT_ERROR 
JSON_NOT_AN_OBJECT 
JSON_MISSING_ATTRIBUTE 
JSON_WRONG_ATTRIBUTE_TYPE 
JSON_WRONG_BUCKET_TYPE_2 
JSON_WRONG_BUCKET_TYPE_4 
JSON_WRONG_DATA_TYPE 
JSON_UNSUPPORTED_DATA_TYPE 
JSON_UNSUPPORTED_HISTOGRAM_TYPE 
JSON_UNSUPPORTED_CHARSET 
JSON_INVALID_SAMPLING_RATE 
JSON_INVALID_NUM_BUCKETS_SPECIFIED 
JSON_INVALID_FREQUENCY 
JSON_INVALID_NUM_DISTINCT 
JSON_VALUE_FORMAT_ERROR 
JSON_VALUE_OUT_OF_RANGE 
JSON_VALUE_NOT_ASCENDING_1 
JSON_VALUE_NOT_ASCENDING_2 
JSON_VALUE_DESCENDING_IN_BUCKET 
JSON_CUMULATIVE_FREQUENCY_NOT_ASCENDING 
JSON_INVALID_NULL_VALUES_FRACTION 
JSON_INVALID_TOTAL_FREQUENCY 
JSON_NUM_BUCKETS_MORE_THAN_SPECIFIED 
JSON_IMPOSSIBLE_EMPTY_EQUI_HEIGHT 

◆ Value_map_type

enum class histograms::Value_map_type
strong

Datatypes that a Value_map and histogram can hold (including the invalid type).

Enumerator
INVALID 
STRING 
INT 
UINT 
DOUBLE 
DECIMAL 
DATE 
TIME 
DATETIME 
ENUM 
SET 

Function Documentation

◆ auto_update_table_histograms()

bool histograms::auto_update_table_histograms ( THD thd,
Table_ref table 
)

Updates existing histograms on a table that were specified with the AUTO UPDATE option.

If any histograms were updated a new snapshot of the current collection of histograms for the table is inserted on the TABLE_SHARE.

Note
The caller must manually ensure that the table share is flushed or that tables are evicted from the table cache to guarantee that new queries will use the updated histograms. This can be done by calling tdc_remove_table() and passing the TDC_RT_REMOVE_UNUSED or TDC_RT_MARK_FOR_REOPEN option, respectively.
Parameters
thdThread handle.
tableTable_ref for the table to update histograms on. The table should already be opened.
Returns
False if all automatically updated histograms on the table (potentially none) were updated without encountering an error. True otherwise.

◆ auto_update_table_histograms_from_background_thread()

bool histograms::auto_update_table_histograms_from_background_thread ( THD thd,
const std::string &  db_name,
const std::string &  table_name 
)

Updates existing histograms on a table that were specified with the AUTO UPDATE option.

Updated histograms are made available to the optimizer.

This function wraps auto_update_table_histograms()) in an appropriate transaction-context for the background thread.

Note
This function temporarily disables the binary log as we are not interested in replicating or recovering updates to histograms that take place in the background.
This function supresses some errors in order to avoid spamming the error log, but unexpected errors are written to the error log, following the same pattern as the event scheduler.
Parameters
thdBackground thread handle.
db_nameName of the database holding the table.
table_nameName of the table to update histograms for.
Returns
False on success, true on error.

◆ build_histogram() [1/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< double > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [2/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< longlong > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [3/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< my_decimal > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [4/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< MYSQL_TIME > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [5/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< String > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [6/7]

template Histogram * histograms::build_histogram ( MEM_ROOT ,
const Value_map< ulonglong > &  ,
size_t  ,
const std::string &  ,
const std::string &  ,
const std::string &   
)

◆ build_histogram() [7/7]

template<class T >
Histogram * histograms::build_histogram ( MEM_ROOT mem_root,
const Value_map< T > &  value_map,
size_t  num_buckets,
const std::string &  db_name,
const std::string &  tbl_name,
const std::string &  col_name 
)

Create a histogram from a value map.

This function will build a histogram from a value map. The histogram type depends on both the size of the input data, as well as the number of buckets specified. If the number of distinct values is less than or equal to the number of buckets, a Singleton histogram will be created. Otherwise, an equi-height histogram will be created.

The histogram will be allocated on the supplied mem_root, and it is the callers responsibility to properly clean up when the histogram isn't needed anymore.

Parameters
mem_rootthe MEM_ROOT where the histogram contents will be allocated
value_mapa value map containing [value, frequency]
num_bucketsthe maximum number of buckets to create
db_namename of the database this histogram represents
tbl_namename of the table this histogram represents
col_namename of the column this histogram represents
Returns
a histogram, using at most "num_buckets" buckets. The histogram type depends on the size of the input data, and the number of buckets

◆ check_value_aux() [1/6]

static type_conversion_status histograms::check_value_aux ( Field field,
const double *  nr 
)
static

Helper function for check_value().

It uses Field::store() on the actual Field that the histogram belongs to in order to test if the value is in the field definition domain.

◆ check_value_aux() [2/6]

static type_conversion_status histograms::check_value_aux ( Field field,
const longlong nr 
)
static

◆ check_value_aux() [3/6]

static type_conversion_status histograms::check_value_aux ( Field field,
const my_decimal mdec 
)
static

◆ check_value_aux() [4/6]

static type_conversion_status histograms::check_value_aux ( Field field,
const String str 
)
static

◆ check_value_aux() [5/6]

static type_conversion_status histograms::check_value_aux ( Field field,
const ulonglong nr 
)
static

◆ check_value_aux() [6/6]

static type_conversion_status histograms::check_value_aux ( Field field,
MYSQL_TIME ltime 
)
static

◆ cleanup_session_context()

static void histograms::cleanup_session_context ( THD thd)
static

Clean up the session context following histogram updates.

Parameters
thdThread handle.

◆ covered_by_single_part_index()

static bool histograms::covered_by_single_part_index ( const THD thd,
const Field field 
)
static

Check if a field is covered by a single-part unique index (primary key or unique index).

Indexes that are marked as invisible are ignored.

Parameters
thdThe current session.
fieldThe field to check.
Returns
true if the field is covered by a single-part unique index. False otherwise.

◆ DeepCopy() [1/2]

template<>
String histograms::DeepCopy ( const String src,
MEM_ROOT mem_root,
bool *  error 
)
inline

◆ DeepCopy() [2/2]

template<typename T >
T histograms::DeepCopy ( const T &  src,
MEM_ROOT mem_root,
bool *  error 
)

Returns a deep copy of the input argument.

In case T has heap-allocated data it is copied onto the supplied mem_root.

Note
This function is only intended to be used to copy the values in histogram buckets and does not provide general support for deep copying arbitrary types.
Parameters
srcThe value to be copied.
mem_rootThe MEM_ROOT to copy heap-allocated data onto.
[out]errorSet to true if an error occurs.
Returns
A deep copy of the input argument.

◆ drop_all_histograms()

bool histograms::drop_all_histograms ( THD thd,
Table_ref table,
const dd::Table original_table_def,
results_map results 
)

Drop histograms for all columns in a given table.

Parameters
thdThread handler.
tableThe table where we should look for the columns.
original_table_defOriginal table definition.
resultsA map where the result of each operation is stored.
Note
Assumes that caller owns exclusive metadata lock on the table, so there is no need to lock individual statistics.
Returns
false on success, true on error.

◆ drop_histograms()

bool histograms::drop_histograms ( THD thd,
Table_ref table,
const columns_set columns,
results_map results 
)

Drop histograms for a set of columns in a given table.

This function will try to drop the histogram statistics for all specified columns. If one of the columns fail, it will continue to the next one and try.

Parameters
thdThread handler.
tableThe table where we should look for the columns.
columnsColumns specified by the user.
resultsA map where the result of each operation is stored.
Note
Assumes that the caller has the appropriate metadata locks on both the table and column statistics. That can either be an exclusive metadata lock on the table itself, or a shared metadata lock on the table combined with exclusive locks on individual column statistics.
Returns
false on success, true on error.

◆ empty()

bool histograms::empty ( const Histogram histogram)
inline

Return true if 'histogram' was built on an empty table.

◆ EstimateDistinctValues()

static ha_rows histograms::EstimateDistinctValues ( double  sampling_rate,
ha_rows  bucket_distinct_values,
ha_rows  bucket_unary_values 
)
static

◆ field_type_to_value_map_type() [1/2]

static Value_map_type histograms::field_type_to_value_map_type ( const enum_field_types  field_type,
const bool  is_unsigned 
)
static

Convert from enum_field_types to Value_map_type.

Parameters
field_typethe field type
is_unsignedwhether the field type is unsigned or not. This is only considered if the field type is LONGLONG
Returns
A Value_map_type. May be INVALID if the Value_map does not support the field type.

◆ field_type_to_value_map_type() [2/2]

static Value_map_type histograms::field_type_to_value_map_type ( const Field field)
static

Get the Value_map_type from a Field object.

This effectively looks at the real_type() of a Field, and converts this to a Value_map_type

Parameters
fieldThe field to convert from
Returns
A Value_map_type. May be INVALID if the Value_map does not support the field type.

◆ fill_value_maps()

static bool histograms::fill_value_maps ( const Mem_root_array< HistogramSetting > &  settings,
double  sample_percentage,
const TABLE table,
value_map_collection value_maps 
)
static

Read data from a table into the provided Value_maps.

We will read data using sampling with the provided sampling percentage.

Parameters
settingsA collection of histogram settings that contain the fields we are reading data from.
sample_percentageThe sampling percentage we will use for sampling. Must be between 0.0 and 100.0.
tableThe table we are reading the data from.
value_mapsThe Value_maps we are reading data into.
Returns
true on error, false otherwise.

◆ find_histogram()

bool histograms::find_histogram ( THD thd,
const std::string &  schema_name,
const std::string &  table_name,
const std::string &  column_name,
const Histogram **  histogram 
)

◆ FindBucketMaxValues()

template<class T >
static ha_rows histograms::FindBucketMaxValues ( const Value_map< T > &  value_map,
size_t  max_buckets 
)
static

◆ FitsIntoBuckets()

template<class T >
static bool histograms::FitsIntoBuckets ( const Value_map< T > &  value_map,
ha_rows  max_bucket_values,
size_t  max_buckets 
)
static

◆ get_temporal()

static bool histograms::get_temporal ( Item item,
Value_map_type  preferred_type,
MYSQL_TIME time_value 
)
static

◆ is_hidden_by_system()

static bool histograms::is_hidden_by_system ( const dd::Column col)
static

Determine whether a column is hidden from the user.

Should be equivalent to field::is_hidden_by_system().

Parameters
colColumn definition.
Returns
True if the column is hidden from the user, false otherwise.

◆ is_using_data()

static bool histograms::is_using_data ( const HistogramSetting setting)
static

◆ lock_for_write()

static bool histograms::lock_for_write ( THD thd,
const MDL_key mdl_key 
)
static

Lock a column statistic MDL key for writing (exclusive lock).

Parameters
thdthread handle
mdl_keythe MDL key to lock
Returns
true on error, false on success

◆ lock_table_histograms()

static bool histograms::lock_table_histograms ( THD thd,
TABLE table 
)
static

Acquire exclusive metadata locks on histograms for all columns.

Does not check whether a histogram exists or not, but simply acquires metadata locks on histograms for all columns that are not hidden by the system.

Parameters
thdThread object for the statement.
tableOpened table.
Returns
True if error, false if success.

◆ log_level()

static loglevel histograms::log_level ( const Sql_condition condition)
static

◆ prepare_session_context()

static void histograms::prepare_session_context ( THD thd)
static

Prepare the session context for histogram updates.

Parameters
thdThread handle.

◆ prepare_value_maps()

static bool histograms::prepare_value_maps ( const Mem_root_array< HistogramSetting > &  settings,
value_map_collection value_maps,
size_t *  row_size_bytes 
)
static

Prepare one Value_map for each field we are creating histogram statistics for.

We will also estimate how many bytes one row will consume. For example, if we are creating histogram statistics for two INTEGER columns, we estimate that one row will consume (sizeof(longlong) * 2) bytes (16 bytes).

Parameters
settingsA collection of histogram settings with all the fields we are creating histogram statistics for.
[out]value_mapsA map where the Value_maps will be initialized.
[out]row_size_bytesAn estimation of how many bytes one row will consume.
Returns
true on error, false otherwise.

◆ rename_histogram()

static bool histograms::rename_histogram ( THD thd,
const char *  old_schema_name,
const char *  old_table_name,
const char *  new_schema_name,
const char *  new_table_name,
const char *  column_name,
results_map results 
)
static

Rename a single histogram from a old schema/table name to a new schema/table name.

It is used for instance by RENAME TABLE, where the contents of the histograms doesn't change.

Parameters
thdThread handler.
old_schema_nameThe old schema name.
old_table_nameThe old table name.
new_schema_nameThe new schema name.
new_table_nameThe new table name.
column_nameThe column name.
resultsA map where the result of the operation is stored.
Returns
false on success, true on error.

◆ rename_histograms()

bool histograms::rename_histograms ( THD thd,
const char *  old_schema_name,
const char *  old_table_name,
const char *  new_schema_name,
const char *  new_table_name,
results_map results 
)

Rename histograms for all columns in a given table.

Parameters
thdThread handler.
old_schema_nameThe old schema name
old_table_nameThe old table name
new_schema_nameThe new schema name
new_table_nameThe new table name
resultsA map where the result of each operation is stored.
Returns
false on success, true on error.

◆ resolve_histogram_fields()

static void histograms::resolve_histogram_fields ( THD thd,
TABLE table,
Mem_root_array< HistogramSetting > *  settings,
results_map results 
)
static

Resolve histogram fields on the supplied collection of histogram update settings.

Modifies the collection of settings in-place to only keep those that can be resolved to fields that exist in the table with a data type that is supported by histograms. Also updates the read set for the TABLE to reflect what columns to read when sampling data to update the histograms.

Parameters
thdThread handle.
tableOpened table.
[in,out]settingsDynamic array of settings for histograms to update.
resultsA container for diagnostics information to the user.

◆ retrieve_auto_update_histogram_settings()

static bool histograms::retrieve_auto_update_histogram_settings ( THD thd,
Table_ref table,
Mem_root_array< HistogramSetting > *  settings 
)
static

Collects the settings for automatically updated histograms on a table.

Parameters
thdThread handle.
tableTable_ref with an open table attached.
[in,out]settingsThe vector of settings to be populated.
Returns
True if an error occured when retrieving the settings, false otherwise.

◆ supports_histogram_updates()

static bool histograms::supports_histogram_updates ( THD thd,
Table_ref table 
)
static

A collection of checks to determine whether the session context and table properties support histogram updates.

Parameters
thdThread handle.
tableTable_ref with an open table attached.
Returns
True if histogram updates are supported, false otherwise.

◆ update_histogram_using_data()

static bool histograms::update_histogram_using_data ( THD thd,
Table_ref table,
const HistogramSetting setting,
results_map results 
)
static

Builds a histogram from a user-supplied JSON string and persists it to the dictionary.

Errors from this function are reported both through calls to my_error() and by placing messages in the passed-along results map. These errors and messages are sent to the client as a result set, see send_histogram_results() in sql_admin.cc.

The results map is a sink for histogram-specific messages and errors for which we typically do not have a my_error() error code. In the context of this function and its call to Histogram::json_to_histogram() any potential error messages in the results map will primarily relate to JSON formatting errors.

Calls to my_error() is generally used to report more serious errors, but there is no absolute rule for which type of error (e.g. fatal or non-fatal to the execution of this function) that goes to which error sink (diagnostics area or the results map).

We guarantee that if the function returns true there will be at least one error (ER_UNABLE_TO_BUILD_HISTOGRAM) placed in the diagnostics area.

Parameters
thdThread handle.
tableOpened table.
settingSettings for the histogram to build.
resultsA container for diagnostics information (error and completion messages) to the user.
Returns
True on error, false on success.

◆ update_histograms()

bool histograms::update_histograms ( THD thd,
Table_ref table,
Mem_root_array< HistogramSetting > *  settings,
results_map results 
)

Create or update histograms for a set of columns of a given table.

This function will try to create a histogram for each HistogramSetting object passed to it. It operates in two stages:

In the first stage it will attempt to resolve every HistogramSetting in settings, verifying that the specified column exists and supports histograms. If a setting cannot be resolved an error message will be generated (see note below for details on error reporting), but the function will continue executing. The collection of settings is modified in-place so that only the resolved settings remain when the function returns.

In the second stage, after the settings have been resolved, the function attempts to build a histogram for each resolved column. If an error is encountered during this stage, the function will immediately abort and return true. In other words, if the function returns true, it will have made an attempt to update the histograms as specified in the output collection of settings, but it could have failed halfway.

If no error occurs during the second stage the function will return false, and the histograms specified in the output collection of settings will succesfully have been updated.

Parameters
thdThread handler.
tableThe table where we should look for the columns/data.
[in,out]settingsThe settings for the histograms to be built.
[in,out]resultsA map where the result of each operation is stored.
Returns
False on success, true if an error was encountered.

◆ update_share_histograms()

bool histograms::update_share_histograms ( THD thd,
Table_ref table 
)

Retrieve an updated snapshot of the histograms on a table directly from the dictionary (in an inefficient manner, querying all columns) and inserts this snapshot in the Table_histograms_collection on the TABLE_SHARE.

Parameters
thdThe current thread.
tableThe table to retrieve updated histograms for.
Note
This function assumes that the table is opened and generally depends on the surrounding context. It also locks/unlocks LOCK_OPEN.
Returns
False on success. Returns true if an error occurred in which case the TABLE_SHARE will not have been updated.

◆ write_diagnostics_area_to_error_log()

static void histograms::write_diagnostics_area_to_error_log ( THD thd,
std::string  db_name,
std::string  table_name 
)
static

Writes messages from the diagnostics area to the error log.

Used by the background histogram update operation to report diagnostics to the user through the error log.

Note
Follows the same approach to reporting as used by the event scheduler. See event_scheduler.cc:print_warnings.
Parameters
thdThread handle.
db_nameThe database of the target table for the histogram update.
table_nameThe target table for the histogram update.

Variable Documentation

◆ HISTOGRAM_MAX_COMPARE_LENGTH

const size_t histograms::HISTOGRAM_MAX_COMPARE_LENGTH = 42
static

The maximum number of characters to evaluate when building histograms.

For binary/blob values, this is the number of bytes to consider.

◆ INVALID_NULL_VALUES_FRACTION

const double histograms::INVALID_NULL_VALUES_FRACTION = -1.0
static

The default (and invalid) value for "m_null_values_fraction".

◆ MAX_NUMBER_OF_HISTOGRAM_BUCKETS

constexpr int histograms::MAX_NUMBER_OF_HISTOGRAM_BUCKETS = 1024
staticconstexpr

◆ value_map_type_to_str

std::map<const Value_map_type, const std::string> histograms::value_map_type_to_str
static
Initial value:
=
{{Value_map_type::DATETIME, "datetime"}, {Value_map_type::DATE, "date"},
{Value_map_type::TIME, "time"}, {Value_map_type::INT, "int"},
{Value_map_type::UINT, "uint"}, {Value_map_type::DOUBLE, "double"},
{Value_map_type::DECIMAL, "decimal"}, {Value_map_type::STRING, "string"},
{Value_map_type::ENUM, "enum"}, {Value_map_type::SET, "set"}}
@ DATE
Definition: mysqlx_resultset.proto:627