diff --git a/docs/java-api/facets.asciidoc b/docs/java-api/facets.asciidoc index 2e1b96d6fa1..9649d813fff 100644 --- a/docs/java-api/facets.asciidoc +++ b/docs/java-api/facets.asciidoc @@ -1,494 +1,11 @@ [[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 <> 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 <> to -learn how to build queries using Java. - - -[[statistical]] -==== Statistical - -Here is how you can use the -{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 the -{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 -the {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 -<>. - - -[[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); --------------------------------------------------- +Faceted search refers to a way to explore large amounts of data by displaying +summaries about various partitions of the data and later allowing to narrow +the navigation to a specific partition. + +In Elasticsearch, `facets` are also the name of a feature that allowed to +compute these summaries. `facets` have been replaced by +<> in Elasticsearch 1.0, which are a superset +of facets.