java.lang.Object
org.elasticsearch.cluster.routing.TsidBuilder
A builder for creating time series identifiers (TSIDs) based on dimensions.
This class allows adding various types of dimensions (int, long, double, boolean, string, bytes)
and builds a TSID that is a hash of the dimension names and values.
Important properties of TSIDs are that they cluster similar time series together,
which helps with storage efficiency,
and that they minimize the risk of hash collisions.
At the same time, they should be short to be efficient in terms of storage and processing.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceTsidBuilder.ThrowingTsidFunnel<T,E extends Exception> A functional interface that describes how objects of a complex type are added to a TSID, allowing for exceptions to be thrown during the process.static interfaceA functional interface that describes how objects of a complex type are added to a TSID. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription<T,E extends Exception>
TsidBuilderadd(T value, TsidBuilder.ThrowingTsidFunnel<T, E> funnel) Adds a value to the TSID using a funnel that can throw exceptions.<T> TsidBuilderadd(T value, TsidBuilder.TsidFunnel<T> funnel) Adds a value to the TSID using a funnel.addAll(TsidBuilder other) Adds all dimensions from another TsidBuilder to this one.addBooleanDimension(String path, boolean value) Adds a boolean dimension to the TSID.addDoubleDimension(String path, double value) Adds a double dimension to the TSID.addIntDimension(String path, int value) Adds an integer dimension to the TSID.addLongDimension(String path, long value) Adds a long dimension to the TSID.addStringDimension(String path, byte[] utf8Bytes, int offset, int length) Adds a string dimension to the TSID using a byte array.addStringDimension(String path, String value) Adds a string dimension to the TSID.addStringDimension(String path, XContentString.UTF8Bytes value) Adds a string dimension to the TSID.org.apache.lucene.util.BytesRefBuilds a time series identifier (TSID) based on the dimensions added to this builder.hash()Computes the hash of the dimensions added to this builder.static TsidBuilder
-
Constructor Details
-
TsidBuilder
public TsidBuilder()
-
-
Method Details
-
newBuilder
-
addIntDimension
Adds an integer dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the integer value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addLongDimension
Adds a long dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the long value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addDoubleDimension
Adds a double dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the double value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addBooleanDimension
Adds a boolean dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the boolean value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addStringDimension
Adds a string dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the string value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addStringDimension
Adds a string dimension to the TSID.- Parameters:
path- the path of the dimensionvalue- the UTF8Bytes value of the dimension- Returns:
- the TsidBuilder instance for method chaining
-
addStringDimension
Adds a string dimension to the TSID using a byte array. The value is provided as UTF-8 encoded bytes[].- Parameters:
path- the path of the dimensionutf8Bytes- the UTF-8 encoded bytes of the string valueoffset- the offset in the byte array where the string startslength- the length of the string in bytes- Returns:
- the TsidBuilder instance for method chaining
-
add
Adds a value to the TSID using a funnel. This allows for complex types to be added to the TSID.- Type Parameters:
T- the type of the value- Parameters:
value- the value to addfunnel- the funnel that describes how to add the value- Returns:
- the TsidBuilder instance for method chaining
-
add
public <T,E extends Exception> TsidBuilder add(T value, TsidBuilder.ThrowingTsidFunnel<T, E> funnel) throws EAdds a value to the TSID using a funnel that can throw exceptions. This allows for complex types to be added to the TSID.- Type Parameters:
T- the type of the valueE- the type of exception that can be thrown- Parameters:
value- the value to addfunnel- the funnel that describes how to add the value- Returns:
- the TsidBuilder instance for method chaining
- Throws:
E- if an exception occurs while adding the value
-
addAll
Adds all dimensions from another TsidBuilder to this one. If the other builder is null or has no dimensions, this method does nothing.- Parameters:
other- the other TsidBuilder to add dimensions from- Returns:
- this TsidBuilder instance for method chaining
-
hash
Computes the hash of the dimensions added to this builder. The hash is a 128-bit value that is computed based on the dimension names and values.- Returns:
- a HashValue128 representing the hash of the dimensions
- Throws:
IllegalArgumentException- if no dimensions have been added
-
buildTsid
public org.apache.lucene.util.BytesRef buildTsid()Builds a time series identifier (TSID) based on the dimensions added to this builder. This is a slight adaptation ofRoutingPathFields.buildHash()but creates shorter tsids. The TSID is a hash that includes:- A hash of the dimension field names (4 bytes). This is to cluster time series that are using the same dimensions together, which makes the encodings more effective.
- A hash of the dimension field values (1 byte each, up to a maximum of 16 fields). This is to cluster time series with similar values together, also helping with making encodings more effective.
- A hash of all names and values combined (16 bytes). This is to avoid hash collisions.
- Returns:
- a BytesRef containing the TSID
- Throws:
IllegalArgumentException- if no dimensions have been added
-