javadoc

modules/elasticsearch/src/main/java/org/elasticsearch/search/facets/histogram/HistogramFacet.java

@@ -26,22 +26,40 @@ import java.util.Comparator;
 import java.util.List;
 
 /**
- * Numeric histogram information.
+ * Numeric histogram facet.
  *
  * @author kimchy (shay.banon)
  */
 public interface HistogramFacet extends Facet, Iterable<HistogramFacet.Entry> {
 
+    /**
+     * The key field name used with this facet.
+     */
     String keyFieldName();
 
+    /**
+     * The key field name used with this facet.
+     */
     String getKeyFieldName();
 
+    /**
+     * The value field name used with this facet.
+     */
     String valueFieldName();
 
+    /**
+     * The value field name used with this facet.
+     */
     String getValueFieldName();
 
+    /**
+     * An ordered list of histogram facet entries.
+     */
     List<Entry> entries();
 
+    /**
+     * An ordered list of histogram facet entries.
+     */
     List<Entry> getEntries();
 
     public static enum ComparatorType {
@@ -131,6 +149,9 @@ public interface HistogramFacet extends Facet, Iterable<HistogramFacet.Entry> {
     }
 
 
+    /**
+     * A histogram entry representing a single entry within the result of a histogram facet.
+     */
     public class Entry {
         private final long key;
         private final long count;
@@ -142,34 +163,58 @@ public interface HistogramFacet extends Facet, Iterable<HistogramFacet.Entry> {
             this.total = total;
         }
 
+        /**
+         * The key value of the histogram.
+         */
         public long key() {
             return key;
         }
 
+        /**
+         * The key value of the histogram.
+         */
         public long getKey() {
             return key();
         }
 
+        /**
+         * The number of hits that fall within that key "range" or "interval".
+         */
         public long count() {
             return count;
         }
 
+        /**
+         * The number of hits that fall within that key "range" or "interval".
+         */
         public long getCount() {
             return count();
         }
 
+        /**
+         * The sum / total of the value field that fall within this key "interval".
+         */
         public double total() {
             return total;
         }
 
+        /**
+         * The sum / total of the value field that fall within this key "interval".
+         */
         public double getTotal() {
             return total();
         }
 
+        /**
+         * The mean of this facet interval.
+         */
         public double mean() {
             return total / count;
         }
 
+        /**
+         * The mean of this facet interval.
+         */
         public double getMean() {
             return mean();
         }

modules/elasticsearch/src/main/java/org/elasticsearch/search/facets/histogram/HistogramFacetBuilder.java

@@ -25,8 +25,11 @@ import org.elasticsearch.search.builder.SearchSourceBuilderException;
 import org.elasticsearch.search.facets.AbstractFacetBuilder;
 
 import java.io.IOException;
+import java.util.concurrent.TimeUnit;
 
 /**
+ * A facet builder of histogram facets.
+ *
  * @author kimchy (shay.banon)
  */
 public class HistogramFacetBuilder extends AbstractFacetBuilder {
@@ -35,41 +38,76 @@ public class HistogramFacetBuilder extends AbstractFacetBuilder {
     private long interval = -1;
     private HistogramFacet.ComparatorType comparatorType;
 
+    /**
+     * Constructs a new histogram facet with the provided facet logical name.
+     *
+     * @param name The logical name of the facet
+     */
     public HistogramFacetBuilder(String name) {
         super(name);
     }
 
+    /**
+     * The field name to perform the histogram facet. Translates to perform the histogram facet
+     * using the provided field as both the {@link #keyField(String)} and {@link #valueField(String)}.
+     */
     public HistogramFacetBuilder field(String field) {
         this.keyFieldName = field;
         this.valueFieldName = field;
         return this;
     }
 
+    /**
+     * The field name to use in order to control where the hit will "fall into" within the histogram
+     * entries. Essentially, using the key field numeric value, the hit will be "rounded" into the relevant
+     * bucket controlled by the interval.
+     */
     public HistogramFacetBuilder keyField(String keyField) {
         this.keyFieldName = keyField;
         return this;
     }
 
+    /**
+     * The field name to use as the value of the hit to compute data based on values within the interval
+     * (for example, total).
+     */
     public HistogramFacetBuilder valueField(String valueField) {
         this.valueFieldName = valueField;
         return this;
     }
 
+    /**
+     * The interval used to control the bucket "size" where each key value of a hit will fall into.
+     */
     public HistogramFacetBuilder interval(long interval) {
         this.interval = interval;
         return this;
     }
 
+    /**
+     * The interval used to control the bucket "size" where each key value of a hit will fall into.
+     */
+    public HistogramFacetBuilder interval(long interval, TimeUnit unit) {
+        return interval(unit.toMillis(interval));
+    }
+
     public HistogramFacetBuilder comparator(HistogramFacet.ComparatorType comparatorType) {
         this.comparatorType = comparatorType;
         return this;
     }
 
+    /**
+     * Should the facet run in global mode (not bounded by the search query) or not (bounded by
+     * the search query). Defaults to <tt>false</tt>.
+     */
     public HistogramFacetBuilder global(boolean global) {
         this.global = global;
         return this;
     }
 
+    /**
+     * An additional filter used to further filter down the set of documents the facet will run on.
+     */
     public HistogramFacetBuilder filter(XContentFilterBuilder filter) {
         this.filter = filter;
         return this;