ClickHouse/dbms/include/DB/Common/HyperLogLogBiasEstimator.h

#pragma once

#include <DB/Common/Exception.h>

#include <algorithm>
#include <limits>
#include <tuple>
#include <type_traits>

/** Этот класс предоставляет способ, чтобы оценить погрешность результата применения алгоритма HyperLogLog.
  * Эмирические наблюдения показывают, что большие погрешности возникают при E < 5 * 2^precision, где
  * E - возвращаемое значение алгоритмом HyperLogLog, и precision - параметр точности HyperLogLog.
  * См. "HyperLogLog in Practice: Algorithmic Engineering of a State of The Art Cardinality Estimation Algorithm".
  * (S. Heule et al., Proceedings of the EDBT 2013 Conference).
  */
template <typename BiasData>
class HyperLogLogBiasEstimator
{
public:
	static constexpr bool isTrivial()
	{
		return false;
	}

	/// Предельное количество уникальных значений до которого должна примениться поправка
	/// из алгоритма LinearCounting.
	static double getThreshold()
	{
		return BiasData::getThreshold();
	}

	/// Вернуть оценку погрешности.
	static double getBias(double raw_estimate)
	{
		const auto & estimates = BiasData::getRawEstimates();
		const auto & biases = BiasData::getBiases();

		auto it = std::lower_bound(estimates.begin(), estimates.end(), raw_estimate);

		if (it == estimates.end())
		{
			return biases[estimates.size() - 1];
		}
		else if (*it == raw_estimate)
		{
			size_t index = std::distance(estimates.begin(), it);
			return biases[index];
		}
		else if (it == estimates.begin())
		{
			return biases[0];
		}
		else
		{
			/// Получаем оценку погрешности путём линейной интерполяции.
			size_t index = std::distance(estimates.begin(), it);

			double estimate1 = estimates[index - 1];
			double estimate2 = estimates[index];

			double bias1 = biases[index - 1];
			double bias2 = biases[index];
			/// Предполагается, что условие estimate1 < estimate2 всегда выполнено.
			double slope = (bias2 - bias1) / (estimate2 - estimate1);

			return bias1 + slope * (raw_estimate - estimate1);
		}
	}

private:
	/// Статические проверки.
	using TRawEstimatesRef = decltype(BiasData::getRawEstimates());
	using TRawEstimates = typename std::remove_reference<TRawEstimatesRef>::type;

	using TBiasDataRef = decltype(BiasData::getBiases());
	using TBiasData = typename std::remove_reference<TBiasDataRef>::type;

	static_assert(std::is_same<TRawEstimates, TBiasData>::value, "Bias estimator data have inconsistent types");
	static_assert(std::tuple_size<TRawEstimates>::value > 0, "Bias estimator has no raw estimate data");
	static_assert(std::tuple_size<TBiasData>::value > 0, "Bias estimator has no bias data");
	static_assert(std::tuple_size<TRawEstimates>::value == std::tuple_size<TBiasData>::value,
				  "Bias estimator has inconsistent data");
};

/** Тривиальный случай HyperLogLogBiasEstimator: употребляется, если не хотим исправить
  * погрешность. Это имеет смысль при маленьких значениях параметра точности, например 5 или 12.
  * Тогда применяются поправки из оригинальной версии алгоритма HyperLogLog.
  * См. "HyperLogLog: The analysis of a near-optimal cardinality estimation algorithm"
  * (P. Flajolet et al., AOFA '07: Proceedings of the 2007 International Conference on Analysis
  * of Algorithms)
  */
struct TrivialBiasEstimator
{
	static constexpr bool isTrivial()
	{
		return true;
	}

	static double getThreshold()
	{
		return 0.0;
	}

	static double getBias(double raw_estimate)
	{
		return 0.0;
	}
};