Add documentation for query parameters.
Change-Id: I80dcd668bea3b2b3fff0c0778548ffad63505d99
Reviewed-on: https://asterix-gerrit.ics.uci.edu/1586
Reviewed-by: Michael Blow <mblow@apache.org>
Sonar-Qube: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
Tested-by: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
BAD: Jenkins <jenkins@fulliautomatix.ics.uci.edu>
diff --git a/asterixdb/asterix-doc/pom.xml b/asterixdb/asterix-doc/pom.xml
index 59d45fd..df6db2c 100644
--- a/asterixdb/asterix-doc/pom.xml
+++ b/asterixdb/asterix-doc/pom.xml
@@ -53,7 +53,7 @@
<configuration>
<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_error.md,5_ddl.md,appendix_1_keywords.md" />
+ <filelist dir="${project.basedir}/src/main/markdown/sqlpp" files="0_toc.md,1_intro.md,2_expr.md,3_query.md,4_error.md,5_ddl.md,appendix_1_keywords.md,appendix_2_parameter.md" />
</concat>
<concat destfile="${project.build.directory}/generated-site/markdown/sqlpp/builtins.md">
<filelist dir="${project.basedir}/src/main/markdown/builtins" files="0_toc.md,1_numeric.md,2_string.md,3_binary.md,4_spatial.md,5_similarity.md,6_tokenizing.md,7_temporal.md,7_allens.md,8_record.md,9_aggregate_sql.md,10_comparison.md,11_type.md,12_misc.md" />
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 ff31357..6dd81bf 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
@@ -90,4 +90,7 @@
* [Upserts](#Upserts)
* [Deletes](#Deletes)
* [Appendix 1. Reserved keywords](#Reserved_keywords)
+* [Appendix 2. Performance tuning](#Performance_tuning)
+ * [Parallelism parameter](#Parallelism_parameter)
+ * [Memory parameters](#Memory_parameters)
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
index b6577ff..e7625b8 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
@@ -17,7 +17,7 @@
! under the License.
!-->
-# <a id="DDL_and_DML_statements">4. DDL and DML statements</a>
+# <a id="DDL_and_DML_statements">5. DDL and DML statements</a>
Statement ::= ( SingleStatement ( ";" )? )* <EOF>
SingleStatement ::= DatabaseDeclaration
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_2_parameter.md b/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_2_parameter.md
new file mode 100644
index 0000000..6ef0dd6
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/appendix_2_parameter.md
@@ -0,0 +1,70 @@
+## <a id="Performance_tuning">Appendix 2. Performance tuning</a>
+The SET statement can be used to override some cluster-wide configuration parameters for a specific request:
+
+ SET <IDENTIFIER> <STRING_LITERAL>
+
+As parameter identifiers are qualified names (containing a '.') they have to be escaped using backticks (\`\`).
+Note that changing query parameters will not affect query correctness but only impact performance
+characteristics, such as response time and throughput.
+
+## <a id="Parallelism_parameter">Parallelism parameter</a>
+The system can execute each request using multiple cores on multiple machines (a.k.a., partitioned parallelism)
+in a cluster. A user can manually specify the maximum execution parallelism for a request to scale it up and down
+using the following parameter:
+
+* **compiler.parallelism**: the maximum number of CPU cores can be used to process a query.
+There are three cases of the value *p* for compiler.parallelism:
+
+ - *p* \< 0 or *p* \> the total number of cores in a cluster: the system will use all available cores in the
+ cluster;
+
+ - *p* = 0 (the default): the system will use the storage parallelism (the number of partitions of stored datasets)
+ as the maximum parallelism for query processing;
+
+ - all other cases: the system will use the user-specified number as the maximum number of CPU cores to use for
+ executing the query.
+
+## <a id="Memory_parameters">Memory parameters</a>
+In the system, each blocking runtime operator such as join, group-by and order-by
+works within a fixed memory budget, and can gracefully spill to disks if
+the memory budget is smaller than the amount of data they have to hold.
+A user can manually configure the memory budget of those operators within a query.
+The supported configurable memory parameters are:
+
+* **compiler.groupmemory**: the memory budget that each parallel group-by operator instance can use;
+ 32MB is the default budget.
+
+* **compiler.sortmemory**: the memory budget that each parallel sort operator instance can use;
+ 32MB is the default budget.
+
+* **compiler.joinmemory**: the memory budget that each parallel hash join operator instance can use;
+ 32MB is the default budget.
+
+For each memory budget value, you can use a 64-bit integer value
+with a 1024-based binary unit suffix (e.g., B, KB, MB, GB).
+If there is no user-provided suffix, "B" is the default suffix. See the following examples.
+
+##### Example
+
+ SET `compiler.groupmemory` "64MB"
+
+ SELECT msg.authorId, COUNT(*)
+ FROM GleambookMessages msg
+ GROUP BY msg.authorId;
+
+##### Example
+
+ SET `compiler.sortmemory` "67108864"
+
+ SELECT VALUE user
+ FROM GleambookUsers AS user
+ ORDER BY ARRAY_LENGTH(user.friendIds) DESC;
+
+##### Example
+
+ SET `compiler.joinmemory` "132000KB"
+
+ SELECT u.name AS uname, m.message AS message
+ FROM GleambookUsers u JOIN GleambookMessages m ON m.authorId = u.id;
+
+
diff --git a/asterixdb/asterix-doc/src/site/site.xml b/asterixdb/asterix-doc/src/site/site.xml
index 3e768bf..a2fee6c 100644
--- a/asterixdb/asterix-doc/src/site/site.xml
+++ b/asterixdb/asterix-doc/src/site/site.xml
@@ -100,18 +100,18 @@
<item name="Builtin Functions" href="aql/builtins.html"/>
</menu>
+ <menu name="API/SDK">
+ <item name="HTTP API" href="api.html"/>
+ <item name="CSV Output" href="csv.html"/>
+ </menu>
+
<menu name="Advanced Features">
- <item name="Support of Similarity Queries" href="aql/similarity.html"/>
<item name="Support of Full-text Queries" href="aql/fulltext.html"/>
<item name="Accessing External Data" href="aql/externaldata.html"/>
<item name="Support for Data Ingestion" href="feeds/tutorial.html"/>
<item name="User Defined Functions" href="udf.html"/>
<item name="Filter-Based LSM Index Acceleration" href="aql/filters.html"/>
- </menu>
-
- <menu name="API/SDK">
- <item name="HTTP API" href="api.html"/>
- <item name="CSV Output" href="csv.html"/>
+ <item name="Support of Similarity Queries" href="aql/similarity.html"/>
</menu>
<menu ref="reports"/>