Add documentation for errors and reserved keywords.
Change-Id: I0e48f8a6b7bc858ca565a428fa4d87ea31437de4
Reviewed-on: https://asterix-gerrit.ics.uci.edu/1239
Sonar-Qube: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Reviewed-by: Yingyi Bu <buyingyi@gmail.com>
diff --git a/asterixdb/asterix-doc/pom.xml b/asterixdb/asterix-doc/pom.xml
index 27a6095..f674f7f 100644
--- a/asterixdb/asterix-doc/pom.xml
+++ b/asterixdb/asterix-doc/pom.xml
@@ -54,7 +54,7 @@
<target>
<concat destfile="${project.build.directory}/generated-site/markdown/sqlpp/manual.md">
<filelist dir="${project.basedir}/src/main/markdown/sqlpp"
- files="0_toc.md,1_intro.md,2_expr.md,3_query.md,4_ddl.md"/>
+ files="0_toc.md,1_intro.md,2_expr.md,3_query.md,4_error.md,5_ddl.md,appendix_1_keywords.md"/>
</concat>
<concat destfile="${project.build.directory}/generated-site/markdown/sqlpp/builtins.md">
<filelist dir="${project.basedir}/src/main/markdown/builtins"
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
index bbe0566..b04ea6a 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
@@ -73,7 +73,12 @@
* [LET clauses](#Let_clauses)
* [UNION ALL](#Union_all)
* [SQL++ Vs. SQL-92](#Vs_SQL-92)
-* [4. DDL and DML statements](#DDL_and_DML_statements)
+* [4. Errors](#Errors)
+ * [Syntax errors](#Syntax_errors)
+ * [Identifier resolution errors](#Parsing_errors)
+ * [Type errors](#Type_errors)
+ * [Resource errors](#Resource_errors)
+* [5. DDL and DML statements](#DDL_and_DML_statements)
* [Declarations](#Declarations)
* [Lifecycle management statements](#Lifecycle_management_statements)
* [Dataverses](#Dataverses)
@@ -84,4 +89,5 @@
* [Inserts](#Inserts)
* [Upserts](#Upserts)
* [Deletes](#Deletes)
+* [Appendix 1. Reserved keywords](#Reserved_keywords)
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_error.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_error.md
new file mode 100644
index 0000000..60232e4
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_error.md
@@ -0,0 +1,97 @@
+# <a id="Errors">4. Errors</a>
+A SQL++ query can potentially result in one of the following errors:
+
+ * syntax error,
+ * identifier resolution error,
+ * type error,
+ * resource error.
+
+If the query processor runs into any error, it will
+terminate the ongoing processing of the query and
+immediately return an error message to the client.
+
+## <a id="Syntax_errors">Syntax Errors</a>
+An valid SQL++ query must satisfy the SQL++ grammar rules.
+Otherwise, a syntax error will be raised.
+
+##### Example
+
+ SELECT *
+ FROM GleambookUsers user
+
+Since the ending semi-colon is mandatory for any SQL++ query,
+we will get a syntax error as follows:
+
+ Error: Syntax error: In line 2 >>FROM GleambookUsers user<< Encountered <EOF> at column 24.
+ ==> FROM GleambookUsers user
+
+##### Example
+
+ SELECT *
+ FROM GleambookUsers user
+ WHERE type="advertiser";
+
+Since "type" a [reserved keyword](#Reserved_keywords) in the SQL++ parser,
+we will get a syntax error as follows:
+
+ Error: Syntax error: In line 3 >>WHERE type="advertiser";<< Encountered 'type' "type" at column 7.
+ ==> WHERE type="advertiser";
+
+
+## <a id="Identifier_resolution_errors">Identifier Resolution Errors</a>
+Referring an undefined identifier can cause an error if the identifier
+cannot be successfully resolved as a valid field access.
+
+##### Example
+
+ SELECT *
+ FROM GleambookUser user;
+
+Assume we have a typo in "GleambookUser" which misses the ending "s",
+we will get an identifier resolution error as follows:
+
+ Error: Cannot find dataset GleambookUser in dataverse Default nor an alias with name GleambookUser!
+
+##### Example
+
+ SELECT name, message
+ FROM GleambookUsers u JOIN GleambookMessages m ON m.authorId = u.id;
+
+If the compiler cannot figure out all possible fields in
+`GleambookUsers` and `GleambookMessages`,
+we will get an identifier resolution error as follows:
+
+ Error: Cannot resolve ambiguous alias reference for undefined identifier name
+
+
+## <a id="Type_errors">Type Errors</a>
+
+The SQL++ compiler does type checks based on its available type information.
+In addition, the SQL++ runtime also reports type errors if a data model instance
+it processes does not satisfy the type requirement.
+
+##### Example
+
+ abs("123");
+
+Since function `abs` can only process numeric input values,
+we will get a type error as follows:
+
+ Error: Arithmetic operations are not implemented for string
+
+
+## <a id="Resource_errors">Resource Errors</a>
+A query can potentially exhaust system resources, such
+as the number of open files and disk spaces.
+For instance, the following two resource errors could be potentially
+be seen when running the system:
+
+ Error: no space left on device
+ Error: too many open files
+
+The "no space left on device" issue usually can be fixed by
+cleaning up disk spaces and reserving more disk spaces for the system.
+The "too many open files" issue usually can be fixed by a system
+administrator, following the instructions
+[here](https://easyengine.io/tutorials/linux/increase-open-files-limit/).
+
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
similarity index 100%
rename from asterixdb/asterix-doc/src/main/markdown/sqlpp/4_ddl.md
rename to asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_1_keywords.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_1_keywords.md
new file mode 100644
index 0000000..b61528c
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_1_keywords.md
@@ -0,0 +1,26 @@
+# <a id="Reserved_keywords">Appendix 1. Reserved keywords</a>
+All reserved keywords are listed in the following table:
+
+| | | | | | |
+| ----|-----|-------|----|-----|----|
+| AND | ANY | APPLY | AS | ASC | AT |
+| AUTOGENERATED | BETWEEN | BTREE | BY | CASE | CLOSED |
+| CREATE | COMPACTION | COMPACT | CONNECT | CORRELATE | DATASET |
+| COLLECTION | DATAVERSE | DECLARE | DEFINITION | DECLARE | DEFINITION |
+| DELETE | DESC | DISCONNECT | DISTINCT | DROP | ELEMENT |
+| ELEMENT | EXPLAIN | ELSE | ENFORCED | END | EVERY |
+| EXCEPT | EXIST | EXTERNAL | FEED | FILTER | FLATTEN |
+| FOR | EXIST | EXTERNAL | FEED | FILTER | FLATTEN |
+| FROM | FULL | FUNCTION | GROUP | HAVING | HINTS |
+| IF | INTO | IN | INDEX | INGESTION | INNER |
+| INSERT | INTERNAL | INTERSECT | IS | JOIN | KEYWORD |
+| LEFT | LETTING | LET | LIKE | LIMIT | LOAD |
+| NODEGROUP | NGRAM | NOT | OFFSET | ON | OPEN |
+| OR | ORDER | OUTER | OUTPUT | PATH | POLICY |
+| PRE-SORTED | PRIMARY | RAW | REFRESH | RETURN | RTREE |
+| RUN | SATISFIES | SECONDARY | SELECT | SET | SOME |
+| TEMPORARY | THEN | TYPE | UNKNOWN | UNNEST | UPDATE |
+| USE | USING | VALUE | WHEN | WHERE | WITH |
+| WRITE | | | | | |
+
+