Merge pull request #284 from tigergraph/release_2.0.1

Release 2.0.1

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()` removed.** Use `getSecrets()` instead.
+- **`runInstalledQuery()` now auto-selects GET or POST** based on `params` type (`dict` → POST, `str` → GET). Passing a raw query string with `usePost=True` raises `TigerGraphException`.
+- **MCP tools moved to [`pytigergraph-mcp`](https://github.com/tigergraph/pytigergraph-mcp).** Do not import from `pyTigerGraph.mcp` directly.
+
+### New Features
+
+- **Unified vertex parameter syntax for `runInstalledQuery()`.** Use `(id,)` for `VERTEX<T>`, `(id, "type")` for untyped `VERTEX`, and lists of tuples for sets. Works identically for both GET and POST.
+- **MAP parameter support.** Pass a Python `dict` for a `MAP` query parameter; it is converted to TigerGraph's wire format automatically.
+- **`getVectorIndexStatus()`** — poll vector index build status without writing raw GSQL.
+- **`runSchemaChange()`** — run GSQL DDL as a schema-change job via a single API call.
+- **Data-source management APIs** — `createDataSource()`, `updateDataSource()`, `getDataSource()`, `getDataSources()`, `dropDataSource()`, `dropAllDataSources()`.
+- **Improved performance for parallel workloads.** Sync connections use per-thread HTTP sessions; async connections use `aiohttp`. Both reduce contention and improve throughput under concurrent load.
+- **TigerGraph 3.x compatibility.** Queries, loading jobs, and schema operations automatically fall back to 3.x `gsqlserver` endpoints, so the same client code works on both 3.x and 4.x.
+
+### Fixed
+
+- **Edge upsert `vertexMustExist`** flag now correctly forwarded to TigerGraph in all code paths.
+- **Edge upsert attribute payloads** serialized correctly for all attribute types.
+
+---
+
+## [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. 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2022 TigerGraph Inc.
+   Copyright 2022-2026 TigerGraph Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -1,66 +1,233 @@
 # pyTigerGraph
 
-pyTigerGraph is a Python package for connecting to TigerGraph databases. Check out the documentation [here](https://docs.tigergraph.com/pytigergraph/current/intro/).
+pyTigerGraph is a Python client for [TigerGraph](https://www.tigergraph.com/) databases. It wraps the REST++ and GSQL APIs and provides both a synchronous and an asynchronous interface.
 
-[![Downloads](https://static.pepy.tech/badge/pyTigergraph)](https://pepy.tech/project/pyTigergraph)
-[![Downloads](https://static.pepy.tech/badge/pyTigergraph/month)](https://pepy.tech/project/pyTigergraph)
-[![Downloads](https://static.pepy.tech/badge/pyTigergraph/week)](https://pepy.tech/project/pyTigergraph)
+Full documentation: <https://docs.tigergraph.com/pytigergraph/current/intro/>
 
-## Quickstart
+Downloads: [![Total Downloads](https://static.pepy.tech/badge/pyTigergraph)](https://pepy.tech/project/pyTigergraph) | [![Monthly Downloads](https://static.pepy.tech/badge/pyTigergraph/month)](https://pepy.tech/project/pyTigergraph) | [![Weekly Downloads](https://static.pepy.tech/badge/pyTigergraph/week)](https://pepy.tech/project/pyTigergraph)
+
+---
+
+## Installation
+
+### Base package
 
-### Installing pyTigerGraph
-This section walks you through installing pyTigerGraph on your machine.
+```sh
+pip install pyTigerGraph
+```
 
-#### Prerequisites
-* Python 3+
-* If you wish to use the GDS functionality, install `torch` ahead of time.
+### Optional extras
 
-#### Install _pyTigerGraph_
+| Extra | What it adds | Install command |
+|-------|-------------|-----------------|
+| `gds` | Graph Data Science — data loaders for PyTorch Geometric, DGL, and Pandas | `pip install 'pyTigerGraph[gds]'` |
+| `mcp` | Model Context Protocol server — installs [`pyTigerGraph-mcp`](https://github.com/tigergraph/tigergraph-mcp) (convenience alias) | `pip install 'pyTigerGraph[mcp]'` |
+| `fast` | [orjson](https://github.com/ijl/orjson) JSON backend — 2–10× faster parsing, releases the GIL under concurrent load | `pip install 'pyTigerGraph[fast]'` |
 
-To download _pyTigerGraph_, run the following command in the command line or use the appropriate tool of your development environment (anaconda, PyCharm, etc.).:
+Extras can be combined:
 
 ```sh
-pip3 install pyTigerGraph
+pip install 'pyTigerGraph[fast,gds,mcp]'
 ```
 
-#### Install _pyTigerGraph[gds]_
+#### `[gds]` prerequisites
 
-To utilize the Graph Data Science Functionality, there are a few options:
-* To use the GDS functions with **PyTorch Geometric**, install `torch` and `PyTorch Geometric` according to their instructions:
+Install `torch` before installing the `gds` extra:
 
-    1) [Install Torch](https://pytorch.org/get-started/locally/)
+1. [Install Torch](https://pytorch.org/get-started/locally/)
+2. Optionally [Install PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html) or [Install DGL](https://www.dgl.ai/pages/start.html)
+3. `pip install 'pyTigerGraph[gds]'`
 
-    2) [Install PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/notes/installation.html)
+#### `[fast]` — orjson JSON backend
 
-    3) Install pyTigerGraph with:
-        ```sh
-        pip3 install 'pyTigerGraph[gds]'
-        ```
+`orjson` is a Rust-backed JSON library that is detected and used automatically when installed. No code changes are required. It improves throughput in two ways:
 
-* To use the GDS functions with **DGL**, install `torch` and `dgl` according to their instructions:
+- **Faster parsing** — 2–10× vs stdlib `json`
+- **GIL release** — threads parse responses concurrently instead of serialising on the GIL
 
-    1) [Install Torch](https://pytorch.org/get-started/locally/)
+If `orjson` is not installed the library falls back to stdlib `json` transparently.
 
-    2) [Install DGL](https://www.dgl.ai/pages/start.html)
+---
 
-    3) Install pyTigerGraph with:
-        ```sh
-        pip3 install 'pyTigerGraph[gds]'
-        ```
+## Quickstart
 
-* To use the GDS functions without needing to produce output in the format supported by PyTorch Geometric or DGL.
-This makes the data loaders output *Pandas dataframes*:
-```sh
-pip3 install 'pyTigerGraph[gds]'
+### Synchronous connection
+
+```python
+from pyTigerGraph import TigerGraphConnection
+
+conn = TigerGraphConnection(
+    host="http://localhost",
+    graphname="my_graph",
+    username="tigergraph",
+    password="tigergraph",
+)
+
+print(conn.echo())
 ```
 
-Once the package is installed, you can import it like any other Python package:
+Use as a context manager to ensure the underlying HTTP session is closed:
 
-```py
-import pyTigerGraph as tg
+```python
+with TigerGraphConnection(host="http://localhost", graphname="my_graph") as conn:
+    result = conn.runInstalledQuery("my_query", {"param": "value"})
 ```
-### Getting Started with Core Functions
+
+### Asynchronous connection
+
+`AsyncTigerGraphConnection` exposes the same API as `TigerGraphConnection` but with `async`/`await` syntax. It uses [aiohttp](https://docs.aiohttp.org/) internally and shares a single connection pool across all concurrent tasks, making it significantly more efficient than threaded sync code at high concurrency.
+
+```python
+import asyncio
+from pyTigerGraph import AsyncTigerGraphConnection
+
+async def main():
+    async with AsyncTigerGraphConnection(
+        host="http://localhost",
+        graphname="my_graph",
+        username="tigergraph",
+        password="tigergraph",
+    ) as conn:
+        result = await conn.runInstalledQuery("my_query", {"param": "value"})
+        print(result)
+
+asyncio.run(main())
+```
+
+### Token-based authentication
+
+```python
+conn = TigerGraphConnection(
+    host="http://localhost",
+    graphname="my_graph",
+    gsqlSecret="my_secret",   # generates a session token automatically
+)
+```
+
+### HTTPS / TigerGraph Cloud
+
+```python
+conn = TigerGraphConnection(
+    host="https://my-instance.i.tgcloud.io",
+    graphname="my_graph",
+    username="tigergraph",
+    password="tigergraph",
+    tgCloud=True,
+)
+```
+
+---
+
+## Connection parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `host` | `str` | `"http://127.0.0.1"` | Server URL including scheme (`http://` or `https://`) |
+| `graphname` | `str` | `""` | Target graph name |
+| `username` | `str` | `"tigergraph"` | Database username |
+| `password` | `str` | `"tigergraph"` | Database password |
+| `gsqlSecret` | `str` | `""` | GSQL secret for token-based auth (preferred over username/password) |
+| `apiToken` | `str` | `""` | Pre-obtained REST++ API token |
+| `jwtToken` | `str` | `""` | JWT token for customer-managed authentication |
+| `restppPort` | `int\|str` | `"9000"` | REST++ port (auto-fails over to `14240/restpp` for TigerGraph 4.x) |
+| `gsPort` | `int\|str` | `"14240"` | GSQL server port |
+| `certPath` | `str` | `None` | Path to CA certificate for HTTPS |
+| `tgCloud` | `bool` | `False` | Set to `True` for TigerGraph Cloud instances |
+
+---
+
+## Performance notes
+
+### Synchronous mode (`TigerGraphConnection`)
+
+- Each thread gets its own dedicated HTTP session and connection pool, so concurrent threads never block each other.
+- Install `pyTigerGraph[fast]` to activate the `orjson` backend and reduce JSON parsing overhead under concurrent load.
+- Use `ThreadPoolExecutor` to run queries in parallel:
+
+```python
+from concurrent.futures import ThreadPoolExecutor, as_completed
+
+with TigerGraphConnection(...) as conn:
+    with ThreadPoolExecutor(max_workers=16) as executor:
+        futures = [executor.submit(conn.runInstalledQuery, "q", {"p": v}) for v in values]
+        for f in as_completed(futures):
+            print(f.result())
+```
+
+### Asynchronous mode (`AsyncTigerGraphConnection`)
+
+- Uses a single `aiohttp.ClientSession` with an unbounded connection pool shared across all concurrent coroutines — no GIL, no thread-scheduling overhead.
+- Typically achieves higher QPS and lower tail latency than the threaded sync mode for I/O-bound workloads.
+
+```python
+import asyncio
+from pyTigerGraph import AsyncTigerGraphConnection
+
+async def main():
+    async with AsyncTigerGraphConnection(...) as conn:
+        tasks = [conn.runInstalledQuery("q", {"p": v}) for v in values]
+        results = await asyncio.gather(*tasks)
+
+asyncio.run(main())
+```
+
+---
+
+## Graph Data Science (GDS)
+
+The `gds` sub-module provides data loaders that stream vertex and edge data from TigerGraph directly into PyTorch Geometric, DGL, or Pandas DataFrames for machine learning workflows.
+
+Install requirements, then access via `conn.gds`:
+
+```python
+conn = TigerGraphConnection(host="...", graphname="...")
+loader = conn.gds.vertexLoader(attributes=["feat", "label"], batch_size=1024)
+for batch in loader:
+    train(batch)
+```
+
+See the [GDS documentation](https://docs.tigergraph.com/pytigergraph/current/gds/) for full details.
+
+---
+
+## MCP Server
+
+The TigerGraph MCP server is now a standalone package: **[pyTigerGraph-mcp](https://github.com/tigergraph/tigergraph-mcp)**. It exposes TigerGraph operations as tools for AI agents and LLM applications (Claude Desktop, Cursor, Copilot, etc.).
+
+```sh
+# Recommended — install the standalone package directly
+pip install pyTigerGraph-mcp
+
+# Or via the pyTigerGraph convenience alias (installs pyTigerGraph-mcp automatically)
+pip install 'pyTigerGraph[mcp]'
+
+# Start the server (reads connection config from environment variables)
+tigergraph-mcp
+```
+
+For full setup instructions, available tools, configuration examples, and multi-profile support, see the **[pyTigerGraph-mcp README](https://github.com/tigergraph/tigergraph-mcp#readme)**.
+
+> **Migrating from `pyTigerGraph.mcp`?** Update your imports:
+> ```python
+> # Old
+> from pyTigerGraph.mcp import serve, ConnectionManager
+> # New
+> from tigergraph_mcp import serve, ConnectionManager
+> ```
+
+---
+
+## Getting started video
 
 [![pyTigerGraph 101](https://img.youtube.com/vi/2BcC3C-qfX4/hqdefault.jpg)](https://www.youtube.com/watch?v=2BcC3C-qfX4)
 
-The video above is a good starting place for learning the core functions of pyTigerGraph. [This Google Colab notebook](https://colab.research.google.com/drive/1JhYcnGVWT51KswcXZzyPzKqCoPP5htcC) is the companion notebook to the video.
+Companion notebook: [Google Colab](https://colab.research.google.com/drive/1JhYcnGVWT51KswcXZzyPzKqCoPP5htcC)
+
+---
+
+## Links
+
+- [Documentation](https://docs.tigergraph.com/pytigergraph/current/intro/)
+- [PyPI](https://pypi.org/project/pyTigerGraph/)
+- [GitHub Issues](https://github.com/tigergraph/pyTigerGraph/issues)
+- [Source](https://github.com/tigergraph/pyTigerGraph)