Add SQL functions to format numbers into human readable format

core/src/main/java/org/apache/druid/java/util/common/HumanReadableBytes.java

@@ -208,4 +208,112 @@ private static long parseInner(String rawNumber)
       throw new IAE("Invalid format or out of range of long: %s", rawNumber);
     }
   }
+
+  public enum UnitSystem
+  {
+    /**
+     * also known as IEC format
+     * eg: B, KiB, MiB, GiB ...
+     */
+    BINARY_BYTE,
+
+    /**
+     * also known as SI format
+     * eg: B, KB, MB ...
+     */
+    DECIMAL_BYTE,
+
+    /**
+     * simplified SI format without 'B' indicator
+     * eg: K, M, G ...
+     */
+    DECIMAL
+  }
+
+  /**
+   * Returns a human-readable string version of input value
+   *
+   * @param bytes      input value. Negative value is also allowed
+   * @param precision  [0,3]
+   * @param unitSystem which unit system is adopted to format the input value, see {@link UnitSystem}
+   */
+  public static String format(long bytes, long precision, UnitSystem unitSystem)
+  {
+    if (precision < 0 || precision > 3) {
+      throw new IAE("precision [%d] must be in the range of [0,3]", precision);
+    }
+
+    String pattern = "%." + precision + "f %s%s";
+    switch (unitSystem) {
+      case BINARY_BYTE:
+        return BinaryFormatter.format(bytes, pattern, "B");
+      case DECIMAL_BYTE:
+        return DecimalFormatter.format(bytes, pattern, "B");
+      case DECIMAL:
+        return DecimalFormatter.format(bytes, pattern, "").trim();
+      default:
+        throw new IAE("Unkonwn unit system[%s]", unitSystem);
+    }
+  }
+
+  static class BinaryFormatter
+  {
+    private static final String[] UNITS = {"", "Ki", "Mi", "Gi", "Ti", "Pi", "Ei"};
+
+    static String format(long bytes, String pattern, String suffix)
+    {
+      if (bytes > -1024 && bytes < 1024) {
+        return bytes + " " + suffix;
+      }
+
+      if (bytes == Long.MIN_VALUE) {
+        /**
+         * special path for Long.MIN_VALUE
+         *
+         * Long.MIN_VALUE = 2^63 = (2^60=1EiB) * 2^3
+         */
+        return StringUtils.format(pattern, -8.0, UNITS[UNITS.length - 1], suffix);
+      }
+
+      /**
+       * A number and its binary bits are listed as fellows
+       * [0,    1KiB) = [0,    2^10)
+       * [1KiB, 1MiB) = [2^10, 2^20),
+       * [1MiB, 1GiB) = [2^20, 2^30),
+       * [1GiB, 1PiB) = [2^30, 2^40),
+       * ...
+       *
+       * So, expression (63 - Long.numberOfLeadingZeros(absValue))) helps us to get the right number of bits of the given input
+       *
+       * Internal implementaion of Long.numberOfLeadingZeros uses bit operations to do calculation so the cost is very cheap
+       */
+      int unitIndex = (63 - Long.numberOfLeadingZeros(Math.abs(bytes))) / 10;
+      return StringUtils.format(pattern, (double) bytes / (1L << (unitIndex * 10)), UNITS[unitIndex], suffix);
+    }
+  }
+
+  static class DecimalFormatter
+  {
+    private static final String[] UNITS = {"K", "M", "G", "T", "P", "E"};
+
+    static String format(long bytes, String pattern, String suffix)
+    {
+      /**
+       * handle number between (-1000, 1000) first to simply further processing
+       */
+      if (bytes > -1000 && bytes < 1000) {
+        return bytes + " " + suffix;
+      }
+
+      /**
+       * because max precision is 3, extra fraction can be ignored by use of integer division which might be a little more efficient
+       */
+      int unitIndex = 0;
+      while (bytes <= -1000_000 || bytes >= 1000_000) {
+        bytes /= 1000;
+        unitIndex++;
+      }
+      return StringUtils.format(pattern, bytes / 1000.0, UNITS[unitIndex], suffix);
+    }
+  }
 }

core/src/main/java/org/apache/druid/math/expr/Function.java

@@ -22,6 +22,7 @@
 import com.google.common.collect.ImmutableSet;
 import org.apache.druid.common.config.NullHandling;
 import org.apache.druid.java.util.common.DateTimes;
+import org.apache.druid.java.util.common.HumanReadableBytes;
 import org.apache.druid.java.util.common.IAE;
 import org.apache.druid.java.util.common.RE;
 import org.apache.druid.java.util.common.StringUtils;
@@ -3539,4 +3540,103 @@ public ExprEval apply(List<Expr> args, Expr.ObjectBinding bindings)
       throw new RE("Unable to slice to unknown type %s", expr.type());
     }
   }
+
+  abstract class SizeFormatFunc implements Function
+  {
+    protected abstract HumanReadableBytes.UnitSystem getUnitSystem();
+
+    @Override
+    public ExprEval apply(List<Expr> args, Expr.ObjectBinding bindings)
+    {
+      final ExprEval valueParam = args.get(0).eval(bindings);
+      if (NullHandling.sqlCompatible() && valueParam.isNumericNull()) {
+        return ExprEval.of(null);
+      }
+
+      /**
+       * only LONG and DOUBLE are allowed
+       * For a DOUBLE, it will be cast to LONG before format
+       */
+      if (valueParam.value() != null && valueParam.type() != ExprType.LONG && valueParam.type() != ExprType.DOUBLE) {
+        throw new IAE("Function[%s] needs a number as its first argument", name());
+      }
+
+      /**
+       * By default, precision is 2
+       */
+      long precision = 2;
+      if (args.size() > 1) {
+        ExprEval precisionParam = args.get(1).eval(bindings);
+        if (precisionParam.type() != ExprType.LONG) {
+          throw new IAE("Function[%s] needs an integer as its second argument", name());
+        }
+        precision = precisionParam.asLong();
+        if (precision < 0 || precision > 3) {
+          throw new IAE("Given precision[%d] of Function[%s] must be in the range of [0,3]", precision, name());
+        }
+      }
+
+      return ExprEval.of(HumanReadableBytes.format(valueParam.asLong(), precision, this.getUnitSystem()));
+    }
+
+    @Override
+    public void validateArguments(List<Expr> args)
+    {
+      if (args.size() < 1 || args.size() > 2) {
+        throw new IAE("Function[%s] needs 1 or 2 arguments", name());
+      }
+    }
+
+    @Nullable
+    @Override
+    public ExprType getOutputType(Expr.InputBindingInspector inputTypes, List<Expr> args)
+    {
+      return ExprType.STRING;
+    }
+  }
+
+  class HumanReadableDecimalByteFormatFunc extends SizeFormatFunc
+  {
+    @Override
+    public String name()
+    {
+      return "human_readable_decimal_byte_format";
+    }
+
+    @Override
+    protected HumanReadableBytes.UnitSystem getUnitSystem()
+    {
+      return HumanReadableBytes.UnitSystem.DECIMAL_BYTE;
+    }
+  }
+
+  class HumanReadableBinaryByteFormatFunc extends SizeFormatFunc
+  {
+    @Override
+    public String name()
+    {
+      return "human_readable_binary_byte_format";
+    }
+
+    @Override
+    protected HumanReadableBytes.UnitSystem getUnitSystem()
+    {
+      return HumanReadableBytes.UnitSystem.BINARY_BYTE;
+    }
+  }
+
+  class HumanReadableDecimalFormatFunc extends SizeFormatFunc
+  {
+    @Override
+    public String name()
+    {
+      return "human_readable_decimal_format";
+    }
+
+    @Override
+    protected HumanReadableBytes.UnitSystem getUnitSystem()
+    {
+      return HumanReadableBytes.UnitSystem.DECIMAL;
+    }
+  }
 }

core/src/test/java/org/apache/druid/java/util/common/HumanReadableBytesTest.java

@@ -395,6 +395,98 @@ public void testBytesRange()
     Assert.assertEquals("value must be in the range of [0, 5]", message);
   }
 
+  @Test
+  public void testFormatInBinaryByte()
+  {
+    Assert.assertEquals("-8.00 EiB", HumanReadableBytes.format(Long.MIN_VALUE, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("-8.000 EiB", HumanReadableBytes.format(Long.MIN_VALUE, 3, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+
+    Assert.assertEquals("-2.00 GiB", HumanReadableBytes.format(Integer.MIN_VALUE, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("-32.00 KiB", HumanReadableBytes.format(Short.MIN_VALUE, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+
+    Assert.assertEquals("-128 B", HumanReadableBytes.format(Byte.MIN_VALUE, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("-1 B", HumanReadableBytes.format(-1, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("0 B", HumanReadableBytes.format(0, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1 B", HumanReadableBytes.format(1, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+
+    Assert.assertEquals("1.00 KiB", HumanReadableBytes.format(1024L, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.00 MiB", HumanReadableBytes.format(1024L * 1024, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.00 GiB", HumanReadableBytes.format(1024L * 1024 * 1024, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.00 TiB", HumanReadableBytes.format(1024L * 1024 * 1024 * 1024, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.00 PiB", HumanReadableBytes.format(1024L * 1024 * 1024 * 1024 * 1024, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("8.00 EiB", HumanReadableBytes.format(Long.MAX_VALUE, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+  }
+
+  @Test
+  public void testPrecisionInBinaryFormat()
+  {
+    Assert.assertEquals("1 KiB", HumanReadableBytes.format(1500, 0, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.5 KiB", HumanReadableBytes.format(1500, 1, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.46 KiB", HumanReadableBytes.format(1500, 2, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+    Assert.assertEquals("1.465 KiB", HumanReadableBytes.format(1500, 3, HumanReadableBytes.UnitSystem.BINARY_BYTE));
+  }
+
+  @Test
+  public void testPrecisionInDecimalFormat()
+  {
+    Assert.assertEquals("1 KB", HumanReadableBytes.format(1456, 0, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.5 KB", HumanReadableBytes.format(1456, 1, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.46 KB", HumanReadableBytes.format(1456, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.456 KB", HumanReadableBytes.format(1456, 3, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+  }
+
+  @Test
+  public void testFormatInDecimalByte()
+  {
+    Assert.assertEquals("1 B", HumanReadableBytes.format(1, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.00 KB", HumanReadableBytes.format(1000L, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.00 MB", HumanReadableBytes.format(1000L * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.00 GB", HumanReadableBytes.format(1000L * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.00 TB", HumanReadableBytes.format(1000L * 1000 * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("1.00 PB", HumanReadableBytes.format(1000L * 1000 * 1000 * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("9.22 EB", HumanReadableBytes.format(Long.MAX_VALUE, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+
+    Assert.assertEquals("100.00 KB", HumanReadableBytes.format(99999, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("99.999 KB", HumanReadableBytes.format(99999, 3, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+
+    Assert.assertEquals("999.9 PB", HumanReadableBytes.format(999_949_999_999_999_999L, 1, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("999.95 PB", HumanReadableBytes.format(999_949_999_999_999_999L, 2, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+    Assert.assertEquals("999.949 PB", HumanReadableBytes.format(999_949_999_999_999_999L, 3, HumanReadableBytes.UnitSystem.DECIMAL_BYTE));
+  }
+
+  @Test
+  public void testFormatInDecimal()
+  {
+    Assert.assertEquals("1", HumanReadableBytes.format(1, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("999", HumanReadableBytes.format(999, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("-999", HumanReadableBytes.format(-999, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("-1.00 K", HumanReadableBytes.format(-1000, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1.00 K", HumanReadableBytes.format(1000L, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1.00 M", HumanReadableBytes.format(1000L * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1.00 G", HumanReadableBytes.format(1000L * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1.00 T", HumanReadableBytes.format(1000L * 1000 * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1.00 P", HumanReadableBytes.format(1000L * 1000 * 1000 * 1000 * 1000, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("-9.22 E", HumanReadableBytes.format(Long.MIN_VALUE, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("9.22 E", HumanReadableBytes.format(Long.MAX_VALUE, 2, HumanReadableBytes.UnitSystem.DECIMAL));
+  }
+
+  @Test
+  public void testInvalidPrecisionArgumentLowerBound()
+  {
+    expectedException.expect(IAE.class);
+    expectedException.expectMessage("precision [-1] must be in the range of [0,3]");
+    Assert.assertEquals("1.00", HumanReadableBytes.format(1, -1, HumanReadableBytes.UnitSystem.DECIMAL));
+  }
+
+  @Test
+  public void testInvalidPrecisionArgumentUpperBound()
+  {
+    expectedException.expect(IAE.class);
+    expectedException.expectMessage("precision [4] must be in the range of [0,3]");
+    Assert.assertEquals("1", HumanReadableBytes.format(1, 3, HumanReadableBytes.UnitSystem.DECIMAL));
+    Assert.assertEquals("1", HumanReadableBytes.format(1, 4, HumanReadableBytes.UnitSystem.DECIMAL));
+  }
+
   private static <T> String validate(T obj)
   {
     Validator validator = Validation.buildDefaultValidatorFactory()