public interface IndexMapping
double values and int values that imposes relative guarantees on the composition
of value(int) and index(double). Specifically, for any value v between minIndexableValue()
and maxIndexableValue(), implementations of IndexMapping must be such that value(index(v))
is close to v with a relative error that is less than relativeAccuracy().
In implementations of IndexMapping, there generally is a trade-off between the cost of computing the index
and the number of indices that are required to cover a given range of values (memory optimality). The most
memory-optimal mapping is the LogarithmicMapping, but it requires the costly evaluation of the logarithm
when computing the index. Other mappings can approximate the logarithmic mapping, while being less computationally
costly. The following table shows the characteristics of a few implementations of IndexMapping,
highlighting the above-mentioned trade-off.
| Mapping | Index usage overhead given actual guarantee | Max index usage overhead given requested guarantee | Computational cost (rough estimate) |
LogarithmicMapping |
0% (optimal) | 0% (optimal) | 100% (reference) |
CubicallyInterpolatedMapping |
~1% (7/(10*log(2))-1) |
~1% (7/(10*log(2))-1) |
~30% |
QuadraticallyInterpolatedMapping |
~8% (3/(4*log(2))-1) |
~8% (3/(4*log(2))-1) |
~25% |
LinearlyInterpolatedMapping |
~44% (1/log(2)-1) |
~44% (1/log(2)-1) |
~20% |
BitwiseLinearlyInterpolatedMapping |
~44% (1/log(2)-1) |
~189% (2/log(2)-1) |
~15% |
CubicallyInterpolatedMapping, which uses a polynomial of degree 3 to approximate the logarithm is a good
compromise as its memory overhead compared to the optimal logarithmic mapping is only 1%, and it is about 3 times
faster than the logarithmic mapping. Using a polynomial of higher degree would not yield a significant gain in memory
efficiency (less than 1%), while it would degrade its insertion speed to some extent.
| Modifier and Type | Method and Description |
|---|---|
static IndexMapping |
fromProto(com.datadoghq.sketch.ddsketch.proto.IndexMapping proto)
Returns an instance of
IndexMapping that matches the provided protobuf representation. |
int |
index(double value) |
double |
maxIndexableValue() |
double |
minIndexableValue() |
double |
relativeAccuracy() |
com.datadoghq.sketch.ddsketch.proto.IndexMapping |
toProto()
Generates a protobuf representation of this
IndexMapping. |
double |
value(int index) |
int index(double value)
double value(int index)
double relativeAccuracy()
double minIndexableValue()
double maxIndexableValue()
com.datadoghq.sketch.ddsketch.proto.IndexMapping toProto()
IndexMapping.IndexMappingstatic IndexMapping fromProto(com.datadoghq.sketch.ddsketch.proto.IndexMapping proto)
IndexMapping that matches the provided protobuf representation.proto - the protobuf representation of an IndexMappingIndexMapping that matches the protobuf representation