path: root/docs/java-api/facets.asciidoc

[[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);
--------------------------------------------------