From 138926e240e5ff114b943101879efb84a9741930 Mon Sep 17 00:00:00 2001 From: nik_garakapati Date: Mon, 28 Sep 2026 12:50:46 +0530 Subject: [PATCH] docs(savanna): document connecting pyTigerGraph with a database secret Savanna readers need a workspace host and secret example, and the overview now links to that path from the start page. --- .../settings/how2-create-database-secret.adoc | 2 +- modules/savanna/modules/get-started/nav.adoc | 1 + .../get-started/pages/connect-agent-mcp.adoc | 2 +- .../pages/connect-pytigergraph.adoc | 126 ++++++++++++++++++ .../get-started/pages/first-graph-ui.adoc | 1 + .../graph-development/pages/index.adoc | 4 +- .../savanna/modules/overview/pages/index.adoc | 10 +- .../modules/overview/pages/release-notes.adoc | 2 +- .../rest-api/pages/data-plane-apis.adoc | 1 + .../pages/workspaces/connect-via-api.adoc | 3 +- 10 files changed, 144 insertions(+), 8 deletions(-) create mode 100644 modules/savanna/modules/get-started/pages/connect-pytigergraph.adoc diff --git a/modules/savanna/modules/administration/pages/settings/how2-create-database-secret.adoc b/modules/savanna/modules/administration/pages/settings/how2-create-database-secret.adoc index 3055a810..78c1d865 100644 --- a/modules/savanna/modules/administration/pages/settings/how2-create-database-secret.adoc +++ b/modules/savanna/modules/administration/pages/settings/how2-create-database-secret.adoc @@ -20,7 +20,7 @@ video::Savanna_Database_Secrets.mp4[] Use the generated secret to authenticate tools and integrations that connect to your TigerGraph database, including: -* pyTigerGraph +* xref:savanna:get-started:connect-pytigergraph.adoc[pyTigerGraph] * TigerGraph MCP. See xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP], where the secret is passed as `TG_SECRET`. * GraphRAG diff --git a/modules/savanna/modules/get-started/nav.adoc b/modules/savanna/modules/get-started/nav.adoc index ea9fcc20..72649a77 100644 --- a/modules/savanna/modules/get-started/nav.adoc +++ b/modules/savanna/modules/get-started/nav.adoc @@ -1,3 +1,4 @@ * Start here ** xref:first-graph-ui.adoc[Build your graph in Savanna] +** xref:connect-pytigergraph.adoc[Connect with pyTigerGraph] ** xref:connect-agent-mcp.adoc[Connect AI tools with MCP] diff --git a/modules/savanna/modules/get-started/pages/connect-agent-mcp.adoc b/modules/savanna/modules/get-started/pages/connect-agent-mcp.adoc index 53952601..e2b9d5bb 100644 --- a/modules/savanna/modules/get-started/pages/connect-agent-mcp.adoc +++ b/modules/savanna/modules/get-started/pages/connect-agent-mcp.adoc @@ -290,7 +290,7 @@ Cursor / VS Code / Claude Code / Claude Desktop * The AI application launches `tigergraph-mcp` on your machine. * The TigerGraph MCP server exposes TigerGraph operations as MCP tools. * The AI application decides which tools to call based on your request. -* The TigerGraph MCP server uses your configured Savanna connection details to perform the operations. +* The TigerGraph MCP server uses pyTigerGraph and your configured Savanna connection details to perform the operations. See xref:connect-pytigergraph.adoc[Connect with pyTigerGraph]. * Tool results return to the AI application and appear in its response. === Tool behavior diff --git a/modules/savanna/modules/get-started/pages/connect-pytigergraph.adoc b/modules/savanna/modules/get-started/pages/connect-pytigergraph.adoc new file mode 100644 index 00000000..7b7a491d --- /dev/null +++ b/modules/savanna/modules/get-started/pages/connect-pytigergraph.adoc @@ -0,0 +1,126 @@ += Connect with pyTigerGraph +:experimental: + +link:https://www.tigergraph.com/docs/pytigergraph/current/intro/[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 + +* A running Savanna xref:savanna:workgroup-workspace:workspaces/workspace.adoc[workspace] with a graph on it. If you do not have one yet, xref:first-graph-ui.adoc[build a graph in the console] first. +* A database secret for that workspace. See xref:savanna:administration:settings/how2-create-database-secret.adoc[Create a database secret]. +* Python with `pip` on the machine that will run your script. + +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 xref:savanna:rest-api:index.adoc[Savanna REST API]. +If the workgroup uses an IP allowlist, include the machine that runs the script. See xref:savanna:workgroup-workspace:workgroups/how2-config-network-access.adoc[Configure network access]. + +== Install + +[source,bash] +---- +pip install pyTigerGraph +---- + +== Connect + +A Savanna connection needs the workspace URL, the graph name, and a database secret. + +[cols="1,1,2",options="header"] +|=== +|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://.i.tgcloud.io`. + +|`graphname` +|Yes +|The graph this connection uses. Create the graph in xref:savanna:graph-development:design-schema/index.adoc[Design Schema] if you do not have one yet. + +|`gsqlSecret` +|Yes +|A database secret for that workspace. See xref:savanna:administration:settings/how2-create-database-secret.adoc[Create a database secret]. +|=== + +When the host contains `tgcloud`, pyTigerGraph treats the instance as TigerGraph Cloud and sends REST{plus}{plus} and GSQL traffic to port `443`, which is how Savanna publishes the workspace. +Leave `restppPort` and `gsPort` at their defaults. + +[source,python] +---- +from pyTigerGraph import TigerGraphConnection + +conn = TigerGraphConnection( + host="https://.i.tgcloud.io", + graphname="MyGraph", + gsqlSecret="", +) + +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: + +[source,python] +---- +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 xref:savanna:graph-development:gsql-editor/index.adoc[GSQL Editor] first, or from pyTigerGraph with the client's query methods. + +[source,python] +---- +result = conn.runInstalledQuery("my_query", params={"param": "value"}) +print(result) +---- + +Vertices, edges, schema changes, and loading jobs are covered in the link:https://www.tigergraph.com/docs/pytigergraph/current/intro/[pyTigerGraph documentation^]. +The HTTP calls underneath are the workspace xref:savanna:rest-api:data-plane-apis.adoc[data-plane APIs]. + +[CAUTION] +==== +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://.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 xref:savanna:administration:settings/how2-create-database-secret.adoc[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 xref:savanna:workgroup-workspace:workspaces/workspace.adoc[About workspaces] and xref:savanna:workgroup-workspace:workgroups/how2-config-network-access.adoc[Configure network access]. + +== Where to go next + +* xref:connect-agent-mcp.adoc[Connect AI tools with MCP] when you want an agent to use the same database. TigerGraph MCP calls the database through pyTigerGraph. +* xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Connect via APIs] for curl, Python, and JavaScript generated in the console. +* xref:savanna:rest-api:data-plane-apis.adoc[Data-plane APIs] for the REST{plus}{plus} and GSQL endpoints the client calls. +* link:https://www.tigergraph.com/docs/pytigergraph/current/getting-started/connection[Connecting to TigerGraph^] in the pyTigerGraph reference. diff --git a/modules/savanna/modules/get-started/pages/first-graph-ui.adoc b/modules/savanna/modules/get-started/pages/first-graph-ui.adoc index 3145c57d..3d2025d6 100644 --- a/modules/savanna/modules/get-started/pages/first-graph-ui.adoc +++ b/modules/savanna/modules/get-started/pages/first-graph-ui.adoc @@ -69,6 +69,7 @@ If a loading job fails, the mapping is the usual cause: check that the parsed co == Where to go next +* Call the same graph from Python: xref:connect-pytigergraph.adoc[Connect with pyTigerGraph]. * Point an AI agent at the same graph: xref:connect-agent-mcp.adoc[Connect AI tools with MCP]. * Model, load, and query in depth: xref:savanna:graph-development:index.adoc[Build]. * In a hurry, or want a schema drafted for you? xref:savanna:build-ai:index.adoc[Build a graph with AI] infers one from your files, and a xref:savanna:integrations:solutions.adoc[Marketplace solution] ships with schema, data, and queries already in place. diff --git a/modules/savanna/modules/graph-development/pages/index.adoc b/modules/savanna/modules/graph-development/pages/index.adoc index 7fe7a9bb..9df7b229 100644 --- a/modules/savanna/modules/graph-development/pages/index.adoc +++ b/modules/savanna/modules/graph-development/pages/index.adoc @@ -2,10 +2,10 @@ :experimental: Model, load, query, and explore graphs on Savanna. -New here? Start with xref:savanna:get-started:first-graph-ui.adoc[Build your graph in Savanna], or xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] once you have a graph. +New here? Start with xref:savanna:get-started:first-graph-ui.adoc[Build your graph in Savanna], xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph], or xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] once you have a graph. Or use xref:savanna:build-ai:index.adoc[Build a graph with AI] as a console shortcut. -This hub links the core Build workflows. Use xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Connect via APIs] or xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] when you are ready to call the same graph from code or an agent. +This hub links the core Build workflows. Use xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph], xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Connect via APIs], or xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] when you are ready to call the same graph from code or an agent. == xref:load-data/index.adoc[Load Data] diff --git a/modules/savanna/modules/overview/pages/index.adoc b/modules/savanna/modules/overview/pages/index.adoc index a281e0ae..f0f9e440 100644 --- a/modules/savanna/modules/overview/pages/index.adoc +++ b/modules/savanna/modules/overview/pages/index.adoc @@ -10,17 +10,21 @@ Storage and compute are separate, so each scales on its own and you pay for the See xref:savanna:overview:comparison_table.adoc[how the offerings compare]. Every path below gets you to a graph you can query. -Choose how you want to work. Build and manage your graph in Savanna, or connect AI tools with MCP and work with it using natural language. +Choose how you want to work. Build and manage your graph in Savanna, connect from Python with pyTigerGraph, or connect AI tools with MCP and work in natural language. == Get started -[.start-cards,cols="2",grid=none,frame=none, separator=¦] +[.start-cards,cols="3",grid=none,frame=none, separator=¦] |=== ¦ xref:savanna:get-started:first-graph-ui.adoc[Build your graph in Savanna] Create and manage graphs, define and edit schemas, load data, and run GSQL queries directly in Savanna. ¦ +xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph] + +Call your Savanna workspace from Python to run queries and work with graph data. +¦ xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] Use natural language in Cursor, VS Code, Claude Code, or Claude Desktop to create and manage graphs, edit schemas, load data, and run GSQL queries in Savanna. @@ -33,12 +37,14 @@ Start with the core graph workflow. Model your domain, load data, query it, and * xref:savanna:graph-development:design-schema/index.adoc[Design a schema] to define the vertices, edges, and attributes that represent your data. * xref:savanna:graph-development:load-data/index.adoc[Load data] from local files or connect to S3, GCS, Azure Blob, Snowflake, JDBC, and other sources. * xref:savanna:graph-development:gsql-editor/index.adoc[Write and run GSQL] to create, install, and run graph queries in a live workspace. +* xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph] to call the workspace from Python with a database secret. * xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Query the graph from code] with generated curl, Python, or JavaScript examples for the graph data plane. * xref:savanna:rest-api:index.adoc[Manage Savanna through the REST API] to provision workgroups, workspaces, and organization resources. == Where to go next * xref:savanna:graph-development:index.adoc[Build] covers schemas, loading data, writing GSQL, and exploring graph results. +* xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph] when your application calls the database from Python. * xref:savanna:get-started:connect-agent-mcp.adoc[Connect AI tools with MCP] when you want an AI agent to work against your database. * xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Connect via APIs] for generated curl, Python, or JavaScript against the graph data plane. * xref:savanna:workgroup-workspace:index.adoc[Workgroups and workspaces] handles workgroups, workspaces, access, networking, and routine administration. diff --git a/modules/savanna/modules/overview/pages/release-notes.adoc b/modules/savanna/modules/overview/pages/release-notes.adoc index f234daa5..e85a02df 100644 --- a/modules/savanna/modules/overview/pages/release-notes.adoc +++ b/modules/savanna/modules/overview/pages/release-notes.adoc @@ -14,7 +14,7 @@ You can now create database secrets in Savanna and use them to connect pyTigerGr Until now you had to leave Savanna, open Admin Portal, and create a database username and password, which was confusing and hard to set up. Create the secret in Savanna and paste it into the client instead. That keeps credential setup in one place, so you spend less time bouncing between products and fewer connections fail because of a mismatched username or password. -See xref:savanna:administration:settings/how2-create-database-secret.adoc[Create a database secret]. +See xref:savanna:administration:settings/how2-create-database-secret.adoc[Create a database secret] and xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph]. === Improvements and bug fixes diff --git a/modules/savanna/modules/rest-api/pages/data-plane-apis.adoc b/modules/savanna/modules/rest-api/pages/data-plane-apis.adoc index 901d8a2f..d49d7242 100644 --- a/modules/savanna/modules/rest-api/pages/data-plane-apis.adoc +++ b/modules/savanna/modules/rest-api/pages/data-plane-apis.adoc @@ -94,6 +94,7 @@ Savanna does not duplicate the data-plane endpoint catalog. You can find the ful == Related topics +* xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph]. Call these endpoints from Python with a database secret. * xref:savanna:workgroup-workspace:workspaces/connect-via-api.adoc[Connect via APIs]. Generated curl, Python, and JavaScript from the Savanna console. * xref:savanna:administration:settings/how2-create-database-secret.adoc[Create a database secret]. The credential the data plane uses. * xref:savanna:rest-api:index.adoc[Savanna REST API]. The control-plane API for managing workspaces. diff --git a/modules/savanna/modules/workgroup-workspace/pages/workspaces/connect-via-api.adoc b/modules/savanna/modules/workgroup-workspace/pages/workspaces/connect-via-api.adoc index a163fb87..a516ae6b 100644 --- a/modules/savanna/modules/workgroup-workspace/pages/workspaces/connect-via-api.adoc +++ b/modules/savanna/modules/workgroup-workspace/pages/workspaces/connect-via-api.adoc @@ -62,7 +62,8 @@ These code snippets provide ready-to-use code examples that you can integrate in === Connect via APIs Limitations The current btn:[Connect from API] code generated by TigerGraph Savanna does not support the database secret. -If you need to connect using the database secret, please refer to https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/user-credentials/#_required_privilege[Required Privilege^]. +To connect from Python with a database secret, see xref:savanna:get-started:connect-pytigergraph.adoc[Connect with pyTigerGraph]. +For how secrets map to privileges, see https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/user-credentials/#_required_privilege[Required Privilege^]. == Next Steps