1 files changed, 494 insertions, 0 deletions
diff --git a/docs/java-api/facets.asciidoc b/docs/java-api/facets.asciidoc
new file mode 100644
index 0000000..34353c6
--- /dev/null
+++ b/docs/java-api/facets.asciidoc
@@ -0,0 +1,494 @@
+[[java-facets]]
+== Facets
+
+Elasticsearch provides a full Java API to play with facets. See the
+{ref}/search-facets.html[Facets guide].
+
+Use the factory for facet builders (`FacetBuilders`) and add each facet
+you want to compute when querying and add it to your search request:
+
+[source,java]
+--------------------------------------------------
+SearchResponse sr = node.client().prepareSearch()
+        .setQuery( /* your query */ )
+        .addFacet( /* add a facet */ )
+        .execute().actionGet();
+--------------------------------------------------
+
+Note that you can add more than one facet. See
+{ref}/search-search.html[Search Java API] for details.
+
+To build facet requests, use `FacetBuilders` helpers. Just import them
+in your class:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.FacetBuilders.*;
+--------------------------------------------------
+
+
+=== Facets
+
+
+[[java-facet-terms]]
+==== Terms Facet
+
+Here is how you can use
+{ref}/search-facets-terms-facet.html[Terms Facet]
+with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.termsFacet("f")
+    .field("brand")
+    .size(10);
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.terms.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+TermsFacet f = (TermsFacet) sr.getFacets().facetsAsMap().get("f");
+
+f.getTotalCount();      // Total terms doc count
+f.getOtherCount();      // Not shown terms doc count
+f.getMissingCount();    // Without term doc count
+
+// For each entry
+for (TermsFacet.Entry entry : f) {
+    entry.getTerm();    // Term
+    entry.getCount();   // Doc count
+}
+--------------------------------------------------
+
+
+[[java-facet-range]]
+==== Range Facet
+
+Here is how you can use
+{ref}/search-facets-range-facet.html[Range Facet]
+with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.rangeFacet("f")
+    .field("price")         // Field to compute on
+    .addUnboundedFrom(3)    // from -infinity to 3 (excluded)
+    .addRange(3, 6)         // from 3 to 6 (excluded)
+    .addUnboundedTo(6);     // from 6 to +infinity
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.range.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+RangeFacet f = (RangeFacet) sr.getFacets().facetsAsMap().get("f");
+
+// For each entry
+for (RangeFacet.Entry entry : f) {
+    entry.getFrom();    // Range from requested
+    entry.getTo();      // Range to requested
+    entry.getCount();   // Doc count
+    entry.getMin();     // Min value
+    entry.getMax();     // Max value
+    entry.getMean();    // Mean
+    entry.getTotal();   // Sum of values
+}
+--------------------------------------------------
+
+
+[[histogram]]
+==== Histogram Facet
+
+Here is how you can use
+{ref}/search-facets-histogram-facet.html[Histogram
+Facet] with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+HistogramFacetBuilder facet = FacetBuilders.histogramFacet("f")
+    .field("price")
+    .interval(1);
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.histogram.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+HistogramFacet f = (HistogramFacet) sr.getFacets().facetsAsMap().get("f");
+
+// For each entry
+for (HistogramFacet.Entry entry : f) {
+    entry.getKey();     // Key (X-Axis)
+    entry.getCount();   // Doc count (Y-Axis)
+}
+--------------------------------------------------
+
+
+[[date-histogram]]
+==== Date Histogram Facet
+
+Here is how you can use
+{ref}/search-facets-date-histogram-facet.html[Date
+Histogram Facet] with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.dateHistogramFacet("f")
+    .field("date")      // Your date field
+    .interval("year");  // You can also use "quarter", "month", "week", "day",
+                        // "hour" and "minute" or notation like "1.5h" or "2w"
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.datehistogram.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+DateHistogramFacet f = (DateHistogramFacet) sr.getFacets().facetsAsMap().get("f");
+
+// For each entry
+for (DateHistogramFacet.Entry entry : f) {
+    entry.getTime();    // Date in ms since epoch (X-Axis)
+    entry.getCount();   // Doc count (Y-Axis)
+}
+--------------------------------------------------
+
+
+[[filter]]
+==== Filter Facet (not facet filter)
+
+Here is how you can use
+{ref}/search-facets-filter-facet.html[Filter Facet]
+with Java API.
+
+If you are looking on how to apply a filter to a facet, have a look at
+link:#facet-filter[facet filter] using Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.filterFacet("f",
+    FilterBuilders.termFilter("brand", "heineken"));    // Your Filter here
+--------------------------------------------------
+
+See <<query-dsl-filters,Filters>> to
+learn how to build filters using Java.
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.filter.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+FilterFacet f = (FilterFacet) sr.getFacets().facetsAsMap().get("f");
+
+f.getCount();   // Number of docs that matched
+--------------------------------------------------
+
+
+[[query]]
+==== Query Facet
+
+Here is how you can use
+{ref}/search-facets-query-facet.html[Query Facet]
+with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.queryFacet("f",
+    QueryBuilders.matchQuery("brand", "heineken"));
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.query.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+QueryFacet f = (QueryFacet) sr.getFacets().facetsAsMap().get("f");
+
+f.getCount();   // Number of docs that matched
+--------------------------------------------------
+
+See <<query-dsl-queries,Queries>> to
+learn how to build queries using Java.
+
+
+[[statistical]]
+==== Statistical
+
+Here is how you can use
+{ref}/search-facets-statistical-facet.html[Statistical
+Facet] with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.statisticalFacet("f")
+   .field("price");
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.statistical.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+StatisticalFacet f = (StatisticalFacet) sr.getFacets().facetsAsMap().get("f");
+
+f.getCount();           // Doc count
+f.getMin();             // Min value
+f.getMax();             // Max value
+f.getMean();            // Mean
+f.getTotal();           // Sum of values
+f.getStdDeviation();    // Standard Deviation
+f.getSumOfSquares();    // Sum of Squares
+f.getVariance();        // Variance
+--------------------------------------------------
+
+
+[[terms-stats]]
+==== Terms Stats Facet
+
+Here is how you can use
+{ref}/search-facets-terms-stats-facet.html[Terms
+Stats Facet] with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.termsStatsFacet("f")
+    .keyField("brand")
+    .valueField("price");
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.termsstats.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+TermsStatsFacet f = (TermsStatsFacet) sr.getFacets().facetsAsMap().get("f");
+f.getTotalCount();      // Total terms doc count
+f.getOtherCount();      // Not shown terms doc count
+f.getMissingCount();    // Without term doc count
+
+// For each entry
+for (TermsStatsFacet.Entry entry : f) {
+    entry.getTerm();            // Term
+    entry.getCount();           // Doc count
+    entry.getMin();             // Min value
+    entry.getMax();             // Max value
+    entry.getMean();            // Mean
+    entry.getTotal();           // Sum of values
+}
+--------------------------------------------------
+
+
+[[geo-distance]]
+==== Geo Distance Facet
+
+Here is how you can use
+{ref}/search-facets-geo-distance-facet.html[Geo
+Distance Facet] with Java API.
+
+
+===== Prepare facet request
+
+Here is an example on how to create the facet request:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders.geoDistanceFacet("f")
+    .field("pin.location")              // Field containing coordinates we want to compare with
+    .point(40, -70)                     // Point from where we start (0)
+    .addUnboundedFrom(10)               // 0 to 10 km (excluded)
+    .addRange(10, 20)                   // 10 to 20 km (excluded)
+    .addRange(20, 100)                  // 20 to 100 km (excluded)
+    .addUnboundedTo(100)                // from 100 km to infinity (and beyond ;-) )
+    .unit(DistanceUnit.KILOMETERS);     // All distances are in kilometers. Can be MILES
+--------------------------------------------------
+
+
+===== Use facet response
+
+Import Facet definition classes:
+
+[source,java]
+--------------------------------------------------
+import org.elasticsearch.search.facet.geodistance.*;
+--------------------------------------------------
+
+[source,java]
+--------------------------------------------------
+// sr is here your SearchResponse object
+GeoDistanceFacet f = (GeoDistanceFacet) sr.getFacets().facetsAsMap().get("f");
+
+// For each entry
+for (GeoDistanceFacet.Entry entry : f) {
+    entry.getFrom();            // Distance from requested
+    entry.getTo();              // Distance to requested
+    entry.getCount();           // Doc count
+    entry.getMin();             // Min value
+    entry.getMax();             // Max value
+    entry.getTotal();           // Sum of values
+    entry.getMean();            // Mean
+}
+--------------------------------------------------
+
+
+[[facet-filter]]
+=== Facet filters (not Filter Facet)
+
+By default, facets are applied on the query resultset whatever filters
+exists or are.
+
+If you need to compute facets with the same filters or even with other
+filters, you can add the filter to any facet using
+`AbstractFacetBuilder#facetFilter(FilterBuilder)` method:
+
+[source,java]
+--------------------------------------------------
+FacetBuilders
+    .termsFacet("f").field("brand") // Your facet
+    .facetFilter( // Your filter here
+        FilterBuilders.termFilter("colour", "pale")
+    );
+--------------------------------------------------
+
+For example, you can reuse the same filter you created for your query:
+
+[source,java]
+--------------------------------------------------
+// A common filter
+FilterBuilder filter = FilterBuilders.termFilter("colour", "pale");
+
+TermsFacetBuilder facet = FacetBuilders.termsFacet("f")
+    .field("brand")
+    .facetFilter(filter);                           // We apply it to the facet
+
+SearchResponse sr = node.client().prepareSearch()
+    .setQuery(QueryBuilders.matchAllQuery())
+    .setFilter(filter)                              // We apply it to the query
+    .addFacet(facet)
+    .execute().actionGet();
+--------------------------------------------------
+
+See documentation on how to build
+<<query-dsl-filters,Filters>>.
+
+
+[[scope]]
+=== Scope
+
+By default, facets are computed within the query resultset. But, you can
+compute facets from all documents in the index whatever the query is,
+using `global` parameter:
+
+[source,java]
+--------------------------------------------------
+TermsFacetBuilder facet = FacetBuilders.termsFacet("f")
+    .field("brand")
+    .global(true);
+--------------------------------------------------