error bounds and to string UDFs
diff --git a/src/main/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDF.java b/src/main/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDF.java
new file mode 100644
index 0000000..3f3fd33
--- /dev/null
+++ b/src/main/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDF.java
@@ -0,0 +1,49 @@
+/*
+ * Copyright 2019, Verizon Media.
+ * Licensed under the terms of the Apache License 2.0. See LICENSE file at the project root for terms.
+ */
+
+package com.yahoo.sketches.hive.hll;
+
+import java.util.Arrays;
+import java.util.List;
+
+import org.apache.hadoop.hive.ql.exec.Description;
+import org.apache.hadoop.hive.ql.exec.UDF;
+import org.apache.hadoop.io.BytesWritable;
+
+import com.yahoo.memory.Memory;
+import com.yahoo.sketches.hll.HllSketch;
+
+@Description(
+ name = "SketchToEstimateAndErrorBounds",
+ value = "_FUNC_(sketch, kappa)",
+ extended = "Returns an estimate of distinct count and error bounds from a given HllSketch."
+ + " Optional kappa is a number of standard deviations from the mean: 1, 2 or 3 (default 2)."
+ + " The result is three double values: estimate, lower bound and upper bound.")
+public class SketchToEstimateAndErrorBoundsUDF extends UDF {
+
+ private static final int DEFAULT_KAPPA = 2;
+
+ /**
+ * Get an estimate and error bounds from a given HllSketch with default kappa
+ * @param serializedSketch HllSketch in a serialized binary form
+ * @return estimate and bounds
+ */
+ public List<Double> evaluate(final BytesWritable serializedSketch) {
+ return evaluate(serializedSketch, DEFAULT_KAPPA);
+ }
+
+ /**
+ * Get an estimate and error bounds from a given HllSketch with explicit kappa
+ * @param serializedSketch HllSketch in a serialized binary form
+ * @param kappa given number of standard deviations from the mean: 1, 2 or 3
+ * @return estimate and bounds
+ */
+ public List<Double> evaluate(final BytesWritable serializedSketch, final int kappa) {
+ if (serializedSketch == null) { return null; }
+ final HllSketch sketch = HllSketch.wrap(Memory.wrap(serializedSketch.getBytes()));
+ return Arrays.asList(sketch.getEstimate(), sketch.getLowerBound(kappa), sketch.getUpperBound(kappa));
+ }
+
+}
diff --git a/src/main/java/com/yahoo/sketches/hive/hll/SketchToStringUDF.java b/src/main/java/com/yahoo/sketches/hive/hll/SketchToStringUDF.java
new file mode 100644
index 0000000..196a9c8
--- /dev/null
+++ b/src/main/java/com/yahoo/sketches/hive/hll/SketchToStringUDF.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2019, Verizon Media.
+ * Licensed under the terms of the Apache License 2.0. See LICENSE file at the project root for terms.
+ */
+
+package com.yahoo.sketches.hive.hll;
+
+import org.apache.hadoop.hive.ql.exec.Description;
+import org.apache.hadoop.hive.ql.exec.UDF;
+import org.apache.hadoop.io.BytesWritable;
+
+import com.yahoo.memory.Memory;
+import com.yahoo.sketches.hll.HllSketch;
+
+@Description(
+ name = "SketchToString",
+ value = "_FUNC_(sketch)",
+ extended = "Returns an human-readable summary of a given HllSketch.")
+public class SketchToStringUDF extends UDF {
+
+ /**
+ * Get a human-readable summary of a given HllSketch
+ * @param serializedSketch HllSketch in a serialized binary form
+ * @return text summary
+ */
+ public String evaluate(final BytesWritable serializedSketch) {
+ if (serializedSketch == null) { return null; }
+ final HllSketch sketch = HllSketch.wrap(Memory.wrap(serializedSketch.getBytes()));
+ return sketch.toString();
+ }
+
+}
diff --git a/src/test/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDFTest.java b/src/test/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDFTest.java
new file mode 100644
index 0000000..6e397ae
--- /dev/null
+++ b/src/test/java/com/yahoo/sketches/hive/hll/SketchToEstimateAndErrorBoundsUDFTest.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright 2019, Verizon Media.
+ * Licensed under the terms of the Apache License 2.0. See LICENSE file at the project root for terms.
+ */
+
+package com.yahoo.sketches.hive.hll;
+
+import java.util.List;
+
+import org.apache.hadoop.io.BytesWritable;
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import com.yahoo.sketches.hll.HllSketch;
+
+public class SketchToEstimateAndErrorBoundsUDFTest {
+
+ @Test
+ public void nullSketch() {
+ final List<Double> result = new SketchToEstimateAndErrorBoundsUDF().evaluate(null);
+ Assert.assertNull(result);
+ }
+
+ @Test
+ public void emptySketch() {
+ final HllSketch sketch = new HllSketch();
+ final List<Double> result = new SketchToEstimateAndErrorBoundsUDF().evaluate(new BytesWritable(sketch.toCompactByteArray()));
+ Assert.assertNotNull(result);
+ Assert.assertEquals(result.size(), 3);
+ Assert.assertEquals(result.get(0), 0.0);
+ Assert.assertEquals(result.get(1), 0.0);
+ Assert.assertEquals(result.get(2), 0.0);
+ }
+
+ @Test
+ public void normalCase() {
+ final HllSketch sketch = new HllSketch();
+ sketch.update(1);
+ sketch.update(2);
+ List<Double> result = new SketchToEstimateAndErrorBoundsUDF().evaluate(new BytesWritable(sketch.toCompactByteArray()));
+ Assert.assertNotNull(result);
+ Assert.assertEquals(result.size(), 3);
+ Assert.assertEquals(result.get(0), 2.0, 0.01);
+ Assert.assertTrue(result.get(1) <= 2.0);
+ Assert.assertTrue(result.get(2) >= 2.0);
+ }
+
+ @Test
+ public void normalCaseWithKappa() {
+ final HllSketch sketch = new HllSketch();
+ sketch.update(1);
+ sketch.update(2);
+ List<Double> result = new SketchToEstimateAndErrorBoundsUDF().evaluate(new BytesWritable(sketch.toCompactByteArray()), 3);
+ Assert.assertNotNull(result);
+ Assert.assertEquals(result.size(), 3);
+ Assert.assertEquals(result.get(0), 2.0, 0.01);
+ Assert.assertTrue(result.get(1) <= 2.0);
+ Assert.assertTrue(result.get(2) >= 2.0);
+ }
+
+}
diff --git a/src/test/java/com/yahoo/sketches/hive/hll/SketchToStringUDFTest.java b/src/test/java/com/yahoo/sketches/hive/hll/SketchToStringUDFTest.java
new file mode 100644
index 0000000..578fcfe
--- /dev/null
+++ b/src/test/java/com/yahoo/sketches/hive/hll/SketchToStringUDFTest.java
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2019, Verizon Media.
+ * Licensed under the terms of the Apache License 2.0. See LICENSE file at the project root for terms.
+ */
+
+package com.yahoo.sketches.hive.hll;
+
+import org.apache.hadoop.io.BytesWritable;
+import org.testng.Assert;
+import org.testng.annotations.Test;
+
+import com.yahoo.sketches.hll.HllSketch;
+
+public class SketchToStringUDFTest {
+
+ @Test
+ public void nullSketch() {
+ final String result = new SketchToStringUDF().evaluate(null);
+ Assert.assertNull(result);
+ }
+
+ @Test
+ public void emptySketch() {
+ final HllSketch sketch = new HllSketch();
+ final String result = new SketchToStringUDF().evaluate(new BytesWritable(sketch.toCompactByteArray()));
+ Assert.assertNotNull(result);
+ Assert.assertTrue(result.length() > 0);
+ }
+
+ @Test
+ public void normalCase() {
+ final HllSketch sketch = new HllSketch();
+ sketch.update(1);
+ sketch.update(2);
+ final String result = new SketchToStringUDF().evaluate(new BytesWritable(sketch.toCompactByteArray()));
+ Assert.assertNotNull(result);
+ Assert.assertTrue(result.length() > 0);
+ }
+
+}
