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

  • Field Details

  • Method Details

    • getInstance

      public static <T> ItemsUnion<T> getInstance​(Comparator<? super T> comparator)
      Create an instance of ItemsUnion with the default k
      Type Parameters:
      T - type of item
      Parameters:
      comparator - to compare items
      Returns:
      an instance of ItemsUnion

    • getInstance

      public static <T> ItemsUnion<T> getInstance​(int maxK, Comparator<? super T> comparator)
      Create an instance of ItemsUnion
      Type Parameters:
      T - type of item
      Parameters:
      maxK - determines the accuracy and size of the union and is a maximum value. 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 different values of k.
      comparator - to compare items
      Returns:
      an instance of ItemsUnion

    • getInstance

      public static <T> ItemsUnion<T> getInstance​(org.apache.datasketches.memory.Memory srcMem, Comparator<? super T> comparator, ArrayOfItemsSerDe<T> serDe)
      Heapify the given srcMem into a Union object.
      Type Parameters:
      T - type of item
      Parameters:
      srcMem - the given srcMem. A reference to srcMem will not be maintained internally.
      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 - type of item
      Parameters:
      sketch - the basis of the union
      Returns:
      an instance of ItemsUnion

    • update

      public void update​(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 values be a power of 2. This is easily satisfied if each of the K values is 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.

    • update

      public void update​(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 values be a power of 2. This is easily satisfied if each of the K values is 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 double (or float) data Item.
      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.

    • 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