Skip to content

Commit a29c3e6

Browse files
jpountzjpountz
committed
Facets: deprecation.
Users are encouraged to move to the new aggregation framework that was introduced in Elasticsearch 1.0. Close #6485
1 parent 969f7f0 commit a29c3e6

14 files changed

+37
-9
lines changed

‎docs/reference/search/aggregations.asciidoc

-8
Original file line numberDiff line numberDiff line change
@@ -10,14 +10,6 @@ This context is defined by the executed query in combination with the different
1010
(filtered queries, top-level filters, and facet level filters). While powerful, their implementation is not designed
1111
from the ground up to support complex aggregations and is thus limited.
1212

13-
.Are facets deprecated?
14-
**********************************
15-
As the functionality facets offer is a subset of the one offered by aggregations, over time, we would like to
16-
see users move to aggregations for all realtime data analytics. That said, we are well aware that such
17-
transitions/migrations take time, and for this reason we are keeping facets around for the time being.
18-
Facets are not officially deprecated yet but are likely to be in the future.
19-
**********************************
20-
2113
The aggregations module breaks the barriers the current facet implementation put in place. The new name ("Aggregations")
2214
also indicates the intention here - a generic yet extremely powerful framework for building aggregations - any types of
2315
aggregations.

‎docs/reference/search/facets.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets]]
22
== Facets
33

4+
include::facets/deprecated.asciidoc[]
5+
46
The usual purpose of a full-text search engine is to return a small
57
number of documents matching your query.
68

‎docs/reference/search/facets/date-histogram-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-date-histogram-facet]]
22
=== Date Histogram Facet
33

4+
include::deprecated.asciidoc[]
5+
46
A specific histogram facet that can work with `date` field types
57
enhancing it over the regular
68
<<search-facets-histogram-facet,histogram

‎docs/reference/search/facets/deprecated.asciidoc

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[WARNING]
2+
Facets are deprecated and will be removed in a future release. You are
3+
encouraged to migrate to <<search-aggregations, aggregations>> instead.

‎docs/reference/search/facets/filter-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-filter-facet]]
22
=== Filter Facets
33

4+
include::deprecated.asciidoc[]
5+
46
A filter facet (not to be confused with a
57
<<search-facets,facet filter>>) allows you to
68
return a count of the hits matching the filter. The filter itself can be

‎docs/reference/search/facets/geo-distance-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-geo-distance-facet]]
22
=== Geo Distance Facets
33

4+
include::deprecated.asciidoc[]
5+
46
The geo_distance facet is a facet providing information for ranges of
57
distances from a provided geo_point including count of the number of
68
hits that fall within each range, and aggregation information (like

‎docs/reference/search/facets/histogram-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-histogram-facet]]
22
=== Histogram Facets
33

4+
include::deprecated.asciidoc[]
5+
46
The histogram facet works with numeric data by building a histogram
57
across intervals of the field values. Each value is "rounded" into an
68
interval (or placed in a bucket), and statistics are provided per

‎docs/reference/search/facets/query-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-query-facet]]
22
=== Query Facets
33

4+
include::deprecated.asciidoc[]
5+
46
A facet query allows to return a count of the hits matching the facet
57
query. The query itself can be expressed using the Query DSL. For
68
example:

‎docs/reference/search/facets/range-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-range-facet]]
22
=== Range Facets
33

4+
include::deprecated.asciidoc[]
5+
46
`range` facet allows to specify a set of ranges and get both the number
57
of docs (count) that fall within each range, and aggregated data either
68
based on the field, or using another field. Here is a simple example:

‎docs/reference/search/facets/statistical-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-statistical-facet]]
22
=== Statistical Facet
33

4+
include::deprecated.asciidoc[]
5+
46
Statistical facet allows to compute statistical data on a numeric
57
fields. The statistical data include count, total, sum of squares, mean
68
(average), minimum, maximum, variance, and standard deviation. Here is

‎docs/reference/search/facets/terms-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-terms-facet]]
22
=== Terms Facet
33

4+
include::deprecated.asciidoc[]
5+
46
Allow to specify field facets that return the N most frequent terms. For
57
example:
68

‎docs/reference/search/facets/terms-stats-facet.asciidoc

+2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
[[search-facets-terms-stats-facet]]
22
=== Terms Stats Facet
33

4+
include::deprecated.asciidoc[]
5+
46
The `terms_stats` facet combines both the
57
<<search-facets-terms-facet,terms>> and
68
<<search-facets-statistical-facet,statistical>>

‎src/main/java/org/elasticsearch/action/search/SearchRequestBuilder.java

+12
Original file line numberDiff line numberDiff line change
@@ -525,47 +525,59 @@ public SearchRequestBuilder addFields(String... fields) {
525525

526526
/**
527527
* Adds a facet to the search operation.
528+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
528529
*/
530+
@Deprecated
529531
public SearchRequestBuilder addFacet(FacetBuilder facet) {
530532
sourceBuilder().facet(facet);
531533
return this;
532534
}
533535

534536
/**
535537
* Sets a raw (xcontent) binary representation of facets to use.
538+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
536539
*/
540+
@Deprecated
537541
public SearchRequestBuilder setFacets(BytesReference facets) {
538542
sourceBuilder().facets(facets);
539543
return this;
540544
}
541545

542546
/**
543547
* Sets a raw (xcontent) binary representation of facets to use.
548+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
544549
*/
550+
@Deprecated
545551
public SearchRequestBuilder setFacets(byte[] facets) {
546552
sourceBuilder().facets(facets);
547553
return this;
548554
}
549555

550556
/**
551557
* Sets a raw (xcontent) binary representation of facets to use.
558+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
552559
*/
560+
@Deprecated
553561
public SearchRequestBuilder setFacets(byte[] facets, int facetsOffset, int facetsLength) {
554562
sourceBuilder().facets(facets, facetsOffset, facetsLength);
555563
return this;
556564
}
557565

558566
/**
559567
* Sets a raw (xcontent) binary representation of facets to use.
568+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
560569
*/
570+
@Deprecated
561571
public SearchRequestBuilder setFacets(XContentBuilder facets) {
562572
sourceBuilder().facets(facets);
563573
return this;
564574
}
565575

566576
/**
567577
* Sets a raw (xcontent) binary representation of facets to use.
578+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
568579
*/
580+
@Deprecated
569581
public SearchRequestBuilder setFacets(Map facets) {
570582
sourceBuilder().facets(facets);
571583
return this;

‎src/main/java/org/elasticsearch/search/facet/FacetBuilders.java

+2-1
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,9 @@
3535
import org.elasticsearch.search.facet.termsstats.TermsStatsFacetBuilder;
3636

3737
/**
38-
*
38+
* @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
3939
*/
40+
@Deprecated
4041
public class FacetBuilders {
4142

4243
public static QueryFacetBuilder queryFacet(String facetName) {

0 commit comments

Comments
 (0)