asterixdb-notifications mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Yingyi Bu (Code Review)" <do-not-re...@asterixdb.incubator.apache.org>
Subject Change in asterixdb[master]: Add documentation for query parameters.
Date Thu, 16 Mar 2017 00:03:42 GMT
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 <buyingyi@gmail.com>

Mime
View raw message