Modified the wording of exception messages and created the troubleshooting page

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;
 
@@ -242,7 +243,7 @@ public Condition(CONN conn, String name, SQLExpr nameExpr, String oper,
         if (OPEAR.operStringToOpear.containsKey(oper)) {
             this.opear = OPEAR.operStringToOpear.get(oper);
         } else {
-            throw new SqlParseException(oper + " is not a supported operation");
+            throw new SqlParseException("Unsupported operation: " + oper);
         }
     }
 
@@ -309,7 +310,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]", opear));
         }
     }
 

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());
         }
     }
 

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

@@ -65,7 +65,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 IllegalStateException("Unsupported feature: " + feature);
                 }
             }
             builder.endObject();

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;

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

@@ -15,6 +15,7 @@
 
 package com.amazon.opendistroforelasticsearch.sql.executor.multi;
 
+import com.alibaba.druid.sql.ast.statement.SQLUnionOperator;
 import com.amazon.opendistroforelasticsearch.sql.exception.SqlParseException;
 import com.amazon.opendistroforelasticsearch.sql.executor.ElasticHitsExecutor;
 import com.amazon.opendistroforelasticsearch.sql.query.multi.MultiQueryRequestBuilder;
@@ -26,14 +27,15 @@
 public class MultiRequestExecutorFactory {
     public static ElasticHitsExecutor createExecutor(Client client, MultiQueryRequestBuilder builder)
             throws SqlParseException {
-        switch (builder.getRelation()) {
+        SQLUnionOperator relation = builder.getRelation();
+        switch (relation) {
             case UNION_ALL:
             case UNION:
                 return new UnionExecutor(client, builder);
             case MINUS:
                 return new MinusExecutor(client, builder);
             default:
-                throw new SqlParseException("only supports union, and minus operations");
+                throw new SqlParseException("Unsupported operator: " + relation);
         }
     }
 }

src/main/java/com/amazon/opendistroforelasticsearch/sql/parser/ChildrenType.java

@@ -66,7 +66,7 @@ public boolean tryFillFromExpr(SQLExpr expr) throws SqlParseException {
             Where where = Where.newInstance();
             new WhereParser(new SqlParser()).parseWhere(secondParameter, where);
             if (where.getWheres().size() == 0) {
-                throw new SqlParseException("unable to parse filter where.");
+                throw new SqlParseException("Failed to parse filter condition");
             }
             this.where = where;
             simple = false;

src/main/java/com/amazon/opendistroforelasticsearch/sql/parser/ElasticSqlExprParser.java

@@ -120,7 +120,7 @@ protected SQLExpr methodRest(SQLExpr expr, boolean acceptLPAREN) {
             return primaryRest(methodInvokeExpr);
         }
 
-        throw new ParserException("not support token:" + lexer.token());
+        throw new ParserException("Syntax error:" + lexer.token());
     }
 
 
@@ -283,7 +283,7 @@ public SQLExpr primary2() {
             case VALUES:
                 lexer.nextToken();
                 if (lexer.token() != Token.LPAREN) {
-                    throw new ParserException("syntax error, illegal values clause");
+                    throw new ParserException("Syntax error: " + lexer.token());
                 }
                 return this.methodRest(new SQLIdentifierExpr("VALUES"), true);
             case BINARY:
@@ -310,7 +310,7 @@ public SQLExpr primary2() {
 
     public final SQLExpr primaryRest(SQLExpr expr) {
         if (expr == null) {
-            throw new IllegalArgumentException("expr");
+            throw new IllegalArgumentException("Illegal expression: NULL");
         }
 
         if (lexer.token() == Token.LITERAL_CHARS) {
@@ -363,7 +363,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                 if ("USING".equalsIgnoreCase(lexer.stringVal())) {
                     lexer.nextToken();
                     if (lexer.token() != Token.IDENTIFIER) {
-                        throw new ParserException("syntax error, illegal hex");
+                        throw new ParserException("Syntax error: " + lexer.token());
                     }
                     String charSet = lexer.stringVal();
                     lexer.nextToken();
@@ -379,7 +379,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                 }
 
                 if (lexer.token() != Token.IDENTIFIER) {
-                    throw new ParserException("syntax error");
+                    throw new ParserException("Syntax error: " + lexer.token());
                 }
 
                 String collate = lexer.stringVal();
@@ -394,7 +394,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                     lexer.nextToken();
 
                     if (lexer.token() != Token.IDENTIFIER) {
-                        throw new ParserException("syntax error");
+                        throw new ParserException("Syntax error: " + lexer.token());
                     }
 
                     String collate = lexer.stringVal();
@@ -424,7 +424,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                 lexer.nextToken();
 
                 if (lexer.token() != Token.IDENTIFIER) {
-                    throw new ParserException("syntax error");
+                    throw new ParserException("Syntax error: " + lexer.token());
                 }
 
                 String unitVal = lexer.stringVal();
@@ -467,7 +467,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                     } else if (lexer.token() == Token.RPAREN) {
                         break;
                     } else {
-                        throw new ParserException("syntax error");
+                        throw new ParserException("Syntax error: " + lexer.token());
                     }
                 }
 
@@ -544,10 +544,10 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                         acceptIdentifier("MODE");
                         matchAgainstExpr.setSearchModifier(MySqlMatchAgainstExpr.SearchModifier.IN_BOOLEAN_MODE);
                     } else {
-                        throw new ParserException("TODO");
+                        throw new ParserException("Syntax error: " + lexer.token());
                     }
                 } else if (lexer.token() == Token.WITH) {
-                    throw new ParserException("TODO");
+                    throw new ParserException("Syntax error: " + lexer.token());
                 }
 
                 accept(Token.RPAREN);
@@ -566,7 +566,7 @@ public final SQLExpr primaryRest(SQLExpr expr) {
                 if (identifierEquals("USING")) {
                     lexer.nextToken();
                     if (lexer.token() != Token.IDENTIFIER) {
-                        throw new ParserException("syntax error");
+                        throw new ParserException("Syntax error: " + lexer.token());
                     }
                     String charset = lexer.stringVal();
                     lexer.nextToken();
@@ -651,7 +651,7 @@ protected SQLExpr bracketRest(SQLExpr expr) {
             index = lexer.integerValue();
             lexer.nextToken();
         } else {
-            throw new ParserException("error : " + lexer.stringVal());
+            throw new ParserException("Syntax error : " + lexer.stringVal());
         }
 
         if (expr instanceof SQLMethodInvokeExpr) {
@@ -685,7 +685,7 @@ protected SQLExpr parseInterval() {
             SQLExpr value = expr();
 
             if (lexer.token() != Token.IDENTIFIER) {
-                throw new ParserException("Syntax error");
+                throw new ParserException("Syntax error: " + lexer.token());
             }
 
             String unit = lexer.stringVal();

src/main/java/com/amazon/opendistroforelasticsearch/sql/parser/ElasticSqlSelectParser.java

@@ -33,10 +33,10 @@
 import com.alibaba.druid.sql.dialect.mysql.ast.statement.MySqlSelectGroupBy;
 import com.alibaba.druid.sql.dialect.mysql.ast.statement.MySqlSelectQueryBlock;
 import com.alibaba.druid.sql.dialect.mysql.ast.statement.MySqlUnionQuery;
-import com.alibaba.druid.sql.parser.ParserException;
 import com.alibaba.druid.sql.parser.SQLExprParser;
 import com.alibaba.druid.sql.parser.SQLSelectParser;
 import com.alibaba.druid.sql.parser.Token;
+import com.amazon.opendistroforelasticsearch.sql.exception.SqlFeatureNotImplementedException;
 
 /**
  * Created by allwefantasy on 8/19/16.
@@ -140,7 +140,7 @@ public SQLSelectQuery query() {
 
         if (lexer.token() == Token.PROCEDURE) {
             lexer.nextToken();
-            throw new ParserException("TODO");
+            throw new SqlFeatureNotImplementedException("Unsupported feature: " + Token.PROCEDURE.name);
         }
 
         parseInto(queryBlock);

src/main/java/com/amazon/opendistroforelasticsearch/sql/parser/FieldMaker.java

@@ -196,7 +196,7 @@ private static Field makeFilterMethodField(SQLMethodInvokeExpr filterMethod, Str
         Where where = Where.newInstance();
         new WhereParser(new SqlParser()).parseWhere(exprToCheck, where);
         if (where.getWheres().size() == 0) {
-            throw new SqlParseException("unable to parse filter where.");
+            throw new SqlParseException("Failed to parse filter condition");
         }
         List<KVValue> methodParameters = new ArrayList<>();
         methodParameters.add(new KVValue("where", where));
@@ -248,7 +248,7 @@ public SQLMethodInvokeExpr makeBinaryMethodField(SQLBinaryOpExpr expr, String al
             case Subtract:
                 return convertBinaryOperatorToMethod("subtract", expr);
             default:
-                throw new SqlParseException(expr.getOperator().getName() + " is not support");
+                throw new SqlParseException("Unsupported operator: " + expr.getOperator().getName());
         }
     }
 
@@ -317,7 +317,7 @@ public MethodField makeMethodField(String name, List<SQLExpr> arguments, SQLAggr
                     NestedType nestedType = new NestedType();
 
                     if (!nestedType.tryFillFromExpr(object)) {
-                        throw new SqlParseException("failed parsing nested expr " + object);
+                        throw new SqlParseException("Failed to parse nested expression: " + object);
                     }
 
                     // Fix bug: method name of reversed_nested() was set to "nested" wrongly
@@ -326,7 +326,7 @@ public MethodField makeMethodField(String name, List<SQLExpr> arguments, SQLAggr
                     ChildrenType childrenType = new ChildrenType();
 
                     if (!childrenType.tryFillFromExpr(object)) {
-                        throw new SqlParseException("failed parsing children expr " + object);
+                        throw new SqlParseException("Failed to parse children expression: " + object);
                     }
 
                     paramers.add(new KVValue("children", childrenType));

src/main/java/com/amazon/opendistroforelasticsearch/sql/parser/NestedType.java

@@ -63,7 +63,7 @@ public boolean tryFillFromExpr(SQLExpr expr) throws SqlParseException {
             //calc path myself..
             if (!field.contains(".")) {
                 if (!reverse) {
-                    throw new SqlParseException("nested should contain . on their field name");
+                    throw new IllegalArgumentException("Illegal nested field name: " + field);
                 } else {
                     this.path = null;
                     this.simple = true;
@@ -92,7 +92,7 @@ public boolean tryFillFromExpr(SQLExpr expr) throws SqlParseException {
                 Where where = Where.newInstance();
                 new WhereParser(new SqlParser()).parseWhere(secondParameter, where);
                 if (where.getWheres().size() == 0) {
-                    throw new SqlParseException("unable to parse filter where.");
+                    throw new SqlParseException("Failed to parse filter condition");
                 }
                 this.where = where;
                 simple = false;