pyTigerGraph

pyTigerGraph is a Python client for TigerGraph databases. It wraps the REST++ and GSQL APIs and provides both a synchronous and an asynchronous interface.

Full documentation: https://docs.tigergraph.com/pytigergraph/current/intro/

Downloads: | |

Installation

Base package

pip install pyTigerGraph

Optional extras

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` (convenience alias)	`pip install 'pyTigerGraph[mcp]'`
`fast`	orjson JSON backend — 2–10× faster parsing, releases the GIL under concurrent load	`pip install 'pyTigerGraph[fast]'`

Extras can be combined:

pip install 'pyTigerGraph[fast,gds,mcp]'

`[gds]` prerequisites

Install torch before installing the gds extra:

Install Torch
Optionally Install PyTorch Geometric or Install DGL
pip install 'pyTigerGraph[gds]'

`[fast]` — orjson JSON backend

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:

Faster parsing — 2–10× vs stdlib json
GIL release — threads parse responses concurrently instead of serialising on the GIL

If orjson is not installed the library falls back to stdlib json transparently.

Quickstart

Synchronous connection

from pyTigerGraph import TigerGraphConnection

conn = TigerGraphConnection(
    host="http://localhost",
    graphname="my_graph",
    username="tigergraph",
    password="tigergraph",
)

print(conn.echo())

Use as a context manager to ensure the underlying HTTP session is closed:

with TigerGraphConnection(host="http://localhost", graphname="my_graph") as conn:
    result = conn.runInstalledQuery("my_query", {"param": "value"})

Asynchronous connection

AsyncTigerGraphConnection exposes the same API as TigerGraphConnection but with async/await syntax. It uses aiohttp internally and shares a single connection pool across all concurrent tasks, making it significantly more efficient than threaded sync code at high concurrency.

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

conn = TigerGraphConnection(
    host="http://localhost",
    graphname="my_graph",
    gsqlSecret="my_secret",   # generates a session token automatically
)

HTTPS / TigerGraph Cloud

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:

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.

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:

conn = TigerGraphConnection(host="...", graphname="...")
loader = conn.gds.vertexLoader(attributes=["feat", "label"], batch_size=1024)
for batch in loader:
    train(batch)

See the GDS documentation for full details.

MCP Server

The TigerGraph MCP server is now a standalone package: pyTigerGraph-mcp. It exposes TigerGraph operations as tools for AI agents and LLM applications (Claude Desktop, Cursor, Copilot, etc.).

# 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.

Migrating from pyTigerGraph.mcp? Update your imports:

# Old
from pyTigerGraph.mcp import serve, ConnectionManager
# New
from tigergraph_mcp import serve, ConnectionManager

Getting started video

Companion notebook: Google Colab

Release files for pyTigerGraph 2.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyTigerGraph 2.0.4
File	Size	Uploaded
pytigergraph-2.0.4.tar.gz	364.5 kB	May 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pyTigerGraph 2.0.4
File	Interpreter	ABI	Platform	Reset
pytigergraph-2.0.4-py3-none-any.whl 352.5 kB May 19, 2026	Python 3	none	any	Details

Total release size: 717.0 kB

Release files / pytigergraph-2.0.4.tar.gz

Download URL	pytigergraph-2.0.4.tar.gz
Size	364.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`1b72ab97c709f332e77841c2b22d0786af01e840c6cddd73c2347b7cdd214d3a`
BLAKE2b-256 checksum How to use checksums	`6d9678a0b24428e5104b81d1f39355bb59086067a3981434a95c9e3b16f2f118`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`

Release files / pytigergraph-2.0.4-py3-none-any.whl

Download URL	pytigergraph-2.0.4-py3-none-any.whl
Size	352.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`6b83a8c9a376fda0d57c687bbf79dda57024225d6e23aa99a69ef71cb90e47e7`
BLAKE2b-256 checksum How to use checksums	`5c0b45e391c88e3cd6b822fa621da1131747fedd06a907f96dabcf5a06a42835`
Upload date	May 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`