Deprecate fuzzy query

With this commit we deprecate the widely misunderstood
fuzzy query but will still allow the fuzziness
parameter in match queries and suggesters.

Relates to #15760

core/src/main/java/org/elasticsearch/index/query/FuzzyQueryBuilder.java

@@ -37,7 +37,11 @@ import java.util.Objects;
 
 /**
  * A Query that does fuzzy matching for a specific value.
+ *
+ * @deprecated Fuzzy queries are not useful enough. This class will be removed with Elasticsearch 4.0. In most cases you may want to use
+ * a match query with the fuzziness parameter for strings or range queries for numeric and date fields.
  */
+@Deprecated
 public class FuzzyQueryBuilder extends AbstractQueryBuilder<FuzzyQueryBuilder> implements MultiTermQueryBuilder<FuzzyQueryBuilder> {
 
     public static final String NAME = "fuzzy";

core/src/main/java/org/elasticsearch/index/query/FuzzyQueryParser.java

@@ -26,6 +26,11 @@ import org.elasticsearch.common.xcontent.XContentParser;
 
 import java.io.IOException;
 
+/**
+ * @deprecated Fuzzy queries are not useful enough. This class will be removed with Elasticsearch 4.0. In most cases you may want to use
+ * a match query with the fuzziness parameter for strings or range queries for numeric and date fields.
+ */
+@Deprecated
 public class FuzzyQueryParser implements QueryParser<FuzzyQueryBuilder> {
 
     public static final ParseField TERM_FIELD = new ParseField("term");

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

@@ -199,7 +199,14 @@ public abstract class QueryBuilders {
      *
      * @param name  The name of the field
      * @param value The value of the term
+     *
+     * @deprecated Fuzzy queries are not useful enough and will be removed with Elasticsearch 4.0. In most cases you may want to use
+     * a match query with the fuzziness parameter for strings or range queries for numeric and date fields.
+     *
+     * @see #matchQuery(String, Object)
+     * @see #rangeQuery(String)
      */
+    @Deprecated
     public static FuzzyQueryBuilder fuzzyQuery(String name, String value) {
         return new FuzzyQueryBuilder(name, value);
     }
@@ -209,7 +216,14 @@ public abstract class QueryBuilders {
      *
      * @param name  The name of the field
      * @param value The value of the term
+     *
+     * @deprecated Fuzzy queries are not useful enough and will be removed with Elasticsearch 4.0. In most cases you may want to use
+     * a match query with the fuzziness parameter for strings or range queries for numeric and date fields.
+     *
+     * @see #matchQuery(String, Object)
+     * @see #rangeQuery(String)
      */
+    @Deprecated
     public static FuzzyQueryBuilder fuzzyQuery(String name, Object value) {
         return new FuzzyQueryBuilder(name, value);
     }

core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java

@@ -138,6 +138,7 @@ public class QueryDSLDocumentationTests extends ESTestCase {
         functionScoreQuery(functions);
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     public void testFuzzy() {
         fuzzyQuery("name", "kimchy");
     }

core/src/test/java/org/elasticsearch/search/highlight/HighlighterSearchIT.java

@@ -2378,6 +2378,7 @@ public class HighlighterSearchIT extends ESIntegTestCase {
 
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     public void testPostingsHighlighterFuzzyQuery() throws Exception {
         assertAcked(prepareCreate("test").addMapping("type1", type1PostingsffsetsMapping()));
         ensureGreen();

core/src/test/java/org/elasticsearch/search/matchedqueries/MatchedQueriesIT.java

@@ -250,6 +250,7 @@ public class MatchedQueriesIT extends ESIntegTestCase {
         }
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     public void testFuzzyQuerySupportsName() {
         createIndex("test1");
         ensureGreen();

core/src/test/java/org/elasticsearch/search/profile/RandomQueryGenerator.java

@@ -72,6 +72,7 @@ public class RandomQueryGenerator {
         }
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     private static QueryBuilder randomTerminalQuery(List<String> stringFields, List<String> numericFields, int numDocs) {
         switch (randomIntBetween(0,6)) {
             case 0:
@@ -195,6 +196,8 @@ public class RandomQueryGenerator {
         return q;
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
+    @Deprecated
     private static QueryBuilder randomFuzzyQuery(List<String> fields) {
 
         QueryBuilder q = QueryBuilders.fuzzyQuery(randomField(fields), randomQueryString(1));

core/src/test/java/org/elasticsearch/search/query/SearchQueryIT.java

@@ -1451,6 +1451,7 @@ public class SearchQueryIT extends ESIntegTestCase {
         assertHitCount(searchResponse, 3l);
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     public void testSpanMultiTermQuery() throws IOException {
         createIndex("test");
 

core/src/test/java/org/elasticsearch/validate/SimpleValidateQueryIT.java

@@ -212,6 +212,7 @@ public class SimpleValidateQueryIT extends ESIntegTestCase {
         assertThat(validateQueryResponse.getQueryExplanation().get(0).getExplanation(), containsString("field:\"foo (one* two*)\""));
     }
 
+    @SuppressWarnings("deprecation") // fuzzy queries will be removed in 4.0
     public void testExplainWithRewriteValidateQuery() throws Exception {
         client().admin().indices().prepareCreate("test")
                 .addMapping("type1", "field", "type=string,analyzer=whitespace")

docs/java-api/query-dsl/fuzzy-query.asciidoc

@@ -1,6 +1,8 @@
 [[java-query-dsl-fuzzy-query]]
 ==== Fuzzy Query
 
+deprecated[3.0.0, Will be removed without a replacement for `string` fields. Note that the `fuzziness` parameter is still supported for match queries and in suggesters. Use range queries for `date` and `numeric` fields instead.]
+
 See {ref}/query-dsl-fuzzy-query.html[Fuzzy Query]
 
 [source,java]

docs/reference/query-dsl/fuzzy-query.asciidoc

@@ -1,6 +1,8 @@
 [[query-dsl-fuzzy-query]]
 === Fuzzy Query
 
+deprecated[3.0.0, Will be removed without a replacement for `string` fields. Note that the `fuzziness` parameter is still supported for match queries and in suggesters. Use range queries for `date` and `numeric` fields instead.]
+
 The fuzzy query uses similarity based on Levenshtein edit distance for
 `string` fields, and a `+/-` margin on numeric and date fields.