From d29406b924f4a490985e307a6ed541af6f5bc91f Mon Sep 17 00:00:00 2001 From: Dyllan Hofflich Date: Tue, 30 Jul 2024 17:33:10 -0400 Subject: [PATCH 1/2] added changes from updating 4.1 gsql endpoints --- modules/core-functions/pages/auth.adoc | 18 +++++++++------- modules/core-functions/pages/gsql.adoc | 19 ++++++++++++++--- modules/core-functions/pages/query.adoc | 26 +++++++++++++++++++++--- modules/core-functions/pages/schema.adoc | 3 ++- modules/core-functions/pages/utils.adoc | 17 ++++++++++++---- modules/release-notes/pages/index.adoc | 10 +++++++++ 6 files changed, 75 insertions(+), 18 deletions(-) diff --git a/modules/core-functions/pages/auth.adoc b/modules/core-functions/pages/auth.adoc index 74cade5..b1fc9d1 100644 --- a/modules/core-functions/pages/auth.adoc +++ b/modules/core-functions/pages/auth.adoc @@ -94,11 +94,10 @@ See https://docs.tigergraph.com/tigergraph-server/current/user-access/managing-c [discrete] ==== Returns: -If your TigerGraph instance is running version 3.5 or before, the return value is -a tuple of `(, , )`. +If your TigerGraph instance is running version <=3.10, the return value is a tuple of `(, , )`. The return value can be ignored, as the token is automatically set for the connection after this call. -If your TigerGraph instance is running version 3.6 or later, the return value is just the token. +If your TigerGraph instance is running version 4.0, the return value is a tuple of `(, ). [NOTE] The expiration timestamp's time zone might be different from your computer's local time @@ -110,10 +109,11 @@ zone. error occurred. [discrete] -==== Endpoint: -- `POST /requesttoken` +==== Endpoints: +- `POST /requesttoken` (In TigerGraph versions 3.x) + See https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_request_a_token[this] for more details. +- `POST /gsql/v1/tokens` (In TigerGraph versions 4.x) == refreshToken() @@ -126,6 +126,9 @@ raised. + See https://docs.tigergraph.com/admin/admin-guide/user-access-management/user-privileges-and-authentication#rest-authentication[this] for more details. +[NOTE] +This function does not work on TigerGraph version 4.x. + [discrete] ==== Parameters: * `secret`: The secret (string) generated in GSQL using `CREATE SECRET`. @@ -191,9 +194,10 @@ so be careful. occurred, for example if the specified token does not exist. [discrete] -==== Endpoint: -- `DELETE /requesttoken` +==== Endpoints: +- `DELETE /requesttoken` (In TigerGraph versions 3.x) + See https://docs.tigergraph.com/tigergraph-server/current/api/built-in-endpoints#_delete_a_token[this] for more details. +- `POST /gsql/v1/tokens` (In TigerGraph versions 4.x) diff --git a/modules/core-functions/pages/gsql.adoc b/modules/core-functions/pages/gsql.adoc index a7bc05b..efb10f2 100644 --- a/modules/core-functions/pages/gsql.adoc +++ b/modules/core-functions/pages/gsql.adoc @@ -20,6 +20,11 @@ time of establishing the connection will be used. ==== Returns: The output of the statement(s) executed. +[discrete] +==== Endpoints: +- `POST /gsqlserver/gsql/file` (In TigerGraph versions 3.x) +- `POST /gsql/v1/statements` (In TigerGraph versions 4.x) + == installUDF() `installUDF(ExprFunctions: str = "", ExprUtil: str = "") -> None` @@ -37,6 +42,9 @@ See https://docs.tigergraph.com/gsql-ref/current/querying/func/query-user-define ==== Returns: Status of the installation. +[discrete] +==== Endpoints: +- `PUT /gsqlserver/gsql/userdefinedfunction` == getUDF() `getUDF(ExprFunctions: bool = True, ExprUtil: bool = True) -> Union[str, Tuple[str, str]]` @@ -49,10 +57,15 @@ See https://docs.tigergraph.com/gsql-ref/current/querying/func/query-user-define ==== Parameters: * `ExprFunctions (bool, optional)`: Whether to get ExprFunctions. Defaults to True. * `ExprUtil (bool, optional)`: Whether to get ExprUtil. Defaults to True. +* `json_out (bool, optional)``: Whether to output as JSON. Defaults to False. Only supported on version >=4.1 [discrete] ==== Returns: -str: If only one of `ExprFunctions` or `ExprUtil` is True, return of the content of that file. -Tuple[str, str]: content of ExprFunctions and content of ExprUtil. - +* `str`: If only one of `ExprFunctions` or `ExprUtil` is True and json_out is False, return of the content of that file. +* `Tuple[str, str]`: If both `ExprFunctions` and `ExprUtil` are True and json_out is False, return content of ExprFunctions and content of ExprUtil. +* `Dict[str, str]`: If json_out is True, return dict with `ExprFunctions` and/or `ExprUtil` as keys and content of file as value. +[discrete] +==== Endpoints: +- `GET /gsqlserver/gsql/userdefinedfunction` (In TigerGraph versions 3.x) +- `GET /gsql/v1/udt/files` (In TigerGraph versions 4.x) diff --git a/modules/core-functions/pages/query.adoc b/modules/core-functions/pages/query.adoc index f562431..b0af22f 100644 --- a/modules/core-functions/pages/query.adoc +++ b/modules/core-functions/pages/query.adoc @@ -25,6 +25,12 @@ and outputs `PRINT` statement syntax. ==== Parameter: * `queryName (str)`: Name of the query to get metadata of. +[discrete] +==== Endpoints: +- `POST /gsqlserver/gsql/queryinfo` (In TigerGraph versions 3.x) + See xref:tigergraph-server:API:built-in-endpoints.adoc_get_query_metadata[query metadata] +- `POST /gsql/v1/queries/signature` (In TigerGraph versions 4.x) + == getInstalledQueries() `getInstalledQueries(fmt: str = "py") -> Union[dict, str, pd.DataFrame]` @@ -202,9 +208,10 @@ When specifying parameter values in a dictionary: [discrete] -==== Endpoint: -- `POST /gsqlserver/interpreted_query` +==== Endpoints: +- `POST /gsqlserver/interpreted_query` (In TigerGraph versions 3.x) See xref:tigergraph-server:API:built-in-endpoints.adoc#_run_an_interpreted_query[Run an interpreted query] +- `POST /gsql/v1/queries/interpret` (In TigerGraph versions 4.x) @@ -293,6 +300,11 @@ Add a query description and parameter descriptions. Only supported on versions o ==== Returns: The response from the database. +[discrete] +==== Endpoints: +- `PUT /gsqlserver/gsql/description` (In TigerGraph version 4.0) +- `PUT /gsql/v1/description` (In TigerGraph versions >4.0) + == getQueryDescription() `getQueryDescription(queryName = "all")` @@ -309,6 +321,11 @@ If set to "all", returns the description of all queries. ==== Returns: The description of the query(ies). +[discrete] +==== Endpoints: +- `GET /gsqlserver/gsql/description` (In TigerGraph version 4.0) +- `GET /gsql/v1/description` (In TigerGraph versions >4.0) + == dropQueryDescription() `dropQueryDescription(queryName: str, dropParamDescriptions: bool = True)` @@ -325,4 +342,7 @@ If set to "*", drops the description of all queries. ==== Returns: The response from the database. - +[discrete] +==== Endpoints: +- `DELETE /gsqlserver/gsql/description` (In TigerGraph version 4.0) +- `DELETE /gsql/v1/description` (In TigerGraph versions >4.0) diff --git a/modules/core-functions/pages/schema.adoc b/modules/core-functions/pages/schema.adoc index b9bd15c..5966a10 100644 --- a/modules/core-functions/pages/schema.adoc +++ b/modules/core-functions/pages/schema.adoc @@ -22,8 +22,9 @@ The schema metadata. [discrete] ==== Endpoint: -- `GET /gsqlserver/gsql/schema` +- `GET /gsqlserver/gsql/schema` (In TigerGraph version 3.x) See xref:tigergraph-server:API:built-in-endpoints.adoc#_show_graph_schema_metadata[Show graph schema metadata] +- `GET /gsql/v1/schema/graphs/{graph_name}` (In TigerGraph version 4.x) == upsertData() diff --git a/modules/core-functions/pages/utils.adoc b/modules/core-functions/pages/utils.adoc index e4225ba..b7e0f40 100644 --- a/modules/core-functions/pages/utils.adoc +++ b/modules/core-functions/pages/utils.adoc @@ -96,20 +96,29 @@ Monitor system usage metrics. * `from_ts (int, optional)`: The epoch timestamp that indicates the start of the time filter. * `to_ts (int, optional)`: The epoch timestamp that indicates the end of the time filter. * `latest (int, optional)`: Number of datapoints to return. If provided, `from_ts` and `to_ts` will be ignored. -* `what (str, optional)`: Name of the metric to filter for. Possible choices are: + +* `what (str, optional)`: Name of the metric to filter for. Possible choices are: - "cpu": Percentage of CPU usage by component - "mem": Memory usage in megabytes by component - "diskspace": Disk usage in megabytes by directory - "network": Network traffic in bytes since the service started - "qps": Number of requests per second by endpoint -- "servicestate": The state of the service, either online 1 or offline 0 -- "connection": Number of open TCP connections -* `who (str, optional)`: Name of the component that reported the datapoint. +- "servicestate": The state of the service, either online 1 or offline 0 (Only avaliable in version <4.1) +- "connection": Number of open TCP connections (Only avaliable in version <4.1) +* `who (str, optional)`: Name of the component that reported the datapoint. (Only avaliable in version <4.1) * `where (str, optional)`: Name of the node that reported the datapoint. [discrete] ==== Returns: JSON object of datapoints collected. +[NOTE] +Output format differs between 3.x and 4.x versions of TigerGraph. + +[discrete] +==== Endpoints: +- `GET /ts3/api/datapoints` (In TigerGraph versions 3.x) + See xref:tigergraph-server:API:built-in-endpoints.adoc#_monitor_system_metrics_ts3_deprecated[Monitor system metrics (deprecated)] +- `POST /informant/metrics/get/{metrics_category}` (In TigerGraph versions 4.x) + See xref:tigergraph-server:API:built-in-endpoints.adoc#_monitor_system_metrics_by_category[Monitor system metrics] == getQueryPerformance() diff --git a/modules/release-notes/pages/index.adoc b/modules/release-notes/pages/index.adoc index 508b04f..6d24918 100644 --- a/modules/release-notes/pages/index.adoc +++ b/modules/release-notes/pages/index.adoc @@ -6,6 +6,16 @@ Release of pyTigerGraph version 1.6. === Added: * xref:pytigergraph:ai:copilot.adoc[TigerGraph CoPilot]. Added a new submodule for interacting with TigerGraph CoPilot, a framework for integrating Generative AI with TigerGraph. +* Support for TigerGraph versions 4.x +* In 4.x getUDF() can output a JSON, explicitly indicating which file body is from ExprFunctions and ExprUtils + +=== Changed: +* Various endpoints changed when using TG 4.x. +* Output format for getSystemMetrics() has been changed and “servicestate” and “connection” metric categories and the “who” parameter have been removed when using TigerGraph versions 4.x. +* All endpoint requests will have the header {‘X-User-Agent": "pyTigerGraph"} +* refreshToken() has been disabled in TG 4.x since JWT tokens do not support refreshing. + + == [1.5] - 2023-09-25 From 688ad482102f4836078e746aaafe6f7f203fe365 Mon Sep 17 00:00:00 2001 From: Dyllan Hofflich Date: Thu, 1 Aug 2024 17:32:09 -0400 Subject: [PATCH 2/2] adding JWT token change --- modules/release-notes/pages/index.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/release-notes/pages/index.adoc b/modules/release-notes/pages/index.adoc index 6d24918..271b4e6 100644 --- a/modules/release-notes/pages/index.adoc +++ b/modules/release-notes/pages/index.adoc @@ -13,6 +13,7 @@ Release of pyTigerGraph version 1.6. * Various endpoints changed when using TG 4.x. * Output format for getSystemMetrics() has been changed and “servicestate” and “connection” metric categories and the “who” parameter have been removed when using TigerGraph versions 4.x. * All endpoint requests will have the header {‘X-User-Agent": "pyTigerGraph"} +* getToken() will now only create JWT tokens when using TG 4.x. * refreshToken() has been disabled in TG 4.x since JWT tokens do not support refreshing.