Class TsidBuilder

java.lang.Object
org.elasticsearch.cluster.routing.TsidBuilder

public class TsidBuilder extends Object
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.
  • Constructor Details

    • TsidBuilder

      public TsidBuilder()
  • Method Details

    • newBuilder

      public static TsidBuilder newBuilder()
    • addIntDimension

      public TsidBuilder addIntDimension(String path, int value)
      Adds an integer dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the integer value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addLongDimension

      public TsidBuilder addLongDimension(String path, long value)
      Adds a long dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the long value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addDoubleDimension

      public TsidBuilder addDoubleDimension(String path, double value)
      Adds a double dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the double value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addBooleanDimension

      public TsidBuilder addBooleanDimension(String path, boolean value)
      Adds a boolean dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the boolean value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addStringDimension

      public TsidBuilder addStringDimension(String path, String value)
      Adds a string dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the string value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addStringDimension

      public TsidBuilder addStringDimension(String path, XContentString.UTF8Bytes value)
      Adds a string dimension to the TSID.
      Parameters:
      path - the path of the dimension
      value - the UTF8Bytes value of the dimension
      Returns:
      the TsidBuilder instance for method chaining
    • addStringDimension

      public TsidBuilder addStringDimension(String path, byte[] utf8Bytes, int offset, int length)
      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 dimension
      utf8Bytes - the UTF-8 encoded bytes of the string value
      offset - the offset in the byte array where the string starts
      length - the length of the string in bytes
      Returns:
      the TsidBuilder instance for method chaining
    • add

      public <T> TsidBuilder add(T value, TsidBuilder.TsidFunnel<T> funnel)
      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 add
      funnel - 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 E
      Adds 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 value
      E - the type of exception that can be thrown
      Parameters:
      value - the value to add
      funnel - 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

      public TsidBuilder addAll(TsidBuilder other)
      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

      public MurmurHash3.Hash128 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 of RoutingPathFields.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