Modified the wording of exception messages and created the troublesho…

…oting page (opendistro-for-elasticsearch#372)

* Edit the wording of exception messages

* Created troubleshooting page

* Revised troubleshooting page

* addressed comments

(cherry picked from commit a4afc75)

docs/user/dql/troubleshooting.rst

@@ -0,0 +1,89 @@
+
+===============
+Troubleshooting
+===============
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+Narrative
+=========
+
+SQL plugin is stateless for now so mostly the troubleshooting is focused on why a single query fails.
+
+
+Syntax Analysis / Semantic Analysis Exceptions
+----------------------------------------------
+
+**Symptoms**
+
+When you end up with exceptions similar to as follows:
+
+Query:
+
+.. code-block:: JSON
+
+	POST /_opendistro/_sql
+	{
+	  "query" : "SELECT * FROM sample:data"
+	}
+
+Result:
+
+.. code-block:: JSON
+
+    {
+      "reason": "Invalid SQL query",
+      "details": "Failed to parse query due to offending symbol [:] at: 'SELECT * FROM xxx WHERE xxx:' <--- HERE...
+        More details: Expecting tokens in {<EOF>, 'AND', 'BETWEEN', 'GROUP', 'HAVING', 'IN', 'IS', 'LIKE', 'LIMIT',
+        'NOT', 'OR', 'ORDER', 'REGEXP', '*', '/', '%', '+', '-', 'DIV', 'MOD', '=', '>', '<', '!',
+        '|', '&', '^', '.', DOT_ID}",
+      "type": "SyntaxAnalysisException"
+    }
+
+**Workaround**
+
+You need to confirm if the syntax is not supported and disable query analysis if that's the case by the following steps:
+
+1. Identify syntax error in failed query, and correct the syntax if the query does not follow MySQL grammar. Go to step 2 if your query is correct in syntax but it still ends up syntax exception.
+
+#. Disable strict query analysis in new ANTLR parser with the following code block.
+
+#. Verify if the query can pass now. If the query fails as well, please create an issue in our `GitHub Issues <https://github.com/opendistro-for-elasticsearch/sql/issues>`_ section to report bugs fixing or request new features.
+
+.. code-block:: JSON
+
+    #Disable query analysis
+    curl -H 'Content-Type: application/json' -X PUT localhost:9200/_cluster/settings -d '{
+      "persistent" : {
+        "opendistro.sql.query.analysis.enabled" : false
+      }
+    }'
+
+    #Verify if the query can pass the verification now
+    curl -H 'Content-Type: application/json' -X POST localhost:9200/_opendistro/_sql -d '{
+      "query" : "SELECT * FROM ..."
+    }'
+
+
+Index Mapping Verification Exception
+------------------------------------
+
+**Symptoms**
+
+.. code-block:: JSON
+
+    {
+      "error": {
+        "reason": "There was internal problem at backend",
+        "details": "When using multiple indices, the mappings must be identical.",
+        "type": "VerificationException"
+      },
+      "status": 503
+    }
+
+**Workaround**
+
+If index in query is not an index pattern (index name ends with wildcard), check if the index has multiple types. If nothing works during your workaround, please create an issue in our `GitHub Issues <https://github.com/opendistro-for-elasticsearch/sql/issues>`_ section so that we can provide you with our suggestions and help.

docs/user/index.rst

@@ -31,3 +31,7 @@ Open Distro for Elasticsearch SQL enables you to extract insights out of Elastic
 
   - TODO: Elasticsearch features
 
+* **Troubleshooting**
+
+  - `Troubleshooting <dql/troubleshooting.rst>`_
+

src/main/java/com/amazon/opendistroforelasticsearch/sql/domain/Condition.java

@@ -19,6 +19,7 @@
 import com.amazon.opendistroforelasticsearch.sql.exception.SqlParseException;
 import com.amazon.opendistroforelasticsearch.sql.parser.ChildrenType;
 import com.amazon.opendistroforelasticsearch.sql.parser.NestedType;
+import com.amazon.opendistroforelasticsearch.sql.utils.StringUtils;
 import com.google.common.collect.BiMap;
 import com.google.common.collect.HashBiMap;
 
@@ -33,7 +34,7 @@
  */
 public class Condition extends Where {
 
-    public enum OPEAR {
+    public enum OPERATOR {
 
         EQ,
         GT,
@@ -64,15 +65,15 @@ public enum OPEAR {
         NIN_TERMS,
         NTERM;
 
-        public static Map<String, OPEAR> methodNameToOpear;
+        public static Map<String, OPERATOR> methodNameToOpear;
 
-        public static Map<String, OPEAR> operStringToOpear;
+        public static Map<String, OPERATOR> operStringToOpear;
 
-        public static Map<String, OPEAR> simpleOperStringToOpear;
+        public static Map<String, OPERATOR> simpleOperStringToOpear;
 
-        private static BiMap<OPEAR, OPEAR> negatives;
+        private static BiMap<OPERATOR, OPERATOR> negatives;
 
-        private static BiMap<OPEAR, OPEAR> simpleReverses;
+        private static BiMap<OPERATOR, OPERATOR> simpleReverses;
 
         static {
             methodNameToOpear = new HashMap<>();
@@ -145,20 +146,22 @@ public enum OPEAR {
             simpleReverses.put(N, N);
         }
 
-        public OPEAR negative() throws SqlParseException {
-            OPEAR negative = negatives.get(this);
+        public OPERATOR negative() throws SqlParseException {
+            OPERATOR negative = negatives.get(this);
             negative = negative != null ? negative : negatives.inverse().get(this);
             if (negative == null) {
-                throw new SqlParseException("OPEAR negative not supported: " + this);
+                throw new SqlParseException(StringUtils.format("Negative operator [%s] is not supported.",
+                        this.name()));
             }
             return negative;
         }
 
-        public OPEAR simpleReverse() throws SqlParseException {
-            OPEAR reverse = simpleReverses.get(this);
+        public OPERATOR simpleReverse() throws SqlParseException {
+            OPERATOR reverse = simpleReverses.get(this);
             reverse = reverse != null ? reverse : simpleReverses.inverse().get(this);
             if (reverse == null) {
-                throw new SqlParseException("OPEAR simple negative not supported: " + this);
+                throw new SqlParseException(StringUtils.format("Simple reverse operator [%s] is not supported.",
+                        this.name()));
             }
             return reverse;
         }
@@ -184,7 +187,7 @@ public SQLExpr getValueExpr() {
 
     private SQLExpr valueExpr;
 
-    private OPEAR opear;
+    private OPERATOR OPERATOR;
 
     private Object relationshipType;
 
@@ -199,7 +202,7 @@ public Condition(CONN conn, String field, SQLExpr nameExpr, String condition, Ob
         this(conn, field, nameExpr, condition, obj, valueExpr, null);
     }
 
-    public Condition(CONN conn, String field, SQLExpr nameExpr, OPEAR condition, Object obj, SQLExpr valueExpr)
+    public Condition(CONN conn, String field, SQLExpr nameExpr, OPERATOR condition, Object obj, SQLExpr valueExpr)
             throws SqlParseException {
         this(conn, field, nameExpr, condition, obj, valueExpr, null);
     }
@@ -208,7 +211,7 @@ public Condition(CONN conn, String name, SQLExpr nameExpr, String oper,
                      Object value, SQLExpr valueExpr, Object relationshipType) throws SqlParseException {
         super(conn);
 
-        this.opear = null;
+        this.OPERATOR = null;
         this.name = name;
         this.value = value;
         this.nameExpr = nameExpr;
@@ -239,30 +242,30 @@ public Condition(CONN conn, String name, SQLExpr nameExpr, String oper,
             this.childType = "";
         }
 
-        if (OPEAR.operStringToOpear.containsKey(oper)) {
-            this.opear = OPEAR.operStringToOpear.get(oper);
+        if (OPERATOR.operStringToOpear.containsKey(oper)) {
+            this.OPERATOR = OPERATOR.operStringToOpear.get(oper);
         } else {
-            throw new SqlParseException(oper + " is not a supported operation");
+            throw new SqlParseException("Unsupported operation: " + oper);
         }
     }
 
 
     public Condition(CONN conn,
                      String name,
                      SQLExpr nameExpr,
-                     OPEAR oper,
+                     OPERATOR oper,
                      Object value,
                      SQLExpr valueExpr,
                      Object relationshipType
     ) throws SqlParseException {
         super(conn);
 
-        this.opear = null;
+        this.OPERATOR = null;
         this.nameExpr = nameExpr;
         this.valueExpr = valueExpr;
         this.name = name;
         this.value = value;
-        this.opear = oper;
+        this.OPERATOR = oper;
         this.relationshipType = relationshipType;
 
         if (this.relationshipType != null) {
@@ -290,7 +293,7 @@ public Condition(CONN conn,
     }
 
     public String getOpertatorSymbol() throws SqlParseException {
-        switch (opear) {
+        switch (OPERATOR) {
             case EQ:
                 return "==";
             case GT:
@@ -309,7 +312,7 @@ public String getOpertatorSymbol() throws SqlParseException {
             case ISN:
                 return "!=";
             default:
-                throw new SqlParseException(opear + " is err!");
+                throw new SqlParseException(StringUtils.format("Failed to parse operator [%s]", OPERATOR));
         }
     }
 
@@ -330,12 +333,12 @@ public void setValue(Object value) {
         this.value = value;
     }
 
-    public OPEAR getOpear() {
-        return opear;
+    public OPERATOR getOPERATOR() {
+        return OPERATOR;
     }
 
-    public void setOpear(OPEAR opear) {
-        this.opear = opear;
+    public void setOPERATOR(OPERATOR OPERATOR) {
+        this.OPERATOR = OPERATOR;
     }
 
     public Object getRelationshipType() {
@@ -379,12 +382,12 @@ public void setChildType(String childType) {
     }
 
     /**
-     * Return true if the opear is {@link OPEAR#NESTED_COMPLEX}
-     * For example, the opear is {@link OPEAR#NESTED_COMPLEX} when condition is
+     * Return true if the opear is {@link OPERATOR#NESTED_COMPLEX}
+     * For example, the opear is {@link OPERATOR#NESTED_COMPLEX} when condition is
      * nested('projects', projects.started_year > 2000 OR projects.name LIKE '%security%')
      */
     public boolean isNestedComplex() {
-        return OPEAR.NESTED_COMPLEX == opear;
+        return OPERATOR.NESTED_COMPLEX == OPERATOR;
     }
 
     @Override
@@ -405,9 +408,9 @@ public String toString() {
         }
 
         if (value instanceof Object[]) {
-            result += this.conn + " " + this.name + " " + this.opear + " " + Arrays.toString((Object[]) value);
+            result += this.conn + " " + this.name + " " + this.OPERATOR + " " + Arrays.toString((Object[]) value);
         } else {
-            result += this.conn + " " + this.name + " " + this.opear + " " + this.value;
+            result += this.conn + " " + this.name + " " + this.OPERATOR + " " + this.value;
         }
 
         return result;
@@ -417,7 +420,7 @@ public String toString() {
     public Object clone() throws CloneNotSupportedException {
         try {
             return new Condition(this.getConn(), this.getName(), this.getNameExpr(),
-                    this.getOpear(), this.getValue(), this.getValueExpr(), this.getRelationshipType());
+                    this.getOPERATOR(), this.getValue(), this.getValueExpr(), this.getRelationshipType());
         } catch (SqlParseException e) {
 
         }

src/main/java/com/amazon/opendistroforelasticsearch/sql/domain/Having.java

@@ -178,7 +178,7 @@ private String doExplain(List<Where> wheres) throws SqlParseException {
     private String createScript(Condition cond) throws SqlParseException {
         String name = cond.getName();
         Object value = cond.getValue();
-        switch (cond.getOpear()) {
+        switch (cond.getOPERATOR()) {
             case EQ:
             case GT:
             case LT:
@@ -206,7 +206,7 @@ private String createScript(Condition cond) throws SqlParseException {
                         map(val -> expr(name, "!=", val)).
                         collect(joining(AND));
             default:
-                throw new SqlParseException("Unsupported operation in HAVING clause: " + cond.getOpear());
+                throw new SqlParseException("Unsupported operation in HAVING clause: " + cond.getOPERATOR());
         }
     }
 

src/main/java/com/amazon/opendistroforelasticsearch/sql/domain/SearchResult.java

@@ -135,7 +135,7 @@ private Object covenValue(Aggregation value) throws SqlParseException {
         } else if (value instanceof LongTerms) {
             return value;
         } else {
-            throw new SqlParseException("unknow this agg type " + value.getClass());
+            throw new SqlParseException("Unknown aggregation value type: " + value.getClass().getSimpleName());
         }
     }
 

src/main/java/com/amazon/opendistroforelasticsearch/sql/executor/GetIndexRequestRestListener.java

@@ -15,6 +15,7 @@
 
 package com.amazon.opendistroforelasticsearch.sql.executor;
 
+import com.amazon.opendistroforelasticsearch.sql.antlr.semantic.SemanticAnalysisException;
 import com.carrotsearch.hppc.cursors.ObjectObjectCursor;
 import org.elasticsearch.action.admin.indices.get.GetIndexRequest;
 import org.elasticsearch.action.admin.indices.get.GetIndexResponse;
@@ -65,7 +66,7 @@ public RestResponse buildResponse(GetIndexResponse getIndexResponse, XContentBui
                         writeSettings(getIndexResponse.settings().get(index), builder, channel.request());
                         break;
                     default:
-                        throw new IllegalStateException("feature [" + feature + "] is not valid");
+                        throw new SemanticAnalysisException("Unsupported feature: " + feature);
                 }
             }
             builder.endObject();

src/main/java/com/amazon/opendistroforelasticsearch/sql/executor/join/NestedLoopsElasticExecutor.java

@@ -307,11 +307,11 @@ private void orderConditionRecursive(String t1Alias, String t2Alias, Where where
 
     private Boolean shouldReverse(Condition cond, String t1Alias, String t2Alias) {
         return cond.getName().startsWith(t1Alias + ".") && cond.getValue().toString().startsWith(t2Alias + ".")
-                && cond.getOpear().isSimpleOperator();
+                && cond.getOPERATOR().isSimpleOperator();
     }
 
     private void reverseOrderOfCondition(Condition cond, String t1Alias, String t2Alias) throws SqlParseException {
-        cond.setOpear(cond.getOpear().simpleReverse());
+        cond.setOPERATOR(cond.getOPERATOR().simpleReverse());
         String name = cond.getName();
         cond.setName(cond.getValue().toString().replaceFirst(t2Alias + ".", ""));
         cond.setValue(name.replaceFirst(t1Alias + ".", ""));

src/main/java/com/amazon/opendistroforelasticsearch/sql/executor/multi/MinusExecutor.java

@@ -37,7 +37,6 @@
 import org.elasticsearch.search.SearchHit;
 import org.elasticsearch.search.SearchHits;
 
-import java.io.IOException;
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashMap;
@@ -77,12 +76,14 @@ public MinusExecutor(Client client, MultiQueryRequestBuilder builder) {
     }
 
     @Override
-    public void run() throws IOException, SqlParseException {
+    public void run() throws SqlParseException {
         if (this.useTermsOptimization && this.fieldsOrderFirstTable.length != 1) {
-            throw new SqlParseException("terms optimization supports minus with only one field");
+            throw new SqlParseException(
+                    "Terms optimization failed: terms optimization for minus execution is supported with one field");
         }
         if (this.useTermsOptimization && !this.useScrolling) {
-            throw new SqlParseException("terms optimization work only with scrolling add scrolling hint");
+            throw new SqlParseException(
+                    "Terms optimization failed: using scrolling is required for terms optimization");
         }
         if (!this.useScrolling || !this.useTermsOptimization) {
             Set<ComperableHitResult> comperableHitResults;
@@ -367,7 +368,7 @@ private Where createWhereWithOrigianlAndTermsFilter(String secondFieldName, Wher
     }
 
     private Where buildTermsFilterFromResults(Set<Object> results, String fieldName) throws SqlParseException {
-        return new Condition(Where.CONN.AND, fieldName, null, Condition.OPEAR.IN_TERMS, results.toArray(), null);
+        return new Condition(Where.CONN.AND, fieldName, null, Condition.OPERATOR.IN_TERMS, results.toArray(), null);
     }
 
     private Object getFieldValue(SearchHit hit, String fieldName) {