elastic · jpountz · Jun 12, 2014
diff --git a/docs/reference/search/aggregations.asciidoc b/docs/reference/search/aggregations.asciidoc
@@ -10,14 +10,6 @@ This context is defined by the executed query in combination with the different
 (filtered queries, top-level filters, and facet level filters). While powerful, their implementation is not designed
 from the ground up to support complex aggregations and is thus limited.
 
-.Are facets deprecated?
-**********************************
-As the functionality facets offer is a subset of the one offered by aggregations, over time, we would like to
-see users move to aggregations for all realtime data analytics. That said, we are well aware that such
-transitions/migrations take time, and for this reason we are keeping facets around for the time being.
-Facets are not officially deprecated yet but are likely to be in the future.
-**********************************
-
 The aggregations module breaks the barriers the current facet implementation put in place. The new name ("Aggregations")
 also indicates the intention here - a generic yet extremely powerful framework for building aggregations - any types of
 aggregations.

diff --git a/docs/reference/search/facets.asciidoc b/docs/reference/search/facets.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets]]
 == Facets
 
+include::facets/deprecated.asciidoc[]
+
 The usual purpose of a full-text search engine is to return a small
 number of documents matching your query.
 

diff --git a/docs/reference/search/facets/date-histogram-facet.asciidoc b/docs/reference/search/facets/date-histogram-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-date-histogram-facet]]
 === Date Histogram Facet
 
+include::deprecated.asciidoc[]
+
 A specific histogram facet that can work with `date` field types
 enhancing it over the regular
 <<search-facets-histogram-facet,histogram

diff --git a/docs/reference/search/facets/deprecated.asciidoc b/docs/reference/search/facets/deprecated.asciidoc
@@ -0,0 +1,3 @@
+[WARNING]
+Facets are deprecated and will be removed in a future release. You are
+encouraged to migrate to <<search-aggregations, aggregations>> instead.
diff --git a/docs/reference/search/facets/filter-facet.asciidoc b/docs/reference/search/facets/filter-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-filter-facet]]
 === Filter Facets
 
+include::deprecated.asciidoc[]
+
 A filter facet (not to be confused with a
 <<search-facets,facet filter>>) allows you to
 return a count of the hits matching the filter. The filter itself can be

diff --git a/docs/reference/search/facets/geo-distance-facet.asciidoc b/docs/reference/search/facets/geo-distance-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-geo-distance-facet]]
 === Geo Distance Facets
 
+include::deprecated.asciidoc[]
+
 The geo_distance facet is a facet providing information for ranges of
 distances from a provided geo_point including count of the number of
 hits that fall within each range, and aggregation information (like

diff --git a/docs/reference/search/facets/histogram-facet.asciidoc b/docs/reference/search/facets/histogram-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-histogram-facet]]
 === Histogram Facets
 
+include::deprecated.asciidoc[]
+
 The histogram facet works with numeric data by building a histogram
 across intervals of the field values. Each value is "rounded" into an
 interval (or placed in a bucket), and statistics are provided per

diff --git a/docs/reference/search/facets/query-facet.asciidoc b/docs/reference/search/facets/query-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-query-facet]]
 === Query Facets
 
+include::deprecated.asciidoc[]
+
 A facet query allows to return a count of the hits matching the facet
 query. The query itself can be expressed using the Query DSL. For
 example:

diff --git a/docs/reference/search/facets/range-facet.asciidoc b/docs/reference/search/facets/range-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-range-facet]]
 === Range Facets
 
+include::deprecated.asciidoc[]
+
 `range` facet allows to specify a set of ranges and get both the number
 of docs (count) that fall within each range, and aggregated data either
 based on the field, or using another field. Here is a simple example:

diff --git a/docs/reference/search/facets/statistical-facet.asciidoc b/docs/reference/search/facets/statistical-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-statistical-facet]]
 === Statistical Facet
 
+include::deprecated.asciidoc[]
+
 Statistical facet allows to compute statistical data on a numeric
 fields. The statistical data include count, total, sum of squares, mean
 (average), minimum, maximum, variance, and standard deviation. Here is

diff --git a/docs/reference/search/facets/terms-facet.asciidoc b/docs/reference/search/facets/terms-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-terms-facet]]
 === Terms Facet
 
+include::deprecated.asciidoc[]
+
 Allow to specify field facets that return the N most frequent terms. For
 example:
 

diff --git a/docs/reference/search/facets/terms-stats-facet.asciidoc b/docs/reference/search/facets/terms-stats-facet.asciidoc
@@ -1,6 +1,8 @@
 [[search-facets-terms-stats-facet]]
 === Terms Stats Facet
 
+include::deprecated.asciidoc[]
+
 The `terms_stats` facet combines both the
 <<search-facets-terms-facet,terms>> and
 <<search-facets-statistical-facet,statistical>>

diff --git a/src/main/java/org/elasticsearch/action/search/SearchRequestBuilder.java b/src/main/java/org/elasticsearch/action/search/SearchRequestBuilder.java
@@ -525,47 +525,59 @@ public SearchRequestBuilder addFields(String... fields) {
 
     /**
      * Adds a facet to the search operation.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder addFacet(FacetBuilder facet) {
         sourceBuilder().facet(facet);
         return this;
     }
 
     /**
      * Sets a raw (xcontent) binary representation of facets to use.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder setFacets(BytesReference facets) {
         sourceBuilder().facets(facets);
         return this;
     }
 
     /**
      * Sets a raw (xcontent) binary representation of facets to use.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder setFacets(byte[] facets) {
         sourceBuilder().facets(facets);
         return this;
     }
 
     /**
      * Sets a raw (xcontent) binary representation of facets to use.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder setFacets(byte[] facets, int facetsOffset, int facetsLength) {
         sourceBuilder().facets(facets, facetsOffset, facetsLength);
         return this;
     }
 
     /**
      * Sets a raw (xcontent) binary representation of facets to use.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder setFacets(XContentBuilder facets) {
         sourceBuilder().facets(facets);
         return this;
     }
 
     /**
      * Sets a raw (xcontent) binary representation of facets to use.
+     * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
      */
+    @Deprecated
     public SearchRequestBuilder setFacets(Map facets) {
         sourceBuilder().facets(facets);
         return this;

diff --git a/src/main/java/org/elasticsearch/search/facet/FacetBuilders.java b/src/main/java/org/elasticsearch/search/facet/FacetBuilders.java
@@ -35,8 +35,9 @@
 import org.elasticsearch.search.facet.termsstats.TermsStatsFacetBuilder;
 
 /**
- *
+ * @deprecated Facets are deprecated and will be removed in a future release. Please use aggregations instead.
  */
+@Deprecated
 public class FacetBuilders {
 
     public static QueryFacetBuilder queryFacet(String facetName) {