Revise runInstalledQuery backward compatibility

Author: chengbiao-jin

CHANGELOG.md

@@ -5,6 +5,116 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.1] - 2026-03-23
+
+### Breaking Changes
+
+- **`showSecrets()` has been removed.** Replace all calls with `getSecrets()`.
+- **`usePost` default changed from `False` to `None`** in `runInstalledQuery()`. The transport is now auto-selected based on `params` type (dict → POST, string → GET). Code that relied on dict params always going through POST is unaffected; code that passed a raw query string and expected POST will now use GET instead.
+- **`usePost=True` with a string `params` now raises `TigerGraphException`** instead of silently sending a malformed request body. Convert the string to a dict or drop `usePost=True` instead.
+
+### New Features
+
+- **Unified vertex parameter syntax for `runInstalledQuery()`.** The same tuple notation now works correctly for both GET and POST — no need to format params differently depending on `usePost`:
+  - `(id,)` — typed vertex `VERTEX<T>`
+  - `(id, "type")` — untyped vertex `VERTEX`
+  - `[(id,), ...]` — typed vertex set `SET<VERTEX<T>>`
+  - `[(id, "type"), ...]` — untyped vertex set `SET<VERTEX>`
+- **MAP query parameter support.** Pass a Python `dict` directly for a `MAP` parameter; it is converted to TigerGraph's wire format automatically. A dict with an `"id"` key is treated as a pre-formatted vertex object and passed through unchanged.
+
+### Compatibility Notes
+
+- **Old-style plain IDs for typed vertex params still work**, but at a cost. If you pass `{"p": 1}` instead of `{"p": (1,)}` for a `VERTEX<T>` parameter, `runInstalledQuery()` catches the server-side rejection and retries transparently via GET, logging a warning. Each such call incurs one extra HTTP round-trip. Migrate to `(id,)` tuples to eliminate the overhead.
+- **`(id, "")` (empty type string) now raises immediately** on the client instead of forwarding to TigerGraph. Update any code relying on the server-side error to handle the client-side `TigerGraphException` instead.
+- **MCP tools have moved to [`pytigergraph-mcp`](https://github.com/tigergraph/pytigergraph-mcp).** Do not import from `pyTigerGraph.mcp` directly; install and use the dedicated `pytigergraph-mcp` package instead.
+
+---
+
+## [2.0.0] - 2025-03-04
+
+### Added
+
+- **MCP (Model Context Protocol) tools.** pyTigerGraph now ships with built-in MCP tool definitions, enabling integration with MCP-compatible AI frameworks.
+
+---
+
+## [1.9.1] - 2024-11-04
+
+### Changed
+
+- API enhancements.
+
+---
+
+## [1.9.0] - 2025-06-30
+
+### Changed
+
+- Multiple API enhancements.
+
+---
+
+## [1.8.4] - 2025-01-20
+
+### Fixed
+
+- Fixed URL construction when `gsPort` and `restppPort` are set to the same value.
+
+---
+
+## [1.8.3] - 2024-12-04
+
+### Fixed
+
+- Fixed `httpx` timeout during async function calls, most notably when installing a query via `.gsql()`.
+
+---
+
+## [1.8.1] - 2024-11-19
+
+### Fixed
+
+- Fixed import error of `TigerGraphException` in the GDS submodule.
+
+---
+
+## [1.8.0] - 2024-11-04
+
+### Added
+
+- **`AsyncTigerGraphConnection`** — full async communication with TigerGraph using the new `AsyncTigerGraphConnection` class.
+- **`delVerticesByType()`** — delete all vertices of a given type in one call.
+- **`limit` parameter for `getEdgesByType()`** — cap the number of edges returned. Note: the limit is applied client-side after retrieval.
+- **Upsert atomicity configuration** — new parameters to control atomicity behaviour of upsert operations.
+- **`runLoadingJobWithDataFrame()`** — run a GSQL loading job directly from a Pandas DataFrame.
+- **`runLoadingJobWithData()`** — run a GSQL loading job from a raw data string.
+
+---
+
+## [1.7.4] - 2024-10-16
+
+### Fixed
+
+- Fixed error when generating a token via `getToken()` with a secret key.
+
+---
+
+## [1.7.3] - 2024-10-14
+
+### Fixed
+
+- Fixed error when generating a token via `getToken()` on TigerGraph Cloud v3.x instances.
+
+---
+
+## [1.7.2] - 2024-10-01
+
+### Added
+
+- **`delVerticesByType()`** — delete all vertices of a specified type. Supports `permanent` (prevent re-insertion of the same IDs) and `ack` (`"all"` or `"none"`) parameters.
+
+---
+
 ## [1.1] - 2022-09-06
 
 Release of pyTigerGraph version 1.1. 

pyTigerGraph/__init__.py

@@ -11,22 +11,8 @@
 
 __license__ = "Apache 2"
 
-# Optional MCP support
-try:
-    from pyTigerGraph.mcp import serve, MCPServer, get_connection, ConnectionManager
-    __all__ = [
-        "TigerGraphConnection",
-        "AsyncTigerGraphConnection",
-        "TigerGraphException",
-        "serve",
-        "MCPServer",
-        "get_connection",
-        "ConnectionManager",
-    ]
-except ImportError:
-    # MCP dependencies not installed
-    __all__ = [
-        "TigerGraphConnection",
-        "AsyncTigerGraphConnection",
-        "TigerGraphException",
-    ]
+__all__ = [
+    "TigerGraphConnection",
+    "AsyncTigerGraphConnection",
+    "TigerGraphException",
+]

pyTigerGraph/common/query.py

@@ -53,34 +53,46 @@ def _parse_query_parameters(params: dict) -> str:
     require special handling.
 
     See xref:tigergraph-server:API:built-in-endpoints.adoc#_query_parameter_passing[Query parameter passing]
-
-    TODO Accept this format for SET<VERTEX>:
-        "key": [([p_id1, p_id2, ...], "vtype"), ...]
-        I.e. multiple primary IDs of the same vertex type
     """
     logger.debug("entry: _parseQueryParameters")
     logger.debug("params: " + str(params))
 
     parts = []
     for k, v in params.items():
         if isinstance(v, tuple):
-            if len(v) == 2 and isinstance(v[1], str):
+            if len(v) == 1:
+                # VERTEX<T> (typed): (id,)  →  k=id
+                parts.append(k + "=" + _safe_char(v[0]))
+            elif len(v) == 2 and isinstance(v[1], str):
+                if not v[1]:
+                    raise TigerGraphException(
+                        f"Invalid vertex parameter '{k}': vertex type string must not be empty. "
+                        "Use (id,) for VERTEX<T> or (id, 'type') for untyped VERTEX.")
+                # VERTEX (untyped): (id, "type")  →  k=id&k.type=type
                 parts.append(k + "=" + str(v[0]))
                 parts.append(k + ".type=" + _safe_char(v[1]))
             else:
                 raise TigerGraphException(
-                    "Invalid parameter value: (vertex_primary_id, vertex_type)"
-                    " was expected.")
+                    f"Invalid vertex parameter '{k}': expected (id,) for VERTEX<T> "
+                    "or (id, 'type') for untyped VERTEX.")
         elif isinstance(v, list):
             for i, vv in enumerate(v):
                 if isinstance(vv, tuple):
-                    if len(vv) == 2 and isinstance(vv[1], str):
+                    if len(vv) == 1:
+                        # SET<VERTEX<T>>: (id,)  →  k=id  (repeated, no index)
+                        parts.append(k + "=" + _safe_char(vv[0]))
+                    elif len(vv) == 2 and isinstance(vv[1], str):
+                        if not vv[1]:
+                            raise TigerGraphException(
+                                f"Invalid vertex parameter '{k}[{i}]': vertex type string must not be empty. "
+                                "Use (id,) for VERTEX<T> or (id, 'type') for untyped VERTEX.")
+                        # SET<VERTEX>: (id, "type")  →  k[i]=id&k[i].type=type
                         parts.append(k + "[" + str(i) + "]=" + _safe_char(vv[0]))
                         parts.append(k + "[" + str(i) + "].type=" + vv[1])
                     else:
                         raise TigerGraphException(
-                            "Invalid parameter value: (vertex_primary_id, vertex_type)"
-                            " was expected.")
+                            f"Invalid vertex parameter '{k}[{i}]': expected (id,) for VERTEX<T> "
+                            "or (id, 'type') for untyped VERTEX.")
                 else:
                     parts.append(k + "=" + _safe_char(vv))
         elif isinstance(v, datetime):
@@ -95,6 +107,115 @@ def _parse_query_parameters(params: dict) -> str:
 
     return ret
 
+def _encode_str_for_post(value: str) -> str:
+    """Encode ``%`` as ``%25`` in string values destined for TigerGraph's POST
+    /query JSON body.
+
+    TigerGraph's RESTPP POST parser URL-decodes string values inside JSON
+    payloads.  A bare ``%`` followed by hex-like characters is mis-interpreted
+    as a percent-encoded sequence, causing a ``REST-30000`` parse error.
+    Encoding ``%`` → ``%25`` prevents this; the server decodes it back to
+    ``%`` transparently.
+    """
+    return value.replace("%", "%25")
+
+
+def _prep_query_parameters_json(params: dict) -> dict:
+    """Converts a parameter dictionary into the JSON format expected by TigerGraph's
+    POST /query endpoint.
+
+    Handles the same Python conventions as ``_parse_query_parameters`` (used for
+    GET mode), but produces a JSON-serialisable dict instead of a query string.
+
+    Conversion rules (per TigerGraph REST API docs):
+        - ``(id,)`` 1-tuple        →  ``{"id": id}``
+          Use for VERTEX<T> (typed vertex) parameters.
+        - ``(id, "type")`` 2-tuple →  ``{"id": id, "type": "type"}``
+          Use for VERTEX (untyped vertex) parameters.
+        - ``list`` of 1-tuples     →  ``[{"id": id}, ...]``
+          Use for SET<VERTEX<T>> (typed vertex set) parameters.
+        - ``list`` of 2-tuples     →  ``[{"id": id, "type": "type"}, ...]``
+          Use for SET<VERTEX> (untyped vertex set) parameters.
+        - ``datetime``             →  ``"YYYY-MM-DD HH:MM:SS"``
+        - ``dict`` with ``"id"``   →  passed through unchanged
+          (caller already supplied correct vertex JSON object)
+        - ``dict`` without ``"id"``→  ``{"keylist": [...], "valuelist": [...]}``
+          (Python dict → TigerGraph MAP wire format)
+        - ``list`` of dicts        →  passed through unchanged
+        - ``str``                  →  ``%`` encoded as ``%25``
+          (TigerGraph URL-decodes strings inside JSON POST bodies)
+        - primitive / other        →  left as-is
+
+    Note: plain ``str`` / ``int`` values are correct for STRING/INT/FLOAT/…
+    parameters only.  Always use tuples for vertex parameters — the API cannot
+    distinguish a STRING value from a VERTEX<T> ID without schema introspection.
+
+    See https://docs.tigergraph.com/tigergraph-server/4.2/api/built-in-endpoints#_run_an_installed_query_post
+    """
+    if not params or not isinstance(params, dict):
+        return params
+
+    converted = {}
+    for k, v in params.items():
+        if isinstance(v, tuple):
+            if len(v) == 1:
+                # VERTEX<T> (typed): (id,)  →  {"id": id}
+                converted[k] = {"id": v[0]}
+            elif len(v) == 2 and isinstance(v[1], str):
+                if not v[1]:
+                    raise TigerGraphException(
+                        f"Invalid vertex parameter '{k}': vertex type string must not be empty. "
+                        "Use (id,) for VERTEX<T> or (id, 'type') for untyped VERTEX.")
+                # VERTEX (untyped): (id, "type")  →  {"id": id, "type": "type"}
+                converted[k] = {"id": v[0], "type": v[1]}
+            else:
+                raise TigerGraphException(
+                    f"Invalid vertex parameter '{k}': expected (id,) for VERTEX<T> "
+                    "or (id, 'type') for untyped VERTEX.")
+        elif isinstance(v, dict):
+            if "id" in v:
+                # Pre-formatted vertex object — pass through unchanged.
+                converted[k] = v
+            else:
+                # Python dict → TigerGraph MAP wire format.
+                converted[k] = {
+                    "keylist": list(v.keys()),
+                    "valuelist": list(v.values()),
+                }
+        elif isinstance(v, list):
+            new_list = []
+            for vv in v:
+                if isinstance(vv, tuple):
+                    if len(vv) == 1:
+                        # SET<VERTEX<T>>: (id,)  →  {"id": id}
+                        new_list.append({"id": vv[0]})
+                    elif len(vv) == 2 and isinstance(vv[1], str):
+                        if not vv[1]:
+                            raise TigerGraphException(
+                                f"Invalid vertex parameter '{k}': vertex type string must not be empty. "
+                                "Use (id,) for VERTEX<T> or (id, 'type') for untyped VERTEX.")
+                        # SET<VERTEX>: (id, "type")  →  {"id": id, "type": "type"}
+                        new_list.append({"id": vv[0], "type": vv[1]})
+                    else:
+                        raise TigerGraphException(
+                            f"Invalid vertex parameter '{k}': expected (id,) for VERTEX<T> "
+                            "or (id, 'type') for untyped VERTEX.")
+                elif isinstance(vv, datetime):
+                    new_list.append(vv.strftime("%Y-%m-%d %H:%M:%S"))
+                elif isinstance(vv, str):
+                    new_list.append(_encode_str_for_post(vv))
+                else:
+                    new_list.append(vv)
+            converted[k] = new_list
+        elif isinstance(v, datetime):
+            converted[k] = v.strftime("%Y-%m-%d %H:%M:%S")
+        elif isinstance(v, str):
+            converted[k] = _encode_str_for_post(v)
+        else:
+            converted[k] = v
+    return converted
+
+
 def _prep_run_installed_query(timeout, sizeLimit, runAsync, replica, threadLimit, memoryLimit):
     """header builder for runInstalledQuery()"""
     headers = {}

pyTigerGraph/pyTigerGraphAuth.py

@@ -5,7 +5,6 @@
 """
 
 import logging
-import warnings
 import requests
 
 from typing import Union, Tuple, Dict
@@ -136,16 +135,6 @@ def getSecrets(self, userName: str = "", alias: str = "", createNew: bool = Fals
 
             return ret
 
-    def showSecrets(self) -> Dict[str, str]:
-        """DEPRECATED
-
-        Use `getSecrets()` instead.
-        """
-        warnings.warn("The `showSecrets()` function is deprecated; use `getSecrets()` instead.",
-                      DeprecationWarning)
-
-        return self.getSecrets()
-
     def createSecret(self, alias: str = "", withAlias: bool = False, value: str = "", userName: str = "" ) -> Union[str, Dict[str, str]]:
         """Creates a secret for generating authentication tokens.
 
@@ -283,8 +272,7 @@ def dropSecret(self, alias: Union[str, list], ignoreErrors: bool = True, userNam
                 single_secret = secrets_list[0]
                 try:
                     res = self._delete(self.gsUrl+"/gsql/v1/secrets/"+single_secret,
-                                     authMode="pwd", resKey="message",
-                                     headers={'Content-Type': 'application/json'})
+                                     authMode="pwd", resKey=None)
                     if logger.level == logging.DEBUG:
                         logger.debug("return: " + str(res))
                     logger.debug("exit: dropSecret")
@@ -295,7 +283,7 @@ def dropSecret(self, alias: Union[str, list], ignoreErrors: bool = True, userNam
                     if logger.level == logging.DEBUG:
                         logger.debug("return: error ignored")
                     logger.debug("exit: dropSecret")
-                    return {"error": False, "message": "Error ignored as requested"}
+                    return {"error": False, "message": f"Failed to drop secrets: [{single_secret}]"}
 
             # Multiple secrets/aliases or with userName - use payload
             url = self.gsUrl+"/gsql/v1/secrets"
@@ -305,8 +293,8 @@ def dropSecret(self, alias: Union[str, list], ignoreErrors: bool = True, userNam
 
             data = {"secrets": secrets_list}
             try:
-                res = self._delete(url, data=data, params=params, authMode="pwd", resKey="message", 
-                                 headers={'Content-Type': 'application/json'}, jsonData=True)
+                res = self._delete(url, data=data, params=params, authMode="pwd", resKey=None,
+                                 jsonData=True)
                 if logger.level == logging.DEBUG:
                     logger.debug("return: " + str(res))
                 logger.debug("exit: dropSecret")
@@ -317,7 +305,7 @@ def dropSecret(self, alias: Union[str, list], ignoreErrors: bool = True, userNam
                 if logger.level == logging.DEBUG:
                     logger.debug("return: error ignored")
                 logger.debug("exit: dropSecret")
-                return {"error": False, "message": "Error ignored as requested"}
+                return {"error": False, "message": f"Failed to drop secrets: {secrets_list}"}
         else:
             # For older versions, use GSQL command
             if isinstance(alias, str):
@@ -574,7 +562,7 @@ def checkJwtToken(self, token: str = None) -> dict:
         data = {"token": token}
         res = self._post(self.gsUrl+"/gsql/v1/tokens/check",
                         data=data, authMode="pwd", resKey=None,
-                        headers={'Content-Type': 'application/json'})
+                        headers={'Content-Type': 'application/json'}, jsonData=True)
 
         if logger.level == logging.DEBUG:
             logger.debug("return: " + str(res))