[CALCITE-1725] Push project aggregate of time extract to druid

* Adding additional comments.
andreAmorimF · Apr 10, 2017 · 2eebca8 · 2eebca8
1 parent 22fdd88
commit 2eebca8
Show file tree

Hide file tree

Showing 6 changed files with 52 additions and 6 deletions.
diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/DefaultDimensionSpec.java b/druid/src/main/java/org/apache/calcite/adapter/druid/DefaultDimensionSpec.java
@@ -21,7 +21,10 @@
 import java.io.IOException;
 
 /**
- * Default implementation of Dimension spec
+ * Default implementation of DimensionSpec.
+ *
+ * <p>The default implementation returns dimension values as is and optionally
+ * renames the dimension.
  */
 public class DefaultDimensionSpec implements DimensionSpec {
 

diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/DimensionSpec.java b/druid/src/main/java/org/apache/calcite/adapter/druid/DimensionSpec.java
@@ -17,7 +17,9 @@
 package org.apache.calcite.adapter.druid;
 
 /**
- * Druid dimension spec interface
+ * Interface for Druid DimensionSpec.
+ *
+ * <p>DimensionSpecs define how dimension values get transformed prior to aggregation.
  */
 public interface DimensionSpec extends DruidQuery.Json {
 }

diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/ExtractionDimensionSpec.java b/druid/src/main/java/org/apache/calcite/adapter/druid/ExtractionDimensionSpec.java
@@ -23,7 +23,10 @@
 import static org.apache.calcite.adapter.druid.DruidQuery.writeFieldIf;
 
 /**
- * Extraction function dimension spec implementation
+ * Implementation of extraction function DimensionSpec.
+ *
+ * <p>The extraction function implementation returns dimension values transformed
+ * using the given extraction function.
  */
 public class ExtractionDimensionSpec implements DimensionSpec {
   private final String dimension;

diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/ExtractionFunction.java b/druid/src/main/java/org/apache/calcite/adapter/druid/ExtractionFunction.java
@@ -17,7 +17,9 @@
 package org.apache.calcite.adapter.druid;
 
 /**
- * Extraction Function interface
+ * Interface for Druid extraction functions.
+ *
+ * <p>Extraction functions define the transformation applied to each dimension value.
  */
 public interface ExtractionFunction extends DruidQuery.Json {
 }

diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/TimeExtractionDimensionSpec.java b/druid/src/main/java/org/apache/calcite/adapter/druid/TimeExtractionDimensionSpec.java
@@ -17,7 +17,7 @@
 package org.apache.calcite.adapter.druid;
 
 /**
- * Time extraction dimension spec implementation
+ * DimensionSpec implementation that uses a time format extraction function.
  */
 public class TimeExtractionDimensionSpec extends ExtractionDimensionSpec {
 
@@ -26,11 +26,28 @@ public TimeExtractionDimensionSpec(
     super(DruidTable.DEFAULT_TIMESTAMP_COLUMN, extractionFunction, outputName);
   }
 
+  /**
+   * Creates a time extraction DimensionSpec that renames the '__time' column
+   * to the given name.
+   *
+   * @param outputName name of the output column
+   * @return the time extraction DimensionSpec instance
+   */
   public static TimeExtractionDimensionSpec makeFullTimeExtract(String outputName) {
     return new TimeExtractionDimensionSpec(
         TimeExtractionFunction.createDefault(), outputName);
   }
 
+  /**
+   * Creates a time extraction DimensionSpec that formats the '__time' column
+   * according to the given granularity and outputs the column with the given
+   * name. Only YEAR, MONTH, and DAY granularity are supported.
+   *
+   * @param granularity granularity to apply to the column
+   * @param outputName name of the output column
+   * @return the time extraction DimensionSpec instance or null if granularity
+   * is not supported
+   */
   public static TimeExtractionDimensionSpec makeExtract(
       Granularity granularity, String outputName) {
     switch (granularity) {
@@ -43,6 +60,7 @@ public static TimeExtractionDimensionSpec makeExtract(
     case DAY:
       return new TimeExtractionDimensionSpec(
           TimeExtractionFunction.createFromGranularity(granularity), outputName);
+    // TODO: Support other granularities
     default:
       return null;
     }

diff --git a/druid/src/main/java/org/apache/calcite/adapter/druid/TimeExtractionFunction.java b/druid/src/main/java/org/apache/calcite/adapter/druid/TimeExtractionFunction.java
@@ -23,7 +23,13 @@
 import static org.apache.calcite.adapter.druid.DruidQuery.writeFieldIf;
 
 /**
- * Time extraction implementation
+ * Implementation of Druid time format extraction function.
+ *
+ * <p>These functions return the dimension value formatted according to the given format string,
+ * time zone, and locale.
+ *
+ * <p>For __time dimension values, this formats the time value bucketed by the aggregation
+ * granularity.
  */
 public class TimeExtractionFunction implements ExtractionFunction {
 
@@ -49,10 +55,22 @@ public TimeExtractionFunction(String format, String granularity, String timeZone
     generator.writeEndObject();
   }
 
+  /**
+   * Creates the default time format extraction function.
+   *
+   * @return the time extraction function
+   */
   public static TimeExtractionFunction createDefault() {
     return new TimeExtractionFunction("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'", null, "UTC", null);
   }
 
+  /**
+   * Creates the time format extraction function for the given granularity.
+   * Only YEAR, MONTH, DAY, and HOUR granularity are supported.
+   *
+   * @param granularity granularity to apply to the column
+   * @return the time extraction function or null if granularity is not supported
+   */
   public static TimeExtractionFunction createFromGranularity(Granularity granularity) {
     switch (granularity) {
     case DAY: