From 0c09000c8861be265cbf054c3278aa66caf3b355 Mon Sep 17 00:00:00 2001 From: Victor Lee Date: Fri, 4 Jul 2025 22:45:40 -0400 Subject: [PATCH] DOC-2023-compatibility-issues-3.6 --- modules/reference/nav.adoc | 5 +- modules/release-notes/nav.adoc | 1 + modules/release-notes/pages/.change-log.adoc | 2 +- ....v3.0-removal-of-deprecated-features.adoc} | 6 +- .../compatibility/changes-among-tg3.adoc | 94 +++++++++ .../changes-from-tg2-to-tg3.adoc | 188 ++++++++++++++++++ .../pages/compatibility/index.adoc | 21 ++ modules/release-notes/pages/index.adoc | 39 +--- 8 files changed, 314 insertions(+), 42 deletions(-) rename modules/release-notes/pages/{v3.0-removal-of-previously-deprecated-features.adoc => compatibility/.v3.0-removal-of-deprecated-features.adoc} (87%) create mode 100644 modules/release-notes/pages/compatibility/changes-among-tg3.adoc create mode 100644 modules/release-notes/pages/compatibility/changes-from-tg2-to-tg3.adoc create mode 100644 modules/release-notes/pages/compatibility/index.adoc diff --git a/modules/reference/nav.adoc b/modules/reference/nav.adoc index c74d1a23..8777912c 100644 --- a/modules/reference/nav.adoc +++ b/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[] \ No newline at end of file +** xref:glossary.adoc[] +** xref:return-codes.adoc[] \ No newline at end of file diff --git a/modules/release-notes/nav.adoc b/modules/release-notes/nav.adoc index 31f850ee..25d81789 100644 --- a/modules/release-notes/nav.adoc +++ b/modules/release-notes/nav.adoc @@ -1 +1,2 @@ * xref:index.adoc[] +* xref:compatibility/index.adoc[] diff --git a/modules/release-notes/pages/.change-log.adoc b/modules/release-notes/pages/.change-log.adoc index 714c59d3..6f1837c0 100644 --- a/modules/release-notes/pages/.change-log.adoc +++ b/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* diff --git a/modules/release-notes/pages/v3.0-removal-of-previously-deprecated-features.adoc b/modules/release-notes/pages/compatibility/.v3.0-removal-of-deprecated-features.adoc similarity index 87% rename from modules/release-notes/pages/v3.0-removal-of-previously-deprecated-features.adoc rename to modules/release-notes/pages/compatibility/.v3.0-removal-of-deprecated-features.adoc index c331367c..9d41c5e2 100644 --- a/modules/release-notes/pages/v3.0-removal-of-previously-deprecated-features.adoc +++ b/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 diff --git a/modules/release-notes/pages/compatibility/changes-among-tg3.adoc b/modules/release-notes/pages/compatibility/changes-among-tg3.adoc new file mode 100644 index 00000000..2f43028c --- /dev/null +++ b/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. + +|=== + diff --git a/modules/release-notes/pages/compatibility/changes-from-tg2-to-tg3.adoc b/modules/release-notes/pages/compatibility/changes-from-tg2-to-tg3.adoc new file mode 100644 index 00000000..67617ef2 --- /dev/null +++ b/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_LIST` +| Use `LIST` + +| `STRING_SET_COMPRESS` +| Use `SET` + +| `STRING_LIST_CONPRESS` +| Use `LIST` + +| `UINT_SET` +| Use `SET` + +| `UINT32_UINT32_KV_LIST` +| Use `MAP` + +| `INT32_INT32_KV_LIST` +| Use `MAP` + +| `UINT32_UDT_KV_LIST` +| Use `MAP`, where `UDT_type` is a user-defined tuple type + +| `INT32_UDT_KV_LIST` +| Use `MAP`, 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(*)` +|=== diff --git a/modules/release-notes/pages/compatibility/index.adoc b/modules/release-notes/pages/compatibility/index.adoc new file mode 100644 index 00000000..5dec7e0a --- /dev/null +++ b/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[] diff --git a/modules/release-notes/pages/index.adoc b/modules/release-notes/pages/index.adoc index 72108035..090c9f30 100644 --- a/modules/release-notes/pages/index.adoc +++ b/modules/release-notes/pages/index.adoc @@ -52,6 +52,7 @@ TigerGraph Kubernetes Operator allows you to automate operations such as the cre === Data API service * Added two parameters `target_vertex_must_exist` and `source_vertex_must_exist` to xref:3.6@tigergraph-server:API:built-in-endpoints.adoc#_upsert_data_to_graph[the REST endpoint to upsert data]. +* `GET /gsqlserver/gsql/queryinfo` endpoint on port 14240 now returns the query input parameters in the same order as they are in the query instead of an unordered list. === Query Language Enhancement * Reducer function `add()` now accumulates values when loading to a `MAP` attribute. @@ -218,7 +219,8 @@ TigerGraph Server 3.6.1 was released on July 7th, 2022. == Deprecation and Compatibility Warnings * The `-OPTIMIZE` flag for `INSTALL QUERY` is deprecated and is planned to be dropped in the 3.7 release. -* Begining with 3.6.3, a vertex having an empty string as its primary id cannot be loaded. Previously, such a vertex was permitted. + +See xref:compatibility/index.adoc[] == Known Issues @@ -239,38 +241,3 @@ If the `primary_id_as_attribute` option is selected, then attending to perform n * xref:attachment$Release_Notes_3.3.pdf[Release notes - TigerGraph 3.3] * xref:attachment$Release_Notes_3.2.pdf[Release notes - TigerGraph 3.2] -== Compatibility with TigerGraph 3.4 -* A single `POST-ACCUM` clause can no longer reference more than one vertex alias in Syntax V1. -* `GET /requesttoken` endpoint is dropped. -Please use `POST /requesttoken` to request authentication tokens instead. -** Using request body to store credentials is more secure than using query string. -If you have a create a token request that puts the credentials in the query string, all you need to do is use the `POST` endpoint and move your credentials to the request body. -* `GET /gsqlserver/gsql/queryinfo` endpoint on port 14240 now returns the query input parameters in the same order as they are in the query instead of an unordered list. -* Deploying TigerGraph in Kubernetes now requires more service account permissions than previous versions. -For details, see Prerequisites section in xref:3.6@tigergraph-server:kubernetes:quickstart-with-gke.adoc[], xref:3.6@tigergraph-server:kubernetes:quickstart-with-aks.adoc[], and xref:3.6@tigergraph-server:kubernetes:quickstart-with-eks.adoc[]. - -== Compatibility with TigerGraph 3.1 - -The following changes were made to the built-in roles in TigerGraph's Role-based Access Control - -* 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. -* 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. -* To learn more about role management and the privileges of built-in roles, see: -** xref:3.6@tigergraph-server:user-access:role-management.adoc[] -** xref:3.6@tigergraph-server:reference:list-of-privileges.adoc[] - -== Compatibility with TigerGraph 2 - -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:3.6@tigergraph-server:system-management:management-with-gadmin.adoc[Managing with gadmin]. -* Some features which were previously deprecated have been dropped. Please see xref:3.6@tigergraph-server:release-notes:v3.0-removal-of-previously-deprecated-features.adoc[V3.0 Removal of Previously Deprecated Features] for a detailed list. - -include::v3.0-removal-of-previously-deprecated-features.adoc[]