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

11 files changed, 35 insertions, 0 deletions

diff --git a/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryBuilder.java b/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryBuilder.java
index 3be82f3970..2031abc007 100644
--- a/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryBuilder.java
+++ b/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";
diff --git a/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryParser.java b/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryParser.java
index 85365f84fb..55dddbe4af 100644
--- a/core/src/main/java/org/elasticsearch/index/query/FuzzyQueryParser.java
+++ b/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");
diff --git a/core/src/main/java/org/elasticsearch/index/query/QueryBuilders.java b/core/src/main/java/org/elasticsearch/index/query/QueryBuilders.java
index 893c97f332..03ccebf047 100644
--- a/core/src/main/java/org/elasticsearch/index/query/QueryBuilders.java
+++ b/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);
     }
diff --git a/core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java b/core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java
index 3e89949821..cb9177369c 100644
--- a/core/src/test/java/org/elasticsearch/index/query/QueryDSLDocumentationTests.java
+++ b/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");
     }
diff --git a/core/src/test/java/org/elasticsearch/search/highlight/HighlighterSearchIT.java b/core/src/test/java/org/elasticsearch/search/highlight/HighlighterSearchIT.java
index 6f9ef10128..10c7c54b83 100644
--- a/core/src/test/java/org/elasticsearch/search/highlight/HighlighterSearchIT.java
+++ b/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();
diff --git a/core/src/test/java/org/elasticsearch/search/matchedqueries/MatchedQueriesIT.java b/core/src/test/java/org/elasticsearch/search/matchedqueries/MatchedQueriesIT.java
index d8c16282e1..4daa45fe39 100644
--- a/core/src/test/java/org/elasticsearch/search/matchedqueries/MatchedQueriesIT.java
+++ b/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();
diff --git a/core/src/test/java/org/elasticsearch/search/profile/RandomQueryGenerator.java b/core/src/test/java/org/elasticsearch/search/profile/RandomQueryGenerator.java
index 9eb41086be..fff0b99c4d 100644
--- a/core/src/test/java/org/elasticsearch/search/profile/RandomQueryGenerator.java
+++ b/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));
diff --git a/core/src/test/java/org/elasticsearch/search/query/SearchQueryIT.java b/core/src/test/java/org/elasticsearch/search/query/SearchQueryIT.java
index ad9ab044ad..d723c88535 100644
--- a/core/src/test/java/org/elasticsearch/search/query/SearchQueryIT.java
+++ b/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");
 
diff --git a/core/src/test/java/org/elasticsearch/validate/SimpleValidateQueryIT.java b/core/src/test/java/org/elasticsearch/validate/SimpleValidateQueryIT.java
index 1657116991..d937d5bade 100644
--- a/core/src/test/java/org/elasticsearch/validate/SimpleValidateQueryIT.java
+++ b/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")
diff --git a/docs/java-api/query-dsl/fuzzy-query.asciidoc b/docs/java-api/query-dsl/fuzzy-query.asciidoc
index e871bc9d0b..1ea5983072 100644
--- a/docs/java-api/query-dsl/fuzzy-query.asciidoc
+++ b/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]
diff --git a/docs/reference/query-dsl/fuzzy-query.asciidoc b/docs/reference/query-dsl/fuzzy-query.asciidoc
index 72bb151f63..a2d770aabc 100644
--- a/docs/reference/query-dsl/fuzzy-query.asciidoc
+++ b/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.