Repository: incubator-hawq-docs Updated Branches: refs/heads/develop bd6ce7830 -> 4f333a3bf
HAWQ-1424 - new alter sequence ref page (closes #117) Project: http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/commit/4f333a3b Tree: http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/tree/4f333a3b Diff: http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/diff/4f333a3b Branch: refs/heads/develop Commit: 4f333a3bf260c99d0a07a369997d0a5e8b44e15e Parents: bd6ce78 Author: Lisa Owen <[email protected]> Authored: Fri Apr 7 09:02:34 2017 -0700 Committer: David Yozie <[email protected]> Committed: Fri Apr 7 09:02:34 2017 -0700 ---------------------------------------------------------------------- .../source/subnavs/apache-hawq-nav.erb | 1 + .../reference/SQLCommandReference.html.md.erb | 2 + .../reference/sql/ALTER-SEQUENCE.html.md.erb | 102 +++++++++++++++++++ .../reference/sql/CREATE-SEQUENCE.html.md.erb | 20 ++-- .../reference/sql/DROP-SEQUENCE.html.md.erb | 2 +- 5 files changed, 116 insertions(+), 11 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/blob/4f333a3b/book/master_middleman/source/subnavs/apache-hawq-nav.erb ---------------------------------------------------------------------- diff --git a/book/master_middleman/source/subnavs/apache-hawq-nav.erb b/book/master_middleman/source/subnavs/apache-hawq-nav.erb index 5c784e9..489f0c4 100644 --- a/book/master_middleman/source/subnavs/apache-hawq-nav.erb +++ b/book/master_middleman/source/subnavs/apache-hawq-nav.erb @@ -429,6 +429,7 @@ <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-OPERATOR-CLASS.html">ALTER OPERATOR CLASS</a></li> <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-RESOURCE-QUEUE.html">ALTER RESOURCE QUEUE</a></li> <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-ROLE.html">ALTER ROLE</a></li> + <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-SEQUENCE.html">ALTER SEQUENCE</a></li> <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-TABLE.html">ALTER TABLE</a></li> <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-TABLESPACE.html">ALTER TABLESPACE</a></li> <li><a href="/docs/userguide/2.2.0.0-incubating/reference/sql/ALTER-TYPE.html">ALTER TYPE</a></li> http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/blob/4f333a3b/markdown/reference/SQLCommandReference.html.md.erb ---------------------------------------------------------------------- diff --git a/markdown/reference/SQLCommandReference.html.md.erb b/markdown/reference/SQLCommandReference.html.md.erb index 44938ee..f7c9689 100644 --- a/markdown/reference/SQLCommandReference.html.md.erb +++ b/markdown/reference/SQLCommandReference.html.md.erb @@ -39,6 +39,8 @@ This section contains a description and the syntax of the SQL commands suppor - **[ALTER ROLE](../reference/sql/ALTER-ROLE.html)** +- **[ALTER SEQUENCE](../reference/sql/ALTER-SEQUENCE.html)** + - **[ALTER TABLE](../reference/sql/ALTER-TABLE.html)** - **[ALTER TABLESPACE](../reference/sql/ALTER-TABLESPACE.html)** http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/blob/4f333a3b/markdown/reference/sql/ALTER-SEQUENCE.html.md.erb ---------------------------------------------------------------------- diff --git a/markdown/reference/sql/ALTER-SEQUENCE.html.md.erb b/markdown/reference/sql/ALTER-SEQUENCE.html.md.erb new file mode 100644 index 0000000..e10d03c --- /dev/null +++ b/markdown/reference/sql/ALTER-SEQUENCE.html.md.erb @@ -0,0 +1,102 @@ +--- +title: ALTER SEQUENCE +--- + +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +Change the definition of a sequence generator. + +## <a id="topic1__section2"></a>Synopsis + +``` pre +ALTER SEQUENCE <name> +       [INCREMENT [BY] <value>] +       [MINVALUE <minvalue> | NO MINVALUE] +       [MAXVALUE <maxvalue> | NO MAXVALUE] +       [RESTART [ WITH ] <start>] +       [CACHE <cache>] +       [[NO] CYCLE] +       [OWNED BY { <table>.<column> | NONE }] +``` + +## <a id="topic1__section3"></a>Description + +`ALTER SEQUENCE` changes the parameters of an existing sequence generator. Any parameters not specifically set in the `ALTER SEQUENCE` command retain their prior setting. + +You must own the sequence to use `ALTER SEQUENCE`. + + +## <a id="topic1__section4"></a>Parameters + +<dt> \<name\> </dt> +<dd>The name (optionally schema-qualified) of the sequence to be altered.</dd> + +<dt> \<increment\> </dt> +<dd>Specifies which value is added to the current sequence value to create a new value. A positive value will make an ascending sequence, a negative one a descending sequence. The default value is 1.</dd> + +<dt> \<minvalue\> +NO MINVALUE </dt> +<dd>Determines the minimum value a sequence can generate. If this clause is not supplied or `NO MINVALUE` is specified, then defaults will be used. The defaults are 1 and -2<sup>63</sup>-1 for ascending and descending sequences, respectively.</dd> + +<dt> \<maxvalue\> +NO MAXVALUE </dt> +<dd>Determines the maximum value for the sequence. If this clause is not supplied or `NO MAXVALUE` is specified, then default values will be used. The defaults are 2<sup>63</sup>-1 and -1 for ascending and descending sequences, respectively.</dd> + +<dt> \<start\> </dt> +<dd>The new current value of the sequence.</dd> + +<dt> \<cache\> </dt> +<dd>Specifies how many sequence numbers are to be preallocated and stored in memory for faster access. The minimum (and default) value is 1 (no cache).</dd> + +<dt>CYCLE +NO CYCLE </dt> +<dd>Allows the sequence to wrap around when the \<maxvalue\> (for ascending) or \<minvalue\> (for descending) has been reached. If the limit is reached, the next number generated will be the \<minvalue\> (for ascending) or \<maxvalue\> (for descending). If `NO CYCLE` is specified, any calls to `nextval()` after the sequence has reached its maximum value will return an error. If not specified, `NO CYCLE` is the default.</dd> + +<dt>OWNED BY \<table\>.\<column\> +OWNED BY NONE </dt> +<dd>Causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well. If specified, this association replaces any previously specified assocation for the sequence. The specified table must have the same owner and be in the same schema as the sequence. `OWNED BY NONE` removes any existing association.</dd> + +## <a id="topic1__section5"></a>Notes + +`ALTER SEQUENCE` will not immediately affect `nextval()` results in backends, other than the current one, that have preallocated (cached) sequence values. They will use up all cached values prior to noticing the changed sequence generation parameters. The current backend will be affected immediately. + +Some variants of `ALTER TABLE` can be used with sequences as well; for example, to rename a sequence use `ALTER TABLE RENAME`. + +## <a id="topic1__section6"></a>Examples + +Restart the sequence named `myseq`: + +``` pre +ALTER SEQUENCE myseq RESTART WITH 111; +``` + +Change the increment value for the sequence named `myseq`: + +``` pre +ALTER SEQUENCE myseq INCREMENT BY 3; +``` + +## <a id="topic1__section7"></a>Compatibility + +`CREATE SEQUENCE` conforms to the SQL standard, with the exception that the `OWNED BY` clause is a HAWQ extension. + +## <a id="topic1__section8"></a>See Also + +[CREATE SEQUENCE](CREATE-SEQUENCE.html), [DROP SEQUENCE](DROP-SEQUENCE.html) http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/blob/4f333a3b/markdown/reference/sql/CREATE-SEQUENCE.html.md.erb ---------------------------------------------------------------------- diff --git a/markdown/reference/sql/CREATE-SEQUENCE.html.md.erb b/markdown/reference/sql/CREATE-SEQUENCE.html.md.erb index 01b81d3..70e5117 100644 --- a/markdown/reference/sql/CREATE-SEQUENCE.html.md.erb +++ b/markdown/reference/sql/CREATE-SEQUENCE.html.md.erb @@ -42,13 +42,13 @@ CREATE [TEMPORARY | TEMP] SEQUENCE <name> If a schema name is given, then the sequence is created in the specified schema. Otherwise it is created in the current schema. Temporary sequences exist in a special schema, so a schema name may not be given when creating a temporary sequence. The sequence name must be distinct from the name of any other sequence, table, or view in the same schema. -After a sequence is created, you use the `nextval` function to operate on the sequence. For example, to insert a row into a table that gets the next value of a sequence: +After a sequence is created, you use the `nextval()` function to operate on the sequence. For example, to insert a row into a table that gets the next value of a sequence: ``` pre INSERT INTO distributors VALUES (nextval('myserial'), 'acme'); ``` -You can also use the function `setval` to operate on a sequence, but only for queries that do not operate on distributed data. For example, the following query is allowed because it resets the sequence counter value for the sequence generator process on the master: +You can also use the function `setval()` to operate on a sequence, but only for queries that do not operate on distributed data. For example, the following query is allowed because it resets the sequence counter value for the sequence generator process on the master: ``` pre SELECT setval('myserial', 201); @@ -64,9 +64,9 @@ In a regular (non-distributed) database, functions that operate on the sequence Because of this distributed sequence design, there are some limitations on the functions that operate on a sequence in HAWQ: -- `lastval` and `currval` functions are not supported. -- `setval` can only be used to set the value of the sequence generator on the master, it cannot be used in subqueries to update records on distributed table data. -- `nextval` sometimes grabs a block of values from the master for a segment to use, depending on the query. So values may sometimes be skipped in the sequence if all of the block turns out not to be needed at the segment level. Note that a regular PostgreSQL database does this too, so this is not something unique to HAWQ. +- `lastval()` and `currval()` functions are not supported. +- `setval()` can only be used to set the value of the sequence generator on the master, it cannot be used in subqueries to update records on distributed table data. +- `nextval()` sometimes grabs a block of values from the master for a segment to use, depending on the query. So values may sometimes be skipped in the sequence if all of the block turns out not to be needed at the segment level. Note that a regular PostgreSQL database does this too, so this is not something unique to HAWQ. Although you cannot update a sequence directly, you can use a query like: @@ -89,11 +89,11 @@ to examine the parameters and current state of a sequence. In particular, the `l <dt> \<minvalue\> NO MINVALUE </dt> -<dd>Determines the minimum value a sequence can generate. If this clause is not supplied or `NO MINVALUE` is specified, then defaults will be used. The defaults are 1 and -263-1 for ascending and descending sequences, respectively.</dd> +<dd>Determines the minimum value a sequence can generate. If this clause is not supplied or `NO MINVALUE` is specified, then defaults will be used. The defaults are 1 and -2<sup>63</sup>-1 for ascending and descending sequences, respectively.</dd> <dt> \<maxvalue\> NO MAXVALUE </dt> -<dd>Determines the maximum value for the sequence. If this clause is not supplied or `NO MAXVALUE` is specified, then default values will be used. The defaults are 263-1 and -1 for ascending and descending sequences, respectively.</dd> +<dd>Determines the maximum value for the sequence. If this clause is not supplied or `NO MAXVALUE` is specified, then default values will be used. The defaults are 2<sup>63-1 and -1 for ascending and descending sequences, respectively.</dd> <dt> \<start\> </dt> <dd>Allows the sequence to begin anywhere. The default starting value is \<minvalue\> for ascending sequences and \<maxvalue\> for descending ones.</dd> @@ -113,7 +113,7 @@ OWNED BY NONE </dt> Sequences are based on bigint arithmetic, so the range cannot exceed the range of an eight-byte integer (-9223372036854775808 to 9223372036854775807). -Although multiple sessions are guaranteed to allocate distinct sequence values, the values may be generated out of sequence when all the sessions are considered. For example, session A might reserve values 1..10 and return `nextval=1`, then session B might reserve values 11..20 and return `nextval=11` before session A has generated nextval=2. Thus, you should only assume that the `nextval` values are all distinct, not that they are generated purely sequentially. Also,`last_value` will reflect the latest value reserved by any session, whether or not it has yet been returned by `nextval`. +Although multiple sessions are guaranteed to allocate distinct sequence values, the values may be generated out of sequence when all the sessions are considered. For example, session A might reserve values 1..10 and return `nextval=1`, then session B might reserve values 11..20 and return `nextval=11` before session A has generated `nextval=2`. Thus, you should only assume that the `nextval()` values are all distinct, not that they are generated purely sequentially. Also,`last_value` will reflect the latest value reserved by any session, whether or not it has yet been returned by `nextval()`. ## <a id="topic1__section6"></a>Examples @@ -135,7 +135,7 @@ Reset the sequence counter value on the master: SELECT setval('myseq', 201); ``` -Illegal use of `setval` in HAWQ (setting sequence values on distributed data): +Illegal use of `setval()` in HAWQ (setting sequence values on distributed data): ``` pre INSERT INTO product VALUES (setval('myseq', 201), 'gizmo'); @@ -151,4 +151,4 @@ INSERT INTO product VALUES (setval('myseq', 201), 'gizmo'); ## <a id="topic1__section8"></a>See Also -[DROP SEQUENCE](DROP-SEQUENCE.html) +[ALTER SEQUENCE](ALTER-SEQUENCE.html), [DROP SEQUENCE](DROP-SEQUENCE.html) http://git-wip-us.apache.org/repos/asf/incubator-hawq-docs/blob/4f333a3b/markdown/reference/sql/DROP-SEQUENCE.html.md.erb ---------------------------------------------------------------------- diff --git a/markdown/reference/sql/DROP-SEQUENCE.html.md.erb b/markdown/reference/sql/DROP-SEQUENCE.html.md.erb index 4d787ae..e0473bd 100644 --- a/markdown/reference/sql/DROP-SEQUENCE.html.md.erb +++ b/markdown/reference/sql/DROP-SEQUENCE.html.md.erb @@ -61,4 +61,4 @@ DROP SEQUENCE myserial; ## <a id="topic1__section7"></a>See Also -[CREATE SEQUENCE](CREATE-SEQUENCE.html) +[ALTER SEQUENCE](ALTER-SEQUENCE.html), [CREATE SEQUENCE](CREATE-SEQUENCE.html)
