Package org.apache.datasketches.tuple

# Class UpdatableSketch<U,S extends UpdatableSummary<U>>

java.lang.Object
org.apache.datasketches.tuple.Sketch<S>
org.apache.datasketches.tuple.UpdatableSketch<U,S>

Type Parameters:
  `U` - Type of the value, which is passed to update method of a Summary
  `S` - Type of the UpdatableSummary<U>

Direct Known Subclasses:
  `ArrayOfStringsSketch`, `DoubleSketch`, `IntegerSketch`

public class UpdatableSketch<U,S extends UpdatableSummary<U>> extends Sketch<S>
An extension of QuickSelectSketch<S>, which can be updated with many types of keys. Summary objects are created using a user-defined SummaryFactory class, which should allow very flexible parameterization if needed. Keys are presented to a sketch along with values of a user-defined update type U. When an entry is inserted into a sketch or a duplicate key is presented to a sketch then summary.update(U value) method will be called. So any kind of user-defined accumulation is possible. Summaries also must know how to copy themselves. Also union and intersection of summaries can be implemented in a sub-class of SummarySetOperations, which will be used in case Union or Intersection of two instances of Tuple Sketch is needed

## Constructor Summary

Constructors
Constructor
Description
`UpdatableSketch(int nomEntries, int lgResizeFactor, float samplingProbability, SummaryFactory<S> summaryFactory)`
This is to create a new instance of an UpdatableQuickSelectSketch.
`UpdatableSketch(org.apache.datasketches.memory.Memory srcMem, SummaryDeserializer<S> deserializer, SummaryFactory<S> summaryFactory)`
Deprecated.
As of 3.0.0, heapifying an UpdatableSketch is deprecated.
`UpdatableSketch(UpdatableSketch<U,S> sketch)`
Copy Constructor

## Method Summary

Modifier and Type
Method
Description
`CompactSketch<S>`
`compact()`
Converts the current state of the sketch into a compact sketch
`UpdatableSketch<U,S>`
`copy()`
`int`
`getCountLessThanThetaLong(long thetaLong)`
Gets the number of hash values less than the given theta expressed as a long.
`int`
`getCurrentCapacity()`
Get current capacity
`int`
`getLgK()`
Get log_base2 of Nominal Entries
`int`
`getNominalEntries()`
Get configured nominal number of entries
`ResizeFactor`
`getResizeFactor()`
Get configured resize factor
`int`
`getRetainedEntries()`
Returns number of retained entries
`float`
`getSamplingProbability()`
Get configured sampling probability
`TupleSketchIterator<S>`
`iterator()`
Returns a SketchIterator
`void`
`reset()`
Resets this sketch an empty state.
`byte[]`
`toByteArray()`
Deprecated.
As of 3.0.0, serializing an UpdatableSketch is deprecated.
`void`
`trim()`
Rebuilds reducing the actual number of entries to the nominal number of entries if needed
`void`
`update(byte[] key, U value)`
Updates this sketch with a byte[] key and U value.
`void`
`update(double key, U value)`
Updates this sketch with a double key and U value.
`void`
`update(int[] key, U value)`
Updates this sketch with a int[] key and U value.
`void`
`update(long[] key, U value)`
Updates this sketch with a long[] key and U value.
`void`
`update(long key, U value)`
Updates this sketch with a long key and U value.
`void`
`update(String key, U value)`
Updates this sketch with a String key and U value.
`void`
`update(ByteBuffer buffer, U value)`
Updates this sketch with a ByteBuffer and U value The value is passed to the update() method of the Summary object associated with the key

### Methods inherited from class org.apache.datasketches.tuple.Sketch

`getEstimate, getEstimate, getLowerBound, getLowerBound, getSummaryFactory, getTheta, getThetaLong, getUpperBound, getUpperBound, isEmpty, isEstimationMode, toString`

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Constructor Details

### UpdatableSketch

public UpdatableSketch(int nomEntries, int lgResizeFactor, float samplingProbability, SummaryFactory<S> summaryFactory)
This is to create a new instance of an UpdatableQuickSelectSketch.

Parameters:
  `nomEntries` - Nominal number of entries. Forced to the nearest power of 2 greater than or equal to the given value.
  `lgResizeFactor` - log2(resizeFactor) - value from 0 to 3:

       0 - no resizing (max size allocated),
       1 - double internal hash table each time it reaches a threshold
       2 - grow four times
       3 - grow eight times (default)

  `samplingProbability` - See Sampling Probability
  `summaryFactory` - An instance of a SummaryFactory.

### UpdatableSketch

@Deprecated public UpdatableSketch(org.apache.datasketches.memory.Memory srcMem, SummaryDeserializer<S> deserializer, SummaryFactory<S> summaryFactory)
Deprecated.
As of 3.0.0, heapifying an UpdatableSketch is deprecated. This capability will be removed in a future release. Heapifying a CompactSketch is not deprecated.
This is to create an instance of a sketch given a serialized form

Parameters:
  `srcMem` - Memory object with data of a serialized UpdatableSketch
  `deserializer` - instance of SummaryDeserializer
  `summaryFactory` - instance of SummaryFactory

### UpdatableSketch

public UpdatableSketch(UpdatableSketch<U,S> sketch)
Copy Constructor

Parameters:
  `sketch` - the sketch to copy

## Method Details

### copy

public UpdatableSketch<U,S> copy()

Returns:
  a deep copy of this sketch

### update

public void update(long key, U value)
Updates this sketch with a long key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given long key
  `value` - The given U value

### update

public void update(double key, U value)
Updates this sketch with a double key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given double key
  `value` - The given U value

### update

public void update(String key, U value)
Updates this sketch with a String key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given String key
  `value` - The given U value

### update

public void update(byte[] key, U value)
Updates this sketch with a byte[] key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given byte[] key
  `value` - The given U value

### update

public void update(ByteBuffer buffer, U value)
Updates this sketch with a ByteBuffer and U value The value is passed to the update() method of the Summary object associated with the key

Parameters:
  `buffer` - The given ByteBuffer key
  `value` - The given U value

### update

public void update(int[] key, U value)
Updates this sketch with a int[] key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given int[] key
  `value` - The given U value

### update

public void update(long[] key, U value)
Updates this sketch with a long[] key and U value. The value is passed to update() method of the Summary object associated with the key

Parameters:
  `key` - The given long[] key
  `value` - The given U value

### getRetainedEntries

public int getRetainedEntries()
Description copied from class: `Sketch`
Returns number of retained entries

Specified by:
  `getRetainedEntries` in class `Sketch<S extends Summary>`
Returns:
  number of retained entries

### getCountLessThanThetaLong

public int getCountLessThanThetaLong(long thetaLong)
Description copied from class: `Sketch`
Gets the number of hash values less than the given theta expressed as a long.

Specified by:
  `getCountLessThanThetaLong` in class `Sketch<S extends Summary>`
Parameters:
  `thetaLong` - the given theta as a long between zero and Long.MAX_VALUE.
Returns:
  the number of hash values less than the given thetaLong.

### getNominalEntries

public int getNominalEntries()
Get configured nominal number of entries

Returns:
  nominal number of entries

### getLgK

public int getLgK()
Get log_base2 of Nominal Entries

Returns:
  log_base2 of Nominal Entries

### getSamplingProbability

public float getSamplingProbability()
Get configured sampling probability

Returns:
  sampling probability

### getCurrentCapacity

public int getCurrentCapacity()
Get current capacity

Returns:
  current capacity

### getResizeFactor

public ResizeFactor getResizeFactor()
Get configured resize factor

Returns:
  resize factor

### trim

public void trim()
Rebuilds reducing the actual number of entries to the nominal number of entries if needed

### reset

public void reset()
Resets this sketch an empty state.

### compact

public CompactSketch<S> compact()
Converts the current state of the sketch into a compact sketch

Specified by:
  `compact` in class `Sketch<S extends Summary>`
Returns:
  compact sketch

### toByteArray

@Deprecated public byte[] toByteArray()
Deprecated.
As of 3.0.0, serializing an UpdatableSketch is deprecated. This capability will be removed in a future release. Serializing a CompactSketch is not deprecated.
This serializes an UpdatableSketch (QuickSelectSketch).

Specified by:
  `toByteArray` in class `Sketch<S extends Summary>`
Returns:
  serialized representation of an UpdatableSketch (QuickSelectSketch).

### iterator

public TupleSketchIterator<S> iterator()
Description copied from class: `Sketch`
Returns a SketchIterator

Specified by:
  `iterator` in class `Sketch<S extends Summary>`
Returns:
  a SketchIterator