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 >
Histogram *	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. 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 Histogram *	build_histogram (MEM_ROOT *, const Value_map< double > &, size_t, const std::string &, const std::string &, const std::string &)
template Histogram *	build_histogram (MEM_ROOT *, const Value_map< String > &, size_t, const std::string &, const std::string &, const std::string &)
template Histogram *	build_histogram (MEM_ROOT *, const Value_map< ulonglong > &, size_t, const std::string &, const std::string &, const std::string &)
template Histogram *	build_histogram (MEM_ROOT *, const Value_map< longlong > &, size_t, const std::string &, const std::string &, const std::string &)
template Histogram *	build_histogram (MEM_ROOT *, const Value_map< MYSQL_TIME > &, size_t, const std::string &, const std::string &, const std::string &)
template Histogram *	build_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 >
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

template<class T >

using histograms::Histogram_key_allocator = typedef Stateless_allocator<T, Histogram_psi_key_alloc>

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

thd	Thread handle.
table	Table_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

thd	Background thread handle.
db_name	Name of the database holding the table.
table_name	Name 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_root	the MEM_ROOT where the histogram contents will be allocated
value_map	a value map containing [value, frequency]
num_buckets	the maximum number of buckets to create
db_name	name of the database this histogram represents
tbl_name	name of the table this histogram represents
col_name	name 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

thd	Thread 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

thd	The current session.
field	The 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

	src	The value to be copied.
	mem_root	The MEM_ROOT to copy heap-allocated data onto.
[out]	error	Set 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

thd	Thread handler.
table	The table where we should look for the columns.
original_table_def	Original table definition.
results	A 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

thd	Thread handler.
table	The table where we should look for the columns.
columns	Columns specified by the user.
results	A 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_type	the field type
is_unsigned	whether 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

field

The 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

settings	A collection of histogram settings that contain the fields we are reading data from.
sample_percentage	The sampling percentage we will use for sampling. Must be between 0.0 and 100.0.
table	The table we are reading the data from.
value_maps	The 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

col	Column 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

thd	thread handle
mdl_key	the 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

thd	Thread object for the statement.
table	Opened 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

thd	Thread 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

	settings	A collection of histogram settings with all the fields we are creating histogram statistics for.
[out]	value_maps	A map where the Value_maps will be initialized.
[out]	row_size_bytes	An 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

thd	Thread handler.
old_schema_name	The old schema name.
old_table_name	The old table name.
new_schema_name	The new schema name.
new_table_name	The new table name.
column_name	The column name.
results	A 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

thd	Thread handler.
old_schema_name	The old schema name
old_table_name	The old table name
new_schema_name	The new schema name
new_table_name	The new table name
results	A 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

	thd	Thread handle.
	table	Opened table.
[in,out]	settings	Dynamic array of settings for histograms to update.
	results	A 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

	thd	Thread handle.
	table	Table_ref with an open table attached.
[in,out]	settings	The 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

thd	Thread handle.
table	Table_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

thd	Thread handle.
table	Opened table.
setting	Settings for the histogram to build.
results	A 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

	thd	Thread handler.
	table	The table where we should look for the columns/data.
[in,out]	settings	The settings for the histograms to be built.
[in,out]	results	A 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

thd	The current thread.
table	The 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

thd	Thread handle.
db_name	The database of the target table for the histogram update.
table_name	The 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"}}