Skip to content

Commit 3a7415d

Browse files
victorleeTGvictorleeTG
authored
Merge pull request #846 from tigergraph/DOC-2023-compatibility-3.6
DOC-2023-compatibility-issues-3.6
2 parents dadb6aa + 0c09000 commit 3a7415d

8 files changed

Lines changed: 314 additions & 42 deletions

File tree

‎modules/reference/nav.adoc‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
* References
22
** xref:configuration-parameters.adoc[]
3-
** xref:return-codes.adoc[]
3+
**
44
** xref:list-of-privileges.adoc[]
55
** xref:ports.adoc[]
6-
** xref:glossary.adoc[]
6+
** xref:glossary.adoc[]
7+
** xref:return-codes.adoc[]

‎modules/release-notes/nav.adoc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,2 @@
11
* xref:index.adoc[]
2+
* xref:compatibility/index.adoc[]

‎modules/release-notes/pages/.change-log.adoc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -883,7 +883,7 @@ Release Date: 2020-01-27
883883

884884
[WARNING]
885885
====
886-
*TigerGraph 2.5.2 is not compatible with versions prior to 2.5.1. Customers who are using Pre-2.5.1 version and intending to migrate to 2.5.2 are advised to take backup of their existing version before upgrading to 2.5.2. This will enable them to downgrade back to the original Pre-2.5.1 version if nee*
886+
*TigerGraph 2.5.2 is not compatible with versions prior to 2.5.1. Customers who are using Pre-2.5.1 version and intending to migrate to 2.5.2 are advised to take backup of their existing version before upgrading to 2.5.2. This will enable them to downgrade back to the original Pre-2.5.1 version if needed*
887887
====
888888

889889
=== *New Features*

modules/release-notes/pages/v3.0-removal-of-previously-deprecated-features.adoc renamed to modules/release-notes/pages/compatibility/.v3.0-removal-of-deprecated-features.adoc

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ END
100100

101101
==== Vertex set variable declaration
102102

103-
See xref:3.6@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
103+
See xref:{page-component-version}@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
104104

105105
If a vertex type is specified, the vertex type must be within parentheses.
106106

@@ -134,7 +134,7 @@ a|Job types need to be specified:
134134
* `RUN GLOBAL SCHEMA_CHANGE JOB`
135135

136136
|`CREATE / SHOW/ REFRESH TOKEN`
137-
|To create a token, use the xref:3.6@tigergraph-server:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
137+
|To create a token, use the xref:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
138138

139139
|`offline2online`
140140
|The offline loading job mode was discontinued in v2.0.
@@ -145,7 +145,7 @@ Do not write loading jobs using this syntax.
145145

146146
==== Output
147147

148-
See xref:3.6@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
148+
See xref:{page-component-version}@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
149149

150150
|===
151151
| Deprecated Syntax | Alternate Syntax

‎modules/release-notes/pages/compatibility/changes-among-tg3.adoc‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
= Compatibility among TigerGraph 3 versions
2+
:description: lists the compatibility issues between different versions of TigerGraph 3, for users who plan to migrate
3+
4+
This page lists the discontinued features or other incompatible changes from one TigerGraph 3.x version to another TigerGraph 3.x version.
5+
6+
[NOTE]
7+
====
8+
The list does not include bug fixes where a feature was not working correctly before and now is working according to the specification.
9+
Those issues are listed on the Release Notes page.
10+
====
11+
12+
== TigerGraph 3.6 Compatibility Changes
13+
14+
[options="header,autowidth"]
15+
|===
16+
| Version | Description | Recommendation
17+
18+
| 3.6.3
19+
| A vertex having an empty string as its primary id is considered bad data and will not be loaded.
20+
| Check input files and loading jobs to insure you are not attempting to load vertices with no ID.
21+
22+
| 3.6
23+
| A single `POST-ACCUM` clause can no longer reference more than one vertex alias in Syntax V1.
24+
| Rewrite query, possibly using multiple `POST-ACCUM`s
25+
26+
| 3.6
27+
| `GET /requesttoken endpoint` is dropped.
28+
| Use `POST /requestoken` instead, with credentials in the request body.
29+
30+
| 3.6
31+
| Deploying TigerGraph in Kubernetes now requires more service account permissions than previous versions.
32+
| See Prerequisites section in xref:kubernetes:quickstart-with-gke.adoc[], xref:kubernetes:quickstart-with-aks.adoc[], and xref:kubernetes:quickstart-with-eks.adoc[].
33+
|===
34+
35+
== TigerGraph 3.4 Compatibility Changes
36+
37+
[options="header,autowidth"]
38+
|===
39+
| Version | Description of Change | Recommendation
40+
41+
| 3.4
42+
| The built-in role `queryreader` can no longer run queries that include updates to the database.
43+
| To emulate the old `queryreader` role, create a role with all `queryreader` privileges, and also grant the `WRITE_DATA` privilege to the new role.
44+
45+
| 3.4
46+
| The built-in role `admin` can no longer create users.
47+
| To emulate the old `admin` role, create a global role with all `admin` privileges, and also grant the `WRITE_USER` privilege to the new role.
48+
49+
|===
50+
51+
52+
== TigerGraph 3.2 Compatibility Changes
53+
54+
[options="header,autowidth"]
55+
|===
56+
| Version | Description of Change | Recommendation
57+
58+
| 3.2
59+
| Subqueries: A distributed mode main query cannot call a distributed mode subquery.
60+
| Refactor such queries.
61+
62+
| 3.2
63+
| Log files: Default logging level for GSQL logs has changed from `DEBUG` to `INFO`.
64+
| Set the xref:reference:configuration-parameters.adoc#_GSQL[logging level to GSQL] to `DEBUG` when needed.
65+
66+
|===
67+
68+
69+
== TigerGraph 3.1 Compatibility Changes
70+
71+
[options="header,autowidth"]
72+
|===
73+
| Version | Description of Change | Recommendation
74+
75+
| 3.1.1
76+
a| Loading `TAGS`: syntax changed from BY (OR\|OVERWRITE) to `BY OR\|OVERWRITE`
77+
78+
(parentheses no longer used)
79+
| Update loading jobs which use `TAGS`
80+
81+
| 3.1.1
82+
| REST endpoint renamed from `dbsanitycheck` to `deleted_vertex_check`
83+
| Inform admin users
84+
85+
| 3.1
86+
| `STRING COMPRESS` data type is deprecated. New data objects may not have this data type. Existing data objects continue to work.
87+
| Use `STRING` data type instead for new schemas.
88+
89+
| 3.1
90+
| GSQL: A schema change can no longer drop a vertex type if it is used in an edge type.
91+
| Consider whether you intend to also remove the vertex type from any edges.
92+
93+
|===
94+

‎modules/release-notes/pages/compatibility/changes-from-tg2-to-tg3.adoc‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
= Compatibility between TigerGraph 2 and TigerGraph 3.0
2+
:description: lists the compatibility issues between TigerGraph 2 and TigerGraph 3, for users who plan to migrate
3+
4+
Major revisions (e.g., from TigerGraph 2 to TigerGraph 3) are the opportunity to deliver significant improvements. While we make every effort to maintain backward compatibility, in selected cases APIs have changed or deprecated features have been dropped, in order to advance the overall product.
5+
6+
*Data migration*: A tool is available to migrate the data in TigerGraph 2.6 to TigerGraph 3.0. Please contact TigerGraph Support for assistance.
7+
8+
*Query and API compatibility*:
9+
10+
* Some gadmin syntax has changed. Notably. `gadmin set config` is now `gadmin config set`.
11+
Please see xref:system-management:management-with-gadmin.adoc[Managing with gadmin].
12+
* Some features which were previously deprecated have been dropped. Please see xref:compatibility/.v3.0-removal-of-deprecated-features.adoc[V3.0 Removal of Previously Deprecated Features] for a detailed list.
13+
14+
== V3.0 Removal of Previously Deprecated Features
15+
16+
TigerGraph 2.x contained some features which were labeled as deprecated.
17+
These features are no longer necessary because they have been superseded already by improved approaches for using the TigerGraph platform.
18+
19+
The new approaches were developed because they use more consistent grammar, are more extensible, or offer higher performance.
20+
Therefore, TigerGraph 3.0 and above has streamlined the product by removing support for some of these deprecated features, listed below:
21+
22+
==== Data Types
23+
24+
|===
25+
| Deprecated type | Alternate approach
26+
27+
| `REAL`
28+
| Use `FLOAT` or `DOUBLE`
29+
30+
| `INT_SET`
31+
| Use `SET<INT>`
32+
33+
| `INT_LIST`
34+
| Use `LIST<INT>`
35+
36+
| `STRING_SET_COMPRESS`
37+
| Use `SET<STRING COMPRESS>`
38+
39+
| `STRING_LIST_CONPRESS`
40+
| Use `LIST<STRING COMPRESS>`
41+
42+
| `UINT_SET`
43+
| Use `SET<INT>`
44+
45+
| `UINT32_UINT32_KV_LIST`
46+
| Use `MAP<UINT, UINT>`
47+
48+
| `INT32_INT32_KV_LIST`
49+
| Use `MAP<INT, INT>`
50+
51+
| `UINT32_UDT_KV_LIST`
52+
| Use `MAP<UINT, UDT_type>`, where `UDT_type` is a user-defined tuple type
53+
54+
| `INT32_UDT_KV_LIST`
55+
| Use `MAP<INT, UDT_type>`, where `UDT_type` is a user-defined tuple type
56+
|===
57+
58+
==== Syntax for Control Flow Statements
59+
60+
61+
62+
|===
63+
|Deprecated statement |Alternate statement
64+
65+
|`FOREACH ... DO ... DONE`
66+
|`FOREACH... DO... END`
67+
68+
a|
69+
----
70+
FOREACH (condition) {
71+
body
72+
}
73+
----
74+
a|
75+
----
76+
FOREACH condition DO
77+
body
78+
END
79+
----
80+
81+
a|
82+
----
83+
IF (condition) {
84+
body1
85+
}
86+
else {
87+
body2
88+
}
89+
----
90+
a|
91+
----
92+
IF condition THEN
93+
body1
94+
ELSE
95+
body2
96+
END
97+
----
98+
a|
99+
----
100+
WHILE (condition) {
101+
body
102+
}
103+
----
104+
a|
105+
----
106+
WHILE condition DO
107+
body
108+
END
109+
----
110+
|===
111+
112+
113+
114+
==== Vertex set variable declaration
115+
116+
See xref:{page-component-version}@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
117+
118+
If a vertex type is specified, the vertex type must be within parentheses.
119+
120+
|===
121+
| Deprecated Statement | Alternate Statement
122+
123+
| `MySet Person = ...`
124+
| `MySet (Person) = ...`
125+
|===
126+
127+
128+
==== Query, Job, and Token Management
129+
130+
131+
132+
|===
133+
|Deprecated operation |Header 2
134+
135+
|`CREATE JOB`
136+
a|Job types need to be specified:
137+
138+
* `CREATE LOADING JOB`
139+
* `CREATE SCHEMA_CHANGE JOB`
140+
* `CREATE GLOBAL SCHEMA_CHANGE JOB`
141+
142+
|`RUN JOB`
143+
a|Job types need to be specified:
144+
145+
* `RUN LOADING JOB`
146+
* `RUN SCHEMA_CHANGE JOB`
147+
* `RUN GLOBAL SCHEMA_CHANGE JOB`
148+
149+
|`CREATE / SHOW/ REFRESH TOKEN`
150+
|To create a token, use the xref:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
151+
152+
|`offline2online`
153+
|The offline loading job mode was discontinued in v2.0.
154+
Do not write loading jobs using this syntax.
155+
|===
156+
157+
158+
159+
==== Output
160+
161+
See xref:{page-component-version}@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
162+
163+
|===
164+
| Deprecated Syntax | Alternate Syntax
165+
166+
| JSON API v1
167+
| v2 has been the default JSON format since TigerGraph 1.1. No alternate JSON version will be available.
168+
169+
| `PRINT ... TO_CSV [filepath]`
170+
| Define a file object, then `PRINT ... TO_CSV [file_object]`
171+
|===
172+
173+
174+
==== Built-in Queries
175+
176+
[Run Built-in Queries in 'GSQL 101']
177+
178+
179+
|===
180+
|Deprecated statement |Alternate statement
181+
182+
|`SELECT count() FROM ...`
183+
a|
184+
* `SELECT approx_count(*) FROM ...`
185+
** May not include all the latest data updates
186+
* `SELECT count(*) FROM ...`
187+
** exact, but slower than `approx_count(*)`
188+
|===

‎modules/release-notes/pages/compatibility/index.adoc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
= Compatibility and Migration Issues
2+
:description:Description of compatibility and migration issues for users moving from previous versions of TigerGraph
3+
4+
This section provides a historical record of feature changes between versions of TigerGraph which are not fully backwardly compatibility with earlier versions.
5+
This includes:
6+
7+
* Discontinued features or options
8+
* Behavioral changes which are not backwardly compatible
9+
10+
In addition to checking this list, check the xref:{page-component-version}@release-notes/index.adoc[Release Notes] for all the versions between your current version and your target version, for *deprecated features, known issues, new reserved words, or other behavioral changes*.
11+
12+
You may need to make migration changes to your TigerGraph application either before or after the upgrade.
13+
For example, change the name of schema elements and refactor queries if a new reserved word was introduced.
14+
15+
If you have any questions or uncertainty, please contact TigerGraph Support.
16+
17+
See all the sections that pertain to your proposed migration.
18+
For example, if you are considering migrating for 2.6 to 3.6, please see both pages.
19+
20+
* xref:compatibility/changes-from-tg2-to-tg3.adoc[]
21+
* xref:compatibility/changes-among-tg3.adoc[]

0 commit comments

Comments
 (0)