Skip to content

Commit f8d35c5

Browse files
mason-sharpmason-sharp
committed
Update documentation for INCREMENT
1 parent ec7ac27 commit f8d35c5

File tree

4 files changed

+117
-104
lines changed

4 files changed

+117
-104
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
- [Snowflake Overview](docs/index.md)
55
- [Building the Snowflake Extension](README.md#installation)
66
- [Basic Configuration and Usage](README.md#configuring-snowflake)
7-
- [Creating a Snowflake Sequence](docs/managing/creating.md)
7+
- [Creating a Snowflake Sequence](docs/creating.md)
88
- [Converting an Existing Postgres Sequence](docs/converting.md)
99
- [Using Snowflake Functions](docs/snowflake_functions.md)
1010
- [Reviewing Snowflake Meta-Data](docs/review_seq.md)

‎docs/converting.md‎

Lines changed: 107 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,101 +1,107 @@
1-
# Converting a PostgreSQL Sequence to a Snowflake Sequence
2-
3-
You can use the `snowflake.convert_sequence_to_snowflake()` function to convert individual sequences to snowflake sequences. Note that this converts the sequence definition; existing values in a sequence column will not change. The command syntax in SQL is:
4-
5-
`SELECT snowflake.convert_sequence_name('sequence_name');`
6-
7-
**Where**
8-
9-
`sequence_name` is the name of a sequence.
10-
11-
There are a number of ways to return a list of sequences. One way is to use the Postgres [`psql client`](https://www.postgresql.org/docs/current/app-psql.html) to execute the following command:
12-
13-
```
14-
\ds
15-
```
16-
17-
Another way is to query metadata catalog information directly in `psql` or another SQL editor.
18-
19-
```
20-
SELECT * FROM information_schema.sequences;
21-
```
22-
23-
The second command will provide data type information, which is useful for learning which sequences will be converted to the BIGINT data type (64 bits).
24-
25-
26-
## Example: Converting an Existing Sequence
27-
28-
The example that follows demonstrates using the psql command line to convert a sequence; in this example, we are using a table named `orders` that has three columns; the last column is a sequence named `id`:
29-
30-
```
31-
acctg=# CREATE TABLE orders (customer VARCHAR, invoice VARCHAR, id bigserial PRIMARY KEY);
32-
CREATE TABLE
33-
```
34-
35-
After creating the table, we insert data into the `orders` table. We only need to provide content for the first two columns, since the sequence definition keeps track of the value of the third column and adds it as needed:
36-
37-
```
38-
acctg=# INSERT INTO orders VALUES ('Chesterfield Schools', 'art_9338');
39-
INSERT 0 1
40-
acctg=# INSERT INTO orders VALUES ('Chesterfield Schools', 'math_9663');
41-
INSERT 0 1
42-
acctg=# INSERT INTO orders VALUES ('Albemarle Schools', 'sci_2009');
43-
INSERT 0 1
44-
acctg=# INSERT INTO orders VALUES ('King William Schools', 'sci_7399');
45-
INSERT 0 1
46-
acctg=# INSERT INTO orders VALUES ('King William Schools', 'art_9484');
47-
INSERT 0 1
48-
acctg=# INSERT INTO orders VALUES ('Hanover Schools', 'music_1849');
49-
INSERT 0 1
50-
acctg=# INSERT INTO orders VALUES ('Washington Schools', 'hist_2983');
51-
INSERT 0 1
52-
```
53-
When we select the rows from our table, we can see the sequence numbers in the `id` column:
54-
55-
```
56-
acctg=# SELECT * FROM orders;
57-
customer | invoice | id
58-
----------------------+------------+----
59-
Chesterfield Schools | art_9338 | 1
60-
Chesterfield Schools | math_9663 | 2
61-
Albemarle Schools | sci_2009 | 3
62-
King William Schools | sci_7399 | 4
63-
King William Schools | art_9484 | 5
64-
Hanover Schools | music_1849 | 6
65-
Washington Schools | hist_2983 | 7
66-
(7 rows)
67-
```
68-
To convert the sequence definition for the `orders` table to use Snowflake sequences, invoke the command in `psql` or another SQL editor:
69-
70-
```
71-
SELECT snowflake.convert_sequence_to_snowflake('orders_id_seq'::regclass);
72-
```
73-
74-
The conversion process modifies the sequence definition to use Snowflake sequences, but does not update existing rows. If we reconnect with psql and add new rows to the table, the new row's `id` will be a Snowflake sequence:
75-
76-
```
77-
acctg=# INSERT INTO orders VALUES ('Prince William Schools', 'math_8330');
78-
INSERT 0 1
79-
acctg=# INSERT INTO orders VALUES ('Fluvanna Schools', 'art_9447');
80-
INSERT 0 1
81-
```
82-
83-
In the query results that follows, you can see the unformatted sequence value in the `id` column, and the same information in the `format` column, formatted with the `snowflake.format(id)` function. The rows added before the conversion to Snowflake sequences show a fixed timestamp of `2022-12-31 19:00:00-05`, while the Snowflake sequences have a unique `id` and timestamp.
84-
85-
Original entries in the table display a Postgres sequence, while entries made after the conversion display Snowflake sequences:
86-
87-
```
88-
acctg=# SELECT id, snowflake.format(id), customer, invoice FROM orders;
89-
id | format | customer | invoice
90-
--------------------+-----------------------------------------------------------+------------------------+------------
91-
1 | {"id": 1, "ts": "2022-12-31 19:00:00-05", "count": 0} | Chesterfield Schools | art_9338
92-
2 | {"id": 2, "ts": "2022-12-31 19:00:00-05", "count": 0} | Chesterfield Schools | math_9663
93-
3 | {"id": 3, "ts": "2022-12-31 19:00:00-05", "count": 0} | Albemarle Schools | sci_2009
94-
4 | {"id": 4, "ts": "2022-12-31 19:00:00-05", "count": 0} | King William Schools | sci_7399
95-
5 | {"id": 5, "ts": "2022-12-31 19:00:00-05", "count": 0} | King William Schools | art_9484
96-
6 | {"id": 6, "ts": "2022-12-31 19:00:00-05", "count": 0} | Hanover Schools | music_1849
97-
7 | {"id": 7, "ts": "2022-12-31 19:00:00-05", "count": 0} | Washington Schools | hist_2983
98-
135824181823537153 | {"id": 1, "ts": "2024-01-10 14:16:48.438-05", "count": 0} | Prince William Schools | math_8330
99-
135824609030176769 | {"id": 1, "ts": "2024-01-10 14:18:30.292-05", "count": 0} | Fluvanna Schools | art_9447
100-
(9 rows)
101-
```
1+
# Converting a PostgreSQL Sequence to a Snowflake Sequence
2+
3+
You cannot directly create a snowflake sequence, you must first create a sequence in Postgres and then convert it. Sequences are created explicitly with the `CREATE SEQUENCE` command but are also implicitly created by `GENERATED { ALWAYS | BY DEFAULT } AS IDENTITY` table columns or SERIAL and BIGSERIAL columns. GENERATED AS IDENTITY is the recommended ANSI SQL method.
4+
5+
You can use the `snowflake.convert_sequence_to_snowflake()` function to convert individual sequences to snowflake sequences. Note that this converts the sequence definition; existing values in a sequence column will not change. The command syntax in SQL is:
6+
7+
`SELECT snowflake.convert_sequence_name('sequence_name');`
8+
9+
**Where**
10+
11+
`sequence_name` is the name of a sequence.
12+
13+
There are a number of ways to return a list of sequences. One way is to use the Postgres [`psql client`](https://www.postgresql.org/docs/current/app-psql.html) to execute the following command:
14+
15+
```
16+
\ds
17+
```
18+
19+
Another way is to query metadata catalog information directly in `psql` or another SQL editor.
20+
21+
```
22+
SELECT * FROM information_schema.sequences;
23+
```
24+
25+
The second command will provide data type information, which is useful for learning which sequences will be converted to the BIGINT data type (64 bits).
26+
27+
28+
## Example: Converting an Existing Sequence
29+
30+
The example that follows demonstrates using the psql command line to convert a sequence; in this example, we are using a table named `orders` that has three columns; the last column is a sequence named `id`:
31+
32+
```
33+
acctg=# CREATE TABLE orders (customer VARCHAR, invoice VARCHAR, id bigserial PRIMARY KEY);
34+
CREATE TABLE
35+
```
36+
37+
After creating the table, we insert data into the `orders` table. We only need to provide content for the first two columns, since the sequence definition keeps track of the value of the third column and adds it as needed:
38+
39+
```
40+
acctg=# INSERT INTO orders VALUES ('Chesterfield Schools', 'art_9338');
41+
INSERT 0 1
42+
acctg=# INSERT INTO orders VALUES ('Chesterfield Schools', 'math_9663');
43+
INSERT 0 1
44+
acctg=# INSERT INTO orders VALUES ('Albemarle Schools', 'sci_2009');
45+
INSERT 0 1
46+
acctg=# INSERT INTO orders VALUES ('King William Schools', 'sci_7399');
47+
INSERT 0 1
48+
acctg=# INSERT INTO orders VALUES ('King William Schools', 'art_9484');
49+
INSERT 0 1
50+
acctg=# INSERT INTO orders VALUES ('Hanover Schools', 'music_1849');
51+
INSERT 0 1
52+
acctg=# INSERT INTO orders VALUES ('Washington Schools', 'hist_2983');
53+
INSERT 0 1
54+
```
55+
When we select the rows from our table, we can see the sequence numbers in the `id` column:
56+
57+
```
58+
acctg=# SELECT * FROM orders;
59+
customer | invoice | id
60+
----------------------+------------+----
61+
Chesterfield Schools | art_9338 | 1
62+
Chesterfield Schools | math_9663 | 2
63+
Albemarle Schools | sci_2009 | 3
64+
King William Schools | sci_7399 | 4
65+
King William Schools | art_9484 | 5
66+
Hanover Schools | music_1849 | 6
67+
Washington Schools | hist_2983 | 7
68+
(7 rows)
69+
```
70+
To convert the sequence definition for the `orders` table to use Snowflake sequences, invoke the command in `psql` or another SQL editor:
71+
72+
```
73+
SELECT snowflake.convert_sequence_to_snowflake('orders_id_seq'::regclass);
74+
```
75+
76+
The conversion process modifies the sequence definition to use Snowflake sequences, but does not update existing rows. If we reconnect with psql and add new rows to the table, the new row's `id` will be a Snowflake sequence:
77+
78+
```
79+
acctg=# INSERT INTO orders VALUES ('Prince William Schools', 'math_8330');
80+
INSERT 0 1
81+
acctg=# INSERT INTO orders VALUES ('Fluvanna Schools', 'art_9447');
82+
INSERT 0 1
83+
```
84+
85+
In the query results that follows, you can see the unformatted sequence value in the `id` column, and the same information in the `format` column, formatted with the `snowflake.format(id)` function. The rows added before the conversion to Snowflake sequences show a fixed timestamp of `2022-12-31 19:00:00-05`, while the Snowflake sequences have a unique `id` and timestamp.
86+
87+
Original entries in the table display a Postgres sequence, while entries made after the conversion display Snowflake sequences:
88+
89+
```
90+
acctg=# SELECT id, snowflake.format(id), customer, invoice FROM orders;
91+
id | format | customer | invoice
92+
--------------------+-----------------------------------------------------------+------------------------+------------
93+
1 | {"id": 1, "ts": "2022-12-31 19:00:00-05", "count": 0} | Chesterfield Schools | art_9338
94+
2 | {"id": 2, "ts": "2022-12-31 19:00:00-05", "count": 0} | Chesterfield Schools | math_9663
95+
3 | {"id": 3, "ts": "2022-12-31 19:00:00-05", "count": 0} | Albemarle Schools | sci_2009
96+
4 | {"id": 4, "ts": "2022-12-31 19:00:00-05", "count": 0} | King William Schools | sci_7399
97+
5 | {"id": 5, "ts": "2022-12-31 19:00:00-05", "count": 0} | King William Schools | art_9484
98+
6 | {"id": 6, "ts": "2022-12-31 19:00:00-05", "count": 0} | Hanover Schools | music_1849
99+
7 | {"id": 7, "ts": "2022-12-31 19:00:00-05", "count": 0} | Washington Schools | hist_2983
100+
135824181823537153 | {"id": 1, "ts": "2024-01-10 14:16:48.438-05", "count": 0} | Prince William Schools | math_8330
101+
135824609030176769 | {"id": 1, "ts": "2024-01-10 14:18:30.292-05", "count": 0} | Fluvanna Schools | art_9447
102+
(9 rows)
103+
```
104+
105+
**INCREMENT and Caching**
106+
107+
Within the same millisecond, snowflake will allow a maximum of 4096 values. Some frameworks like the ORM framework Hibernate may be configured to try to fetch a sequence value, cache and assign a range by using an `INCREMENT` value for the sequence. Snowflake sequences honor the increment value, but you should not use a value greater than 4096. If you would like to change the increment value, use `ALTER SEQUENCE <seq_name> INCREMENT <increment_value> NO MAXVALUE`.

‎docs/creating.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,5 @@ or use the `pg_ctl reload` command to reload the server:
4949
[pgedge]$ /home/pgedge/pg16/bin/pg_ctl reload -D "/home/pgedge/data/pg16"
5050
server signaled
5151
```
52+
53+
Once snowflake is configured, you can begin to use snowflake sequences by first [converting](converting.md) them from Postgres sequences.

‎hibernate.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
Hibernate uses identifiers as the primary key of an entity. There are ways to
2-
define identifiers in Hibernate, which are unique keys for an entity, ensuring
2+
define identifiers in Hibernate, which are unique keys for an entity, ensuring
33
they are not null.
44

55
pgEdge Snowflake Sequences for PostgreSQL can be used with Hibernate, in this
@@ -84,5 +84,10 @@ FROM
8484
170505378935607296 "London"
8585
```
8686

87-
It is a basic example to demostrate use of pgEdge Snow Flake sequence with the
87+
It is a basic example to demostrate use of pgEdge Snowflake sequence with the
8888
Java Hibernate code.
89+
90+
91+
**INCREMENT and Caching**
92+
93+
Within the same millisecond, snowflake will allow a maximum of 4096 values. Hibernate may be configured to try to fetch a sequence value, cache and assign a range by using an `INCREMENT` value for the sequence. Snowflake sequences honor the increment value, but you should not use a value greater than 4096. If you would like to change the increment value, use `ALTER SEQUENCE <seq_name> INCREMENT <increment_value> NO MAXVALUE`.

0 commit comments

Comments
 (0)