Connect with pyTigerGraph

pyTigerGraph is TigerGraph’s Python client. Use it to call a Savanna workspace from a script or application: run installed queries, read and write vertices and edges, and work with the same graph you built in the console.

This page gets you from install to a successful call against your workspace.

Before you start

pyTigerGraph talks to the workspace host, the database behind that workspace. Authenticate with a database secret. Control-plane calls, such as creating workspaces, use api.tgcloud.io and an API key instead. See Savanna REST API. If the workgroup uses an IP allowlist, include the machine that runs the script. See Configure network access.

Install

pip install pyTigerGraph

Connect

A Savanna connection needs the workspace URL, the graph name, and a database secret.

Argument Required What to use

host

Yes

Your workspace URL, including https://. Open Workspaces, select the workspace, and copy its URL. A Savanna host looks like https://<workspace-id>.i.tgcloud.io.

graphname

Yes

The graph this connection uses. Create the graph in Design Schema if you do not have one yet.

gsqlSecret

Yes

A database secret for that workspace. See Create a database secret.

When the host contains tgcloud, pyTigerGraph treats the instance as TigerGraph Cloud and sends REST++ and GSQL traffic to port 443, which is how Savanna publishes the workspace. Leave restppPort and gsPort at their defaults.

from pyTigerGraph import TigerGraphConnection

conn = TigerGraphConnection(
    host="https://<workspace-id>.i.tgcloud.io",
    graphname="MyGraph",
    gsqlSecret="<database-secret>",
)

print(conn.echo())
print(conn.getVertexTypes())

echo() returns a response when the workspace host answers. getVertexTypes() returns the vertex type names on the graph when the secret can read it.

Read the secret from the environment so it stays out of source control:

import os
from pyTigerGraph import TigerGraphConnection

conn = TigerGraphConnection(
    host=os.environ["TG_HOST"],
    graphname=os.environ["TG_GRAPHNAME"],
    gsqlSecret=os.environ["TG_SECRET"],
)

Run a query

runInstalledQuery calls a query that is already installed on the graph. Install the query in the GSQL Editor first, or from pyTigerGraph with the client’s query methods.

result = conn.runInstalledQuery("my_query", params={"param": "value"})
print(result)

Vertices, edges, schema changes, and loading jobs are covered in the pyTigerGraph documentation. The HTTP calls underneath are the workspace data-plane APIs.

Treat database secrets like passwords. Store them securely and do not commit them to source control. A database secret does not expire and remains valid until you delete or revoke it. Calls through pyTigerGraph run against the connected database and can modify or delete data.

Troubleshooting

Invalid URL scheme

host needs a scheme. Use https://<workspace-id>.i.tgcloud.io. A hostname alone raises Invalid URL scheme.

Authentication failed

Create the secret in Savanna for the same workspace, and paste the full value into gsqlSecret. A control-plane API key is a different credential and will not authenticate this connection. See Create a database secret.

Connection error

Confirm the workspace status is active, the host is the workspace URL, and your IP is on the workgroup allowlist when one is enabled. See About workspaces and Configure network access.

Where to go next