Yingyi Bu has uploaded a new change for review.
https://asterix-gerrit.ics.uci.edu/1586
Change subject: Add documentation for query parameters.
......................................................................
Add documentation for query parameters.
Change-Id: I80dcd668bea3b2b3fff0c0778548ffad63505d99
---
M asterixdb/asterix-doc/pom.xml
M asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
A asterixdb/asterix-doc/src/main/markdown/sqlpp/4_parameter.md
R asterixdb/asterix-doc/src/main/markdown/sqlpp/5_error.md
R asterixdb/asterix-doc/src/main/markdown/sqlpp/6_ddl.md
5 files changed, 83 insertions(+), 5 deletions(-)
git pull ssh://asterix-gerrit.ics.uci.edu:29418/asterixdb
refs/changes/86/1586/1
diff --git a/asterixdb/asterix-doc/pom.xml b/asterixdb/asterix-doc/pom.xml
index 59d45fd..da7ed12 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_parameter.md,5_error.md,6_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"
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..db1730b 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/0_toc.md
@@ -73,12 +73,15 @@
* [LET clauses](#Let_clauses)
* [UNION ALL](#Union_all)
* [SQL++ Vs. SQL-92](#Vs_SQL-92)
-* [4. Errors](#Errors)
+* [4. Performance Tuning](#Tuning)
+ * [Parallelism parameter](#Parallelism_parameter)
+ * [Memory parameters](#Memory_parameters)
+* [5. 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)
+* [6. DDL and DML statements](#DDL_and_DML_statements)
* [Declarations](#Declarations)
* [Lifecycle management statements](#Lifecycle_management_statements)
* [Dataverses](#Dataverses)
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_parameter.md
b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_parameter.md
new file mode 100644
index 0000000..c835ff9
--- /dev/null
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_parameter.md
@@ -0,0 +1,75 @@
+# <a id="Tuning">4. Performance Tuning</a>
+
+A user can override several query-related parameters that are specified in the
+instance-level configuration file, for a particular query, using the following
syntax:
+
+ SET <IDENTIFIER> <STRING_LITERAL>
+
+Since each parameter described as follows
+is a fully qualified name, we have to use a backtick (\`\`) to make it a
delimited identifier.
+According to the syntax, the value part of each parameter has to always be a
string.
+Note that changing those query parameters will not affect query correctness
but only impact performance
+characteristics.
+
+## <a id="Parallelism_parameter">Parallelism parameter</a>
+Since the system can execute each individual query using multiple machines
(a.k.a., partitioned parallelism)
+in a cluster, a user can manually specify the maximum execution parallelism
for a query to scale it up and down,
+based on on her/his own need, 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>
+A user can manually configure the memory budget of runtime data processing
operators
+that consume a chunk of memory, such as join, group-by and order-by, within a
query.
+Note that in the system, all those runtime operators can gracefully spill to
disks even if
+the memory budget is much smaller than the mount of data they process,
+bust still, changing the memory budget can have impacts on performance
characteristics such as response
+time and throughput. The supported configurable parameters are listed as
follows:
+
+* **compiler.groupmemory**: the memory budget that each parallel group by
operator instance can use;
+ 32MB is the default budget.
+
+* **compiler.joinmemory**: the memory budget that each parallel sort operator
instance can use;
+ 32MB is the default budget.
+
+* **compiler.sortmemory**: the memory budget that each parallel hash join
operator instance can use;
+ 32MB is the default budget.
+
+For the memory budget value, you can use integer, long, or an integer/long
value with KB/MB/GB suffix.
+If there is no user-provided suffix, "bytes" 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
+ LIMIT 1;
+
+##### 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/main/markdown/sqlpp/4_error.md
b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_error.md
similarity index 98%
rename from asterixdb/asterix-doc/src/main/markdown/sqlpp/4_error.md
rename to asterixdb/asterix-doc/src/main/markdown/sqlpp/5_error.md
index 60232e4..02b4564 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/4_error.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_error.md
@@ -1,4 +1,4 @@
-# <a id="Errors">4. Errors</a>
+# <a id="Errors">5. Errors</a>
A SQL++ query can potentially result in one of the following errors:
* syntax error,
diff --git a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
b/asterixdb/asterix-doc/src/main/markdown/sqlpp/6_ddl.md
similarity index 99%
rename from asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
rename to asterixdb/asterix-doc/src/main/markdown/sqlpp/6_ddl.md
index b6577ff..a60a731 100644
--- a/asterixdb/asterix-doc/src/main/markdown/sqlpp/5_ddl.md
+++ b/asterixdb/asterix-doc/src/main/markdown/sqlpp/6_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">6. DDL and DML statements</a>
Statement ::= ( SingleStatement ( ";" )? )* <EOF>
SingleStatement ::= DatabaseDeclaration
--
To view, visit https://asterix-gerrit.ics.uci.edu/1586
To unsubscribe, visit https://asterix-gerrit.ics.uci.edu/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I80dcd668bea3b2b3fff0c0778548ffad63505d99
Gerrit-PatchSet: 1
Gerrit-Project: asterixdb
Gerrit-Branch: master
Gerrit-Owner: Yingyi Bu <[email protected]>
