DOC-2023-compatibility-issues-3.6

modules/reference/nav.adoc

@@ -1,6 +1,7 @@
 * References
 ** xref:configuration-parameters.adoc[]
-** xref:return-codes.adoc[]
+**
 ** xref:list-of-privileges.adoc[]
 ** xref:ports.adoc[]
-** xref:glossary.adoc[]
+** xref:glossary.adoc[]
+** xref:return-codes.adoc[]

modules/release-notes/nav.adoc

@@ -1 +1,2 @@
 * xref:index.adoc[]
+* xref:compatibility/index.adoc[]

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

@@ -883,7 +883,7 @@ Release Date: 2020-01-27
 
 [WARNING]
 ====
-*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*
+*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*
 ====
 
 === *New Features*

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

@@ -100,7 +100,7 @@ END
 
 ==== Vertex set variable declaration
 
-See xref:3.6@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
+See xref:{page-component-version}@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
 
 If a vertex type is specified, the vertex type must be within parentheses.
 
@@ -134,7 +134,7 @@ a|Job types need to be specified:
 * `RUN GLOBAL SCHEMA_CHANGE JOB`
 
 |`CREATE / SHOW/ REFRESH TOKEN`
-|To create a token, use the xref:3.6@tigergraph-server:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
+|To create a token, use the xref:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
 
 |`offline2online`
 |The offline loading job mode was discontinued in v2.0.
@@ -145,7 +145,7 @@ Do not write loading jobs using this syntax.
 
 ==== Output
 
-See xref:3.6@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
+See xref:{page-component-version}@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
 
 |===
 | Deprecated Syntax | Alternate Syntax

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

@@ -0,0 +1,94 @@
+= Compatibility among TigerGraph 3 versions
+:description: lists the compatibility issues between different versions of TigerGraph 3, for users who plan to migrate
+
+This page lists the discontinued features or other incompatible changes from one TigerGraph 3.x version to another TigerGraph 3.x version.
+
+[NOTE]
+====
+The list does not include bug fixes where a feature was not working correctly before and now is working according to the specification.
+Those issues are listed on the Release Notes page.
+====
+
+== TigerGraph 3.6 Compatibility Changes
+
+[options="header,autowidth"]
+|===
+| Version | Description | Recommendation
+
+| 3.6.3
+| A vertex having an empty string as its primary id is considered bad data and will not be loaded.
+| Check input files and loading jobs to insure you are not attempting to load vertices with no ID.
+
+| 3.6
+| A single `POST-ACCUM` clause can no longer reference more than one vertex alias in Syntax V1.
+| Rewrite query, possibly using multiple `POST-ACCUM`s
+
+| 3.6
+| `GET /requesttoken endpoint` is dropped.
+| Use `POST /requestoken` instead, with credentials in the request body.
+
+| 3.6
+| Deploying TigerGraph in Kubernetes now requires more service account permissions than previous versions.
+| See Prerequisites section in xref:kubernetes:quickstart-with-gke.adoc[], xref:kubernetes:quickstart-with-aks.adoc[], and xref:kubernetes:quickstart-with-eks.adoc[].
+|===
+
+== TigerGraph 3.4 Compatibility Changes
+
+[options="header,autowidth"]
+|===
+| Version | Description of Change | Recommendation
+
+| 3.4
+| The built-in role `queryreader` can no longer run queries that include updates to the database.
+| To emulate the old `queryreader` role, create a role with all `queryreader` privileges, and also grant the `WRITE_DATA` privilege to the new role.
+
+| 3.4
+| The built-in role `admin` can no longer create users.
+| 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.
+
+|===
+
+
+== TigerGraph 3.2 Compatibility Changes
+
+[options="header,autowidth"]
+|===
+| Version | Description of Change | Recommendation
+
+| 3.2
+| Subqueries: A distributed mode main query cannot call a distributed mode subquery.
+| Refactor such queries.
+
+| 3.2
+| Log files: Default logging level for GSQL logs has changed from `DEBUG` to `INFO`.
+| Set the xref:reference:configuration-parameters.adoc#_GSQL[logging level to GSQL] to `DEBUG` when needed.
+
+|===
+
+
+== TigerGraph 3.1 Compatibility Changes
+
+[options="header,autowidth"]
+|===
+| Version | Description of Change | Recommendation
+
+| 3.1.1
+a| Loading `TAGS`: syntax changed from BY (OR\|OVERWRITE) to `BY OR\|OVERWRITE`
+
+(parentheses no longer used)
+| Update loading jobs which use `TAGS`
+
+| 3.1.1
+| REST endpoint renamed from `dbsanitycheck` to `deleted_vertex_check`
+| Inform admin users
+
+| 3.1
+| `STRING COMPRESS` data type is deprecated. New data objects may not have this data type. Existing data objects continue to work.
+| Use `STRING` data type instead for new schemas.
+
+| 3.1
+| GSQL: A schema change can no longer drop a vertex type if it is used in an edge type.
+| Consider whether you intend to also remove the vertex type from any edges.
+
+|===
+

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

@@ -0,0 +1,188 @@
+= Compatibility between TigerGraph 2 and TigerGraph 3.0
+:description: lists the compatibility issues between TigerGraph 2 and TigerGraph 3, for users who plan to migrate
+
+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.
+
+*Data migration*: A tool is available to migrate the data in TigerGraph 2.6 to TigerGraph 3.0. Please contact TigerGraph Support for assistance.
+
+*Query and API compatibility*:
+
+* Some gadmin syntax has changed. Notably. `gadmin set config` is now `gadmin config set`.
+Please see xref:system-management:management-with-gadmin.adoc[Managing with gadmin].
+* 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.
+
+== V3.0 Removal of Previously Deprecated Features
+
+TigerGraph 2.x contained some features which were labeled as deprecated.
+These features are no longer necessary because they have been superseded already by improved approaches for using the TigerGraph platform.
+
+The new approaches were developed because they use more consistent grammar, are more extensible,  or offer higher performance.
+Therefore, TigerGraph 3.0 and above has streamlined the product by removing support for some of these deprecated features, listed below:
+
+==== Data Types
+
+|===
+| Deprecated type | Alternate approach
+
+| `REAL`
+| Use `FLOAT` or `DOUBLE`
+
+| `INT_SET`
+| Use `SET<INT>`
+
+| `INT_LIST`
+| Use `LIST<INT>`
+
+| `STRING_SET_COMPRESS`
+| Use `SET<STRING COMPRESS>`
+
+| `STRING_LIST_CONPRESS`
+| Use `LIST<STRING COMPRESS>`
+
+| `UINT_SET`
+| Use `SET<INT>`
+
+| `UINT32_UINT32_KV_LIST`
+| Use `MAP<UINT, UINT>`
+
+| `INT32_INT32_KV_LIST`
+| Use `MAP<INT, INT>`
+
+| `UINT32_UDT_KV_LIST`
+| Use `MAP<UINT, UDT_type>`, where `UDT_type` is a user-defined tuple type
+
+| `INT32_UDT_KV_LIST`
+| Use `MAP<INT, UDT_type>`, where `UDT_type` is a user-defined tuple type
+|===
+
+==== Syntax for Control Flow Statements
+
+
+
+|===
+|Deprecated statement |Alternate statement
+
+|`FOREACH ... DO ... DONE`
+|`FOREACH... DO... END`
+
+a|
+----
+FOREACH (condition) {
+    body
+}
+----
+a|
+----
+FOREACH condition DO
+    body
+END
+----
+
+a|
+----
+IF (condition) {
+    body1
+}
+else {
+    body2
+}
+----
+a|
+----
+IF condition THEN
+    body1
+ELSE
+    body2
+END
+----
+a|
+----
+WHILE (condition) {
+    body
+}
+----
+a|
+----
+WHILE condition DO
+    body
+END
+----
+|===
+
+
+
+==== Vertex set variable declaration
+
+See xref:{page-component-version}@gsql-ref:querying:declaration-and-assignment-statements.adoc#_vertex_set_variables[Vertex Set Variable Declaration and Assignment]
+
+If a vertex type is specified, the vertex type must be within parentheses.
+
+|===
+| Deprecated Statement | Alternate Statement
+
+| `MySet Person = ...`
+| `MySet (Person) = ...`
+|===
+
+
+==== Query, Job, and Token Management
+
+
+
+|===
+|Deprecated operation |Header 2
+
+|`CREATE JOB`
+a|Job types need to be specified:
+
+* `CREATE LOADING JOB`
+* `CREATE SCHEMA_CHANGE JOB`
+* `CREATE GLOBAL SCHEMA_CHANGE JOB`
+
+|`RUN JOB`
+a|Job types need to be specified:
+
+* `RUN LOADING JOB`
+* `RUN SCHEMA_CHANGE JOB`
+* `RUN GLOBAL SCHEMA_CHANGE JOB`
+
+|`CREATE / SHOW/ REFRESH TOKEN`
+|To create a token, use the xref:API:built-in-endpoints.adoc#_request_a_token[REST endpoint GET /requesttoken].
+
+|`offline2online`
+|The offline loading job mode was discontinued in v2.0.
+Do not write loading jobs using this syntax.
+|===
+
+
+
+==== Output
+
+See xref:{page-component-version}@gsql-ref:querying:output-statements-and-file-objects.adoc#_print_statement_api_v2[PRINT Statement]
+
+|===
+| Deprecated Syntax | Alternate Syntax
+
+| JSON API v1
+| v2 has been the default JSON format since TigerGraph 1.1. No alternate JSON version will be available.
+
+| `PRINT ... TO_CSV [filepath]`
+| Define a file object, then `PRINT ... TO_CSV [file_object]`
+|===
+
+
+==== Built-in Queries
+
+[Run Built-in Queries in 'GSQL 101']
+
+
+|===
+|Deprecated statement |Alternate statement
+
+|`SELECT count() FROM ...`
+a|
+* `SELECT approx_count(*) FROM ...`
+** May not include all the latest data updates
+* `SELECT count(*) FROM ...`
+** exact, but slower than `approx_count(*)`
+|===

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

@@ -0,0 +1,21 @@
+= Compatibility and Migration Issues
+:description:Description of compatibility and migration issues for users moving from previous versions of TigerGraph
+
+This section provides a historical record of feature changes between versions of TigerGraph which are not fully backwardly compatibility with earlier versions.
+This includes:
+
+* Discontinued features or options
+* Behavioral changes which are not backwardly compatible
+
+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*.
+
+You may need to make migration changes to your TigerGraph application either before or after the upgrade.
+For example, change the name of schema elements and refactor queries if a new reserved word was introduced.
+
+If you have any questions or uncertainty, please contact TigerGraph Support.
+
+See all the sections that pertain to your proposed migration.
+For example, if you are considering migrating for 2.6 to 3.6, please see both pages.
+
+* xref:compatibility/changes-from-tg2-to-tg3.adoc[]
+* xref:compatibility/changes-among-tg3.adoc[]