HAWQ-1382 Specify necessary setup for hawq_rm_stmt_nvseg and hawq_rm_…

…stmt_vseg_memory (closes #103)

markdown/bestpractices/managing_resources_bestpractices.html.md.erb

@@ -110,11 +110,14 @@ ALTER RESOURCE queue1 WITH (VSEG_RESOURCE_QUOTA='mem:2gb');
 If there are only occasional queries on Parquet tables with a large page size, use a statement level specification instead of altering the resource queue. For example:
 
 ```sql
-SET HAWQ_RM_STMT_NVSEG=10;
-SET HAWQ_RM_STMT_VSEG_MEMORY='2gb';
-query1;
-SET HAWQ_RM_STMT_NVSEG=0;
+postgres=# SET hawq_rm_stmt_nvseg=10;
+postgres=# SET hawq_rm_stmt_vseg_memory='2gb';
+postgres=# query1;
+postgres=# SET hawq_rm_stmt_nvseg=0;
+SET
 ```
+***Note:*** To set the parameters at the statement level, you must set `hawq_rm_stmt_nvseg` to a value greater than 0 before setting `hawq_rm_stmt_vseg_memory`. After running a query or completing the session, the value of `hawq_rm_stmt_nvseg` should be reset to 0,  as shown in the example above.
+
 
 ### Restricting Resource Consumption for Specific Queries
 
@@ -161,3 +164,4 @@ In order to raise the minimum number of virtual segments available for a query s
     In the second DDL, if there are 10 nodes in the cluster, the actual minimum number of virtual segments is 50 (5 \* 10 = 50).
 
 
+

markdown/reference/guc/parameter_definitions.html.md.erb

@@ -2067,15 +2067,15 @@ HAWQ resource manager segment server port number.
 
 ## <a name="hawq_rm_stmt_nvseg"></a>hawq\_rm\_stmt\_nvseg
 
-Defines the number of virtual segments to use for the next query's execution. The default value is 0 which means statement level resource quota setting is disabled.
+Defines the number of virtual segments to use for the next query's execution. The default value is 0, which means statement level resource quota setting is disabled.
 
 | Value Range | Default | Set Classifications     |
 |-------------|---------|-------------------------|
 | 0 to 65535  | 0       | master, session, reload |
 
 ## <a name="hawq_rm_stmt_vseg_memory"></a>hawq\_rm\_stmt\_vseg\_memory
 
-Defines the memory quota of one virtual segment.
+Defines the memory quota of one virtual segment. You must set the number of virtual segments to a number greater than 0 in `hawq_rm_stmt_nvseg` before specifying the memory quota.  
 
 | Value Range                                                                         | Default | Set Classifications     |
 |-------------------------------------------------------------------------------------|---------|-------------------------|

markdown/resourcemgmt/ConfigureResourceManagement.html.md.erb

@@ -100,22 +100,25 @@ In some cases, you may want to specify additional resource quotas on the query s
 
 The following configuration properties allow a user to control resource quotas without altering corresponding resource queues.
 
--   [hawq\_rm\_stmt\_vseg\_memory](../reference/guc/parameter_definitions.html)
 -   [hawq\_rm\_stmt\_nvseg](../reference/guc/parameter_definitions.html)
+-   [hawq\_rm\_stmt\_vseg\_memory](../reference/guc/parameter_definitions.html)
 
 However, the changed resource quota for the virtual segment cannot exceed the resource queue’s maximum capacity in HAWQ.
 
+***Note:*** The value of `hawq_rm_stmt_vseg_memory` depends on `hawq_rm_stmt_nvseg`, which defines the number of virtual segments used for the query. You must set `hawq_rm_stmt_nvseg` to a value greater than 0 before setting the memory quota for each segment with  `hawq_rm_stmt_vseg_memory`. After running a query or completing the session, reset the value of `hawq_rm_stmt_nvseg` to 0 to disable the statement level resource quota.
+
 In the following example, when executing the next query statement, the HAWQ resource manager will attempt to allocate 10 virtual segments and each segment has a 256MB memory quota.
 
+
 ``` sql
+postgres=# SET hawq_rm_stmt_nvseg=10;
+SET
 postgres=# SET hawq_rm_stmt_vseg_memory='256mb';
 SET
-postgres=# SET hawq_rm_stmt_nvseg=10;
+postgres=# SELECT <x> FROM <from_item> WHERE <condition>;
+postgres=# SET hawq_rm_stmt_nvseg=0;
 SET
-postgres=# CREATE TABLE t(i integer);
-CREATE TABLE
-postgres=# INSERT INTO t VALUES(1);
-INSERT 0 1
+
 ```
 
 Note that given the dynamic nature of resource allocation in HAWQ, you cannot expect that each segment has reserved resources for every query. The HAWQ resource manager will only attempt to allocate those resources. In addition, the number of virtual segments allocated for the query statement cannot amount to a value larger than the value set in global configuration parameter `hawq_rm_nvseg_perquery_limit` and `hawq_rm_nvseg_perquery_perseg_limit`.