Package org.apache.datasketches.quantiles

Class ItemsUnion<T>

java.lang.Object
org.apache.datasketches.quantiles.ItemsUnion<T>
Type Parameters:
T - type of item
public final class ItemsUnion<T> extends Object
The API for Union operations for generic ItemsSketches
Author:
Lee Rhodes, Alexander Saydakov

  • Method Details

    • getInstance

      public static <T> ItemsUnion<T> getInstance(Class<T> clazz, Comparator<? super T> comparator)
      Create an instance of ItemsUnion with the default k
      Type Parameters:
      T - The sketch data type
      Parameters:
      clazz - The sketch class type
      comparator - to compare items
      Returns:
      an instance of ItemsUnion

    • getInstance

      public static <T> ItemsUnion<T> getInstance(Class<T> clazz, int maxK, Comparator<? super T> comparator)
      Create an instance of ItemsUnion
      Type Parameters:
      T - The sketch data type
      Parameters:
      clazz - The sketch class type
      maxK - determines the accuracy and size of the union and is a maximum. The effective k can be smaller due to unions with smaller k sketches. It is recommended that maxK be a power of 2 to enable unioning of sketches with a different k.
      comparator - to compare items
      Returns:
      an instance of ItemsUnion

    • getInstance

      public static <T> ItemsUnion<T> getInstance(Class<T> clazz, org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe)
      Heapify the given srcMem into a Union object.
      Type Parameters:
      T - The sketch data type
      Parameters:
      clazz - The sketch class type A reference to srcMem will not be maintained internally.
      srcMem - the given srcMem.
      comparator - to compare items
      serDe - an instance of ArrayOfItemsSerDe
      Returns:
      an instance of ItemsUnion

    • getInstance

      public static <T> ItemsUnion<T> getInstance(ItemsSketch<T> sketch)
      Create an instance of ItemsUnion based on ItemsSketch
      Type Parameters:
      T - The sketch data type
      Parameters:
      sketch - the basis of the union
      Returns:
      an instance of ItemsUnion

    • union

      public void union(ItemsSketch<T> sketchIn)
      Iterative union operation, which means this method can be repeatedly called. Merges the given sketch into this union object. The given sketch is not modified. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

      It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

      Parameters:
      sketchIn - the sketch to be merged into this one.

    • union

      public void union(org.apache.datasketches.memory.Memory srcMem, ArrayOfItemsSerDe<T> serDe)
      Iterative union operation, which means this method can be repeatedly called. Merges the given Memory image of a ItemsSketch into this union object. The given Memory object is not modified and a link to it is not retained. It is required that the ratio of the two K's be a power of 2. This is easily satisfied if each of the K's are already a power of 2. If the given sketch is null or empty it is ignored.

      It is required that the results of the union operation, which can be obtained at any time, is obtained from getResult().

      Parameters:
      srcMem - Memory image of sketch to be merged
      serDe - an instance of ArrayOfItemsSerDe

    • update

      public void update(T dataItem)
      Update this union with the given dataItem.
      Parameters:
      dataItem - The given datum.

    • getResult

      public ItemsSketch<T> getResult()
      Gets the result of this Union operation as a copy of the internal state. This enables further union update operations on this state.
      Returns:
      the result of this Union operation

    • getResultAndReset

      public ItemsSketch<T> getResultAndReset()
      Gets the result of this Union operation (without a copy) and resets this Union to the virgin state.
      Returns:
      the result of this Union operation and reset.

    • reset

      public void reset()
      Resets this Union to a virgin state. Keeps maxK, comparator and clazz

    • isEmpty

      public boolean isEmpty()
      Returns true if this union is empty
      Returns:
      true if this union is empty

    • isDirect

      public boolean isDirect()
      Returns true if this union is direct
      Returns:
      true if this union is direct

    • getMaxK

      public int getMaxK()
      Returns the configured maxK of this Union.
      Returns:
      the configured maxK of this Union.

    • getEffectiveK

      public int getEffectiveK()
      Returns the effective k of this Union.
      Returns:
      the effective k of this Union.

    • toString

      public String toString()
      Returns summary information about the backing sketch.
      Overrides:
      toString in class Object

    • toString

      public String toString(boolean sketchSummary, boolean dataDetail)
      Returns summary information about the backing sketch. Used for debugging.
      Parameters:
      sketchSummary - if true includes sketch summary
      dataDetail - if true includes data detail
      Returns:
      summary information about the sketch.

    • toByteArray

      public byte[] toByteArray(ArrayOfItemsSerDe<T> serDe)
      Serialize this union to a byte array. Result is an ItemsSketch, serialized in an unordered, non-compact form. The resulting byte[] can be passed to getInstance for either a sketch or union.
      Parameters:
      serDe - an instance of ArrayOfItemsSerDe
      Returns:
      byte array of this union