MySQL 8.3.0
Source Code Documentation
histograms::Histogram Class Referenceabstract

Histogram base class. More...

#include <histogram.h>

Inheritance diagram for histograms::Histogram:
[legend]

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_ROOTget_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_INFOget_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
 
virtual bool histogram_to_json (Json_object *json_object) const =0
 Converts the histogram to a JSON object. More...
 
virtual Histogramclone (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 Histogramjson_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...
 

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_INFOm_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_ROOTm_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...
 

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

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_rootthe mem_root where the histogram contents will be allocated
db_namename of the database this histogram represents
tbl_namename of the table this histogram represents
col_namename of the column this histogram represents
typethe histogram type (equi-height, singleton)
data_typethe type of data that this histogram contains
[out]erroris 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_rootthe mem_root where the histogram contents will be allocated
otherthe histogram to copy
[out]erroris 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
opThe operator to apply
valueThe value to find the selectivity for.
Returns
The estimated selectivity, between 0.0 and 1.0 inclusive.

◆ 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_rootthe 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_domthe JSON DOM object to extract the value from
outthe value from the JSON DOM object
contexterror 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_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
valueThe 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
itemsan array of items that contains both the field we are estimating the selectivity for, as well as the user-provided constant values.
item_countthe number of Items in the Item array.
opthe predicate operator
[out]selectivitythe calculated selectivity if a usable histogram was found
Return values
trueif 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
itemThe Item to read/evaluate the value from.
opThe operator we are estimating the selectivity for.
typelibIn 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]selectivityThe 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_objectthe 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_objectoutput 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_objectthe JSON object to read the histogram data from
contexterror 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_rootMEM_ROOT where the histogram will be allocated
schema_namethe schema name
table_namethe table name
column_namethe column name
json_objectoutput where the histogram is stored
contexterror 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

◆ 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).

Parameters
thdThread handler.
Returns
false on success, true on error.

Member Data Documentation

◆ m_charset

const CHARSET_INFO* histograms::Histogram::m_charset
protected

The character set for the data stored.

◆ m_column_name

LEX_CSTRING histograms::Histogram::m_column_name
private

Name of the column this histogram represents.

◆ m_data_type

const Value_map_type histograms::Histogram::m_data_type
private

The type of the data this histogram contains.

◆ m_database_name

LEX_CSTRING histograms::Histogram::m_database_name
private

Name of the database this histogram represents.

◆ m_hist_type

const enum_histogram_type histograms::Histogram::m_hist_type
private

The type of this histogram.

◆ m_mem_root

MEM_ROOT* histograms::Histogram::m_mem_root
private

The MEM_ROOT where the histogram contents will be allocated.

◆ m_null_values_fraction

double histograms::Histogram::m_null_values_fraction
protected

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

◆ m_num_buckets_specified

size_t histograms::Histogram::m_num_buckets_specified
protected

The number of buckets originally specified.

◆ m_sampling_rate

double histograms::Histogram::m_sampling_rate
protected

◆ 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: