Histogram base class. More...

#include <histogram.h>

Inheritance diagram for histograms::Histogram:

Public Types
enum class	enum_histogram_type { EQUI_HEIGHT , SINGLETON }
	All supported histogram types in MySQL. More...

Public Member Functions
	Histogram ()=delete

	Histogram (const Histogram &other)=delete

virtual	~Histogram ()=default
	Destructor. More...

MEM_ROOT *	get_mem_root () const

const LEX_CSTRING	get_database_name () const

const LEX_CSTRING	get_table_name () const

const LEX_CSTRING	get_column_name () const

enum_histogram_type	get_histogram_type () const

double	get_null_values_fraction () const

const CHARSET_INFO *	get_character_set () const

double	get_sampling_rate () const

virtual std::string	histogram_type_to_str () const =0
	Returns the histogram type as a readable string. More...

virtual size_t	get_num_buckets () const =0

virtual size_t	get_num_distinct_values () const =0
	Get the estimated number of distinct non-NULL values. More...

Value_map_type	get_data_type () const

size_t	get_num_buckets_specified () const

bool	get_auto_update () const

void	set_auto_update (bool auto_update)
	Sets the auto update property for the histogram. More...

virtual bool	histogram_to_json (Json_object *json_object) const =0
	Converts the histogram to a JSON object. More...

virtual Histogram *	clone (MEM_ROOT *mem_root) const =0
	Make a clone of the current histogram. More...

bool	store_histogram (THD *thd) const
	Store this histogram to persistent storage (data dictionary). More...

bool	get_selectivity (Item *items, size_t item_count, enum_operator op, double selectivity) const
	Get selectivity estimation. More...

double	get_non_null_values_fraction () const

template<>
bool	extract_json_dom_value (const Json_dom json_dom, double out, Error_context *context)

template<>
bool	extract_json_dom_value (const Json_dom json_dom, String out, Error_context *context)

template<>
bool	extract_json_dom_value (const Json_dom json_dom, ulonglong out, Error_context *context)

template<>
bool	extract_json_dom_value (const Json_dom json_dom, longlong out, Error_context *context)

template<>
bool	extract_json_dom_value (const Json_dom json_dom, MYSQL_TIME out, Error_context *context)

template<>
bool	extract_json_dom_value (const Json_dom json_dom, my_decimal out, Error_context *context)

Static Public Member Functions
static constexpr const char *	histogram_type_str ()
	String representation of the JSON field "histogram-type". More...

static constexpr const char *	data_type_str ()
	String representation of the JSON field "data-type". More...

static constexpr const char *	collation_id_str ()
	String representation of the JSON field "collation-id". More...

static constexpr const char *	singleton_str ()
	String representation of the histogram type SINGLETON. More...

static constexpr const char *	equi_height_str ()
	String representation of the histogram type EQUI-HEIGHT. More...

static Histogram *	json_to_histogram (MEM_ROOT mem_root, const std::string &schema_name, const std::string &table_name, const std::string &column_name, const Json_object &json_object, Error_context context)
	Converts JSON object to a histogram. More...

Protected Member Functions
	Histogram (MEM_ROOT mem_root, const std::string &db_name, const std::string &tbl_name, const std::string &col_name, enum_histogram_type type, Value_map_type data_type, bool error)
	Constructor. More...

	Histogram (MEM_ROOT mem_root, const Histogram &other, bool error)
	Copy constructor. More...

bool	histogram_data_type_to_json (Json_object *json_object) const
	Write the data type of this histogram into a JSON object. More...

template<class T >
bool	extract_json_dom_value (const Json_dom json_dom, T out, Error_context *context)
	Return the value that is contained in the JSON DOM object. More...

virtual bool	json_to_histogram (const Json_object &json_object, Error_context *context)=0
	Populate the histogram with data from the provided JSON object. More...

Static Protected Member Functions
static constexpr const char *	buckets_str ()
	String representation of the JSON field "buckets". More...

static constexpr const char *	last_updated_str ()
	String representation of the JSON field "last-updated". More...

static constexpr const char *	null_values_str ()
	String representation of the JSON field "null-values". More...

static constexpr const char *	sampling_rate_str ()

static constexpr const char *	numer_of_buckets_specified_str ()
	String representation of the JSON field "number-of-buckets-specified". More...

static constexpr const char *	auto_update_str ()
	String representation of the JSON field "auto-update". More...

Protected Attributes
double	m_sampling_rate

double	m_null_values_fraction
	The fraction of NULL values in the histogram (between 0.0 and 1.0). More...

const CHARSET_INFO *	m_charset
	The character set for the data stored. More...

size_t	m_num_buckets_specified
	The number of buckets originally specified. More...

Private Member Functions
bool	get_raw_selectivity (Item *items, size_t item_count, enum_operator op, double selectivity) const
	An internal function for getting a selectivity estimate prior to adustment. More...

bool	get_selectivity_dispatcher (Item item, const enum_operator op, const TYPELIB typelib, double *selectivity) const
	An internal function for getting the selecitvity estimation. More...

template<class T >
double	get_less_than_selectivity_dispatcher (const T &value) const
	An internal function for getting the selecitvity estimation. More...

template<class T >
double	get_greater_than_selectivity_dispatcher (const T &value) const

template<class T >
double	get_equal_to_selectivity_dispatcher (const T &value) const

template<class T >
double	apply_operator (const enum_operator op, const T &value) const
	An internal function for applying the correct function for the given operator. More...

Private Attributes
MEM_ROOT *	m_mem_root
	The MEM_ROOT where the histogram contents will be allocated. More...

const enum_histogram_type	m_hist_type
	The type of this histogram. More...

const Value_map_type	m_data_type
	The type of the data this histogram contains. More...

LEX_CSTRING	m_database_name
	Name of the database this histogram represents. More...

LEX_CSTRING	m_table_name
	Name of the table this histogram represents. More...

LEX_CSTRING	m_column_name
	Name of the column this histogram represents. More...

bool	m_auto_update
	True if the histogram was created with the AUTO UPDATE option, false if MANUAL UPDATE. More...

Detailed Description

Histogram base class.

This is an abstract class containing the interface and shared code for concrete histogram subclasses.

Histogram subclasses (Singleton, Equi_height) are constructed through factory methods in order to catch memory allocation errors during construction.

The histogram subclasses have no public copy or move constructors. In order to copy a histogram onto a given MEM_ROOT, use the public clone method. The clone method ensures that members of the histogram, such String type buckets, are also allocated on the given MEM_ROOT. Modifications to these methods need to be careful that histogram buckets are cloned/copied correctly.

Member Enumeration Documentation

◆ enum_histogram_type

enum class histograms::Histogram::enum_histogram_type

strong

All supported histogram types in MySQL.

Enumerator
EQUI_HEIGHT
SINGLETON

Constructor & Destructor Documentation

◆ Histogram() [1/4]

histograms::Histogram::Histogram	(	MEM_ROOT *	mem_root,
		const std::string &	db_name,
		const std::string &	tbl_name,
		const std::string &	col_name,
		enum_histogram_type	type,
		Value_map_type	data_type,
		bool *	error
	)

protected

Constructor.

Parameters

	mem_root	the mem_root where the histogram contents will be allocated
	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
	type	the histogram type (equi-height, singleton)
	data_type	the type of data that this histogram contains
[out]	error	is set to true if an error occurs

◆ Histogram() [2/4]

histograms::Histogram::Histogram	(	MEM_ROOT *	mem_root,
		const Histogram &	other,
		bool *	error
	)

protected

Copy constructor.

This will make a copy of the provided histogram onto the provided MEM_ROOT.

Parameters

	mem_root	the mem_root where the histogram contents will be allocated
	other	the histogram to copy
[out]	error	is set to true if an error occurs

◆ Histogram() [3/4]

histograms::Histogram::Histogram ( )

delete

◆ Histogram() [4/4]

histograms::Histogram::Histogram ( const Histogram & other )

delete

◆ ~Histogram()

virtual histograms::Histogram::~Histogram ( )

virtualdefault

Destructor.

Member Function Documentation

◆ apply_operator()

template<class T >

double histograms::Histogram::apply_operator	(	const enum_operator	op,
		const T &	value
	)		const

private

An internal function for applying the correct function for the given operator.

Parameters

op	The operator to apply
value	The value to find the selectivity for.

Returns: The estimated selectivity, between 0.0 and 1.0 inclusive.

◆ auto_update_str()

static constexpr const char * histograms::Histogram::auto_update_str ( )

inlinestaticconstexprprotected

String representation of the JSON field "auto-update".

◆ buckets_str()

static constexpr const char * histograms::Histogram::buckets_str ( )

inlinestaticconstexprprotected

String representation of the JSON field "buckets".

◆ clone()

virtual Histogram * histograms::Histogram::clone ( MEM_ROOT * mem_root ) const

pure virtual

Make a clone of the current histogram.

Parameters

mem_root the MEM_ROOT on which the new histogram will be allocated.

Returns: a histogram allocated on the provided MEM_ROOT. Returns nullptr on error.

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ collation_id_str()

static constexpr const char * histograms::Histogram::collation_id_str ( )

inlinestaticconstexpr

String representation of the JSON field "collation-id".

◆ data_type_str()

static constexpr const char * histograms::Histogram::data_type_str ( )

inlinestaticconstexpr

String representation of the JSON field "data-type".

◆ equi_height_str()

static constexpr const char * histograms::Histogram::equi_height_str ( )

inlinestaticconstexpr

String representation of the histogram type EQUI-HEIGHT.

◆ extract_json_dom_value() [1/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		double *	out,
		Error_context *	context
	)

◆ extract_json_dom_value() [2/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		longlong *	out,
		Error_context *	context
	)

◆ extract_json_dom_value() [3/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		my_decimal *	out,
		Error_context *	context
	)

◆ extract_json_dom_value() [4/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		MYSQL_TIME *	out,
		Error_context *	context
	)

◆ extract_json_dom_value() [5/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		String *	out,
		Error_context *	context
	)

◆ extract_json_dom_value() [6/7]

template<class T >

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		T *	out,
		Error_context *	context
	)

protected

Return the value that is contained in the JSON DOM object.

For most types, this function simply returns the contained value. For String values, the value is allocated on this histograms MEM_ROOT before it is returned. This allows the String value to survive the entire lifetime of the histogram object.

Parameters

json_dom	the JSON DOM object to extract the value from
out	the value from the JSON DOM object
context	error context for validation

Returns: true on error, false otherwise

◆ extract_json_dom_value() [7/7]

template<>

bool histograms::Histogram::extract_json_dom_value	(	const Json_dom *	json_dom,
		ulonglong *	out,
		Error_context *	context
	)

◆ get_auto_update()

bool histograms::Histogram::get_auto_update ( ) const

inline

Returns: True if automatic updates are enabled for the histogram, false otherwise.

◆ get_character_set()

const CHARSET_INFO * histograms::Histogram::get_character_set ( ) const

inline

Returns: the character set for the data this histogram contains

◆ get_column_name()

const LEX_CSTRING histograms::Histogram::get_column_name ( ) const

inline

Returns: name of the column this histogram represents

◆ get_data_type()

Value_map_type histograms::Histogram::get_data_type ( ) const

inline

Returns: the data type that this histogram contains

◆ get_database_name()

const LEX_CSTRING histograms::Histogram::get_database_name ( ) const

inline

Returns: name of the database this histogram represents

◆ get_equal_to_selectivity_dispatcher()

template<class T >

double histograms::Histogram::get_equal_to_selectivity_dispatcher ( const T & value ) const

private

See also: get_less_than_selectivity_dispatcher

◆ get_greater_than_selectivity_dispatcher()

template<class T >

double histograms::Histogram::get_greater_than_selectivity_dispatcher ( const T & value ) const

private

See also: get_less_than_selectivity_dispatcher

◆ get_histogram_type()

enum_histogram_type histograms::Histogram::get_histogram_type ( ) const

inline

Returns: type of this histogram

◆ get_less_than_selectivity_dispatcher()

template<class T >

double histograms::Histogram::get_less_than_selectivity_dispatcher ( const T & value ) const

private

An internal function for getting the selecitvity estimation.

This function will cast the histogram to the correct class (using down_cast) and pass the given value on to the correct selectivity estimation function for that class.

Parameters

value The value to estimate the selectivity for.

Returns: The estimated selectivity, between 0.0 and 1.0 inclusive.

◆ get_mem_root()

MEM_ROOT * histograms::Histogram::get_mem_root ( ) const

inline

Returns: the MEM_ROOT that this histogram uses for allocations

◆ get_non_null_values_fraction()

double histograms::Histogram::get_non_null_values_fraction ( ) const

inline

Returns: the fraction of non-null values in the histogram.

◆ get_null_values_fraction()

double histograms::Histogram::get_null_values_fraction ( ) const

Returns: the fraction of NULL values, in the range [0.0, 1.0]

◆ get_num_buckets()

virtual size_t histograms::Histogram::get_num_buckets ( ) const

pure virtual

Returns: number of buckets in this histogram

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ get_num_buckets_specified()

size_t histograms::Histogram::get_num_buckets_specified ( ) const

inline

Returns: number of buckets originally specified by the user. This may be higher than the actual number of buckets in the histogram.

◆ get_num_distinct_values()

virtual size_t histograms::Histogram::get_num_distinct_values ( ) const

pure virtual

Get the estimated number of distinct non-NULL values.

Returns: number of distinct non-NULL values

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ get_raw_selectivity()

bool histograms::Histogram::get_raw_selectivity	(	Item **	items,
		size_t	item_count,
		enum_operator	op,
		double *	selectivity
	)		const

private

An internal function for getting a selectivity estimate prior to adustment.

See also: get_selectivity() for details.

◆ get_sampling_rate()

double histograms::Histogram::get_sampling_rate ( ) const

inline

Returns: the sampling rate used to generate this histogram

◆ get_selectivity()

bool histograms::Histogram::get_selectivity	(	Item **	items,
		size_t	item_count,
		enum_operator	op,
		double *	selectivity
	)		const

Get selectivity estimation.

This function will try and get the selectivity estimation for a predicate on the form "COLUMN OPERATOR CONSTANT", for instance "SELECT * FROM t1 WHERE col1 > 23;".

This function will take care of several of things, for instance checking that the value we are estimating the selectivity for is a constant value.

The order of the Items provided does not matter. For instance, of the operator argument given is "EQUALS_TO", it does not matter if the constant value is provided as the first or the second argument; this function will take care of this.

Parameters

	items	an array of items that contains both the field we are estimating the selectivity for, as well as the user-provided constant values.
	item_count	the number of Items in the Item array.
	op	the predicate operator
[out]	selectivity	the calculated selectivity if a usable histogram was found

Return values

true	if an error occurred (the Item provided was not a constant value or similar).

Returns: false if success

◆ get_selectivity_dispatcher()

bool histograms::Histogram::get_selectivity_dispatcher	(	Item *	item,
		const enum_operator	op,
		const TYPELIB *	typelib,
		double *	selectivity
	)		const

private

An internal function for getting the selecitvity estimation.

This function will read/evaluate the value from the given Item, and pass this value on to the correct selectivity estimation function based on the data type of the histogram. For instance, if the data type of the histogram is INT, we will call "val_int" on the Item to evaluate the value as an integer and pass this value on to the next function.

Parameters

	item	The Item to read/evaluate the value from.
	op	The operator we are estimating the selectivity for.
	typelib	In the case of ENUM or SET data type, this parameter holds the type information. This is needed in order to map a string representation of an ENUM/SET value into its correct integer representation (ENUM/SET values are stored as integer values in the histogram).
[out]	selectivity	The estimated selectivity, between 0.0 and 1.0 inclusive.

Returns: true on error (i.e the provided item was NULL), false on success.

◆ get_table_name()

const LEX_CSTRING histograms::Histogram::get_table_name ( ) const

inline

Returns: name of the table this histogram represents

◆ histogram_data_type_to_json()

bool histograms::Histogram::histogram_data_type_to_json ( Json_object * json_object ) const

protected

Write the data type of this histogram into a JSON object.

Parameters

json_object the JSON object where we will write the histogram data type

Returns: true on error, false otherwise

◆ histogram_to_json()

bool histograms::Histogram::histogram_to_json ( Json_object * json_object ) const

pure virtual

Converts the histogram to a JSON object.

Parameters

[in,out] json_object output where the histogram is to be stored. The caller is responsible for allocating/deallocating the JSON object

Returns: true on error, false otherwise

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ histogram_type_str()

static constexpr const char * histograms::Histogram::histogram_type_str ( )

inlinestaticconstexpr

String representation of the JSON field "histogram-type".

◆ histogram_type_to_str()

virtual std::string histograms::Histogram::histogram_type_to_str ( ) const

pure virtual

Returns the histogram type as a readable string.

Returns: a readable string representation of the histogram type

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ json_to_histogram() [1/2]

bool histograms::Histogram::json_to_histogram	(	const Json_object &	json_object,
		Error_context *	context
	)

protectedpure virtual

Populate the histogram with data from the provided JSON object.

The base class also provides an implementation that subclasses must call in order to populate fields that are shared among all histogram types (character set, null values fraction).

Parameters

json_object	the JSON object to read the histogram data from
context	error context for validation

Returns: true on error, false otherwise

Implemented in histograms::Equi_height< T >, and histograms::Singleton< T >.

◆ json_to_histogram() [2/2]

Histogram * histograms::Histogram::json_to_histogram	(	MEM_ROOT *	mem_root,
		const std::string &	schema_name,
		const std::string &	table_name,
		const std::string &	column_name,
		const Json_object &	json_object,
		Error_context *	context
	)

static

Converts JSON object to a histogram.

Parameters

mem_root	MEM_ROOT where the histogram will be allocated
schema_name	the schema name
table_name	the table name
column_name	the column name
json_object	output where the histogram is stored
context	error context for validation

Returns: nullptr on error. Otherwise a histogram allocated on the provided MEM_ROOT.

◆ last_updated_str()

static constexpr const char * histograms::Histogram::last_updated_str ( )

inlinestaticconstexprprotected

String representation of the JSON field "last-updated".

◆ null_values_str()

static constexpr const char * histograms::Histogram::null_values_str ( )

inlinestaticconstexprprotected

String representation of the JSON field "null-values".

◆ numer_of_buckets_specified_str()

static constexpr const char * histograms::Histogram::numer_of_buckets_specified_str ( )

inlinestaticconstexprprotected

String representation of the JSON field "number-of-buckets-specified".

◆ sampling_rate_str()

static constexpr const char * histograms::Histogram::sampling_rate_str ( )

inlinestaticconstexprprotected

◆ set_auto_update()

void histograms::Histogram::set_auto_update ( bool auto_update )

inline

Sets the auto update property for the histogram.

◆ singleton_str()

static constexpr const char * histograms::Histogram::singleton_str ( )

inlinestaticconstexpr

String representation of the histogram type SINGLETON.

◆ store_histogram()

bool histograms::Histogram::store_histogram ( THD * thd ) const

Store this histogram to persistent storage (data dictionary).

The MEM_ROOT that the histogram is allocated on is transferred to the dictionary.

Parameters

thd	Thread handler.

Returns: false on success, true on error.

◆ m_table_name

LEX_CSTRING histograms::Histogram::m_table_name

private

Name of the table this histogram represents.

The documentation for this class was generated from the following files:

sql/histograms/histogram.h
sql/histograms/histogram.cc

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ enum_histogram_type

Constructor & Destructor Documentation

◆ Histogram() [1/4]

◆ Histogram() [2/4]

◆ Histogram() [3/4]

◆ Histogram() [4/4]

◆ ~Histogram()

Member Function Documentation

◆ apply_operator()

◆ auto_update_str()

◆ buckets_str()

◆ clone()

◆ collation_id_str()

◆ data_type_str()

◆ equi_height_str()

◆ extract_json_dom_value() [1/7]

◆ extract_json_dom_value() [2/7]

◆ extract_json_dom_value() [3/7]

◆ extract_json_dom_value() [4/7]

◆ extract_json_dom_value() [5/7]

◆ extract_json_dom_value() [6/7]

◆ extract_json_dom_value() [7/7]

◆ get_auto_update()

◆ get_character_set()

◆ get_column_name()

◆ get_data_type()

◆ get_database_name()

◆ get_equal_to_selectivity_dispatcher()

◆ get_greater_than_selectivity_dispatcher()

◆ get_histogram_type()

◆ get_less_than_selectivity_dispatcher()

◆ get_mem_root()

◆ get_non_null_values_fraction()

◆ get_null_values_fraction()

◆ get_num_buckets()

◆ get_num_buckets_specified()

◆ get_num_distinct_values()

◆ get_raw_selectivity()

◆ get_sampling_rate()

◆ get_selectivity()

◆ get_selectivity_dispatcher()

◆ get_table_name()

◆ histogram_data_type_to_json()

◆ histogram_to_json()

◆ histogram_type_str()

◆ histogram_type_to_str()

◆ json_to_histogram() [1/2]

◆ json_to_histogram() [2/2]

◆ last_updated_str()

◆ null_values_str()

◆ numer_of_buckets_specified_str()

◆ sampling_rate_str()

◆ set_auto_update()

◆ singleton_str()

◆ store_histogram()

Member Data Documentation

◆ m_auto_update

◆ m_charset

◆ m_column_name

◆ m_data_type

◆ m_database_name

◆ m_hist_type

◆ m_mem_root

◆ m_null_values_fraction

◆ m_num_buckets_specified

◆ m_sampling_rate

◆ m_table_name