parent/child: Deprecated the `top_children` in favour of the `has_child` query.

docs/reference/migration/migrate_1_6.asciidoc

@@ -8,3 +8,10 @@ your application from Elasticsearch 1.x to Elasticsearch 1.6.
 === More Like This API
 
 The More Like This API query has been deprecated and will be removed in 2.0. Instead use the <<query-dsl-mlt-query, More Like This Query>>.
+
+[float]
+=== `top_children` query
+
+The `top_children` query has been deprecated and will be removed in 2.0. Instead the `has_child` query should be used.
+The `top_children` query isn't always faster than the `has_child` query and the `top_children` query is often inaccurate.
+The total hits and any aggregations in the same search request will likely be off.

docs/reference/query-dsl/queries/top-children-query.asciidoc

@@ -1,6 +1,8 @@
 [[query-dsl-top-children-query]]
 === Top Children Query
 
+deprecated[1.6.0, Use the `has_child` query instead]
+
 The `top_children` query runs the child query with an estimated hits
 size, and out of the hit docs, aggregates it into parent docs. If there
 aren't enough parent docs matching the requested from/size search

src/main/java/org/elasticsearch/index/query/QueryBuilders.java

@@ -475,6 +475,7 @@ public abstract class QueryBuilders {
      * @param type  The child type.
      * @param query The query.
      */
+    @Deprecated
     public static TopChildrenQueryBuilder topChildrenQuery(String type, QueryBuilder query) {
         return new TopChildrenQueryBuilder(type, query);
     }

src/main/java/org/elasticsearch/index/query/TopChildrenQueryBuilder.java

@@ -25,6 +25,7 @@ import java.io.IOException;
 /**
  *
  */
+@Deprecated
 public class TopChildrenQueryBuilder extends BaseQueryBuilder implements BoostableQueryBuilder<TopChildrenQueryBuilder> {
 
     private final QueryBuilder queryBuilder;

src/main/java/org/elasticsearch/index/query/TopChildrenQueryParser.java

@@ -38,6 +38,7 @@ import java.io.IOException;
 /**
  *
  */
+@Deprecated
 public class TopChildrenQueryParser implements QueryParser {
 
     public static final String NAME = "top_children";

src/main/java/org/elasticsearch/index/search/child/TopChildrenQuery.java

@@ -54,6 +54,7 @@ import java.util.Set;
  * This query is most of the times faster than the {@link ChildrenQuery}. Usually enough parent documents can be returned
  * in the first child document query round.
  */
+@Deprecated
 public class TopChildrenQuery extends IndexCacheableQuery {
 
     private static final ParentDocComparator PARENT_DOC_COMP = new ParentDocComparator();