Skip to main content

​
🐍 TuringDB Python SDK

The TuringDB Python SDK provides an easy interface for connecting to your TuringDB Cloud instance, running queries, and managing graphs programmatically.
📦 Install the PythonSDK:
Using pip: 
pip install turingdb
or using the uv package manager (you will need to create a project first): 
uv add turingdb

​
🚀 Getting Started

from turingdb import TuringDB

client = TuringDB(
    instance_id="your-instance-id",
    auth_token="your-api-token"
)

# List available graphs
print(client.list_available_graphs())
🛑 Need help with tokens or IDs? See Authentication Guide

​
🔐 Initialization

client = TuringDB(
    instance_id: str,       # Your unique instance ID (from cloud UI)
    auth_token: str,        # Your API token (from Settings > API Keys)
    host: str = "...",      # Optional custom host URL (default for TuringDB Instance is prefilled)
)
  • Uses secure HTTPX client
  • Auth headers are set automatically
  • API gateway refreshes every 60s — wait after creating a token or instance

​
🧭 Core Methods

​
list_available_graphs() → list[str]

Returns all graphs you have access to on the TuringDB Cloud backend. 
client.list_available_graphs()

​
list_loaded_graphs() → list[str]

Returns the currently loaded graphs in memory. 
client.list_loaded_graphs()

​
create_graph(graph_name: str)

Creates a new empty graph with the specified name. 
client.create_graph("my_new_graph")
Internally executes CREATE GRAPH “graph_name”

​
load_graph(graph_name: str, raise_if_loaded: bool = True)

Loads a previously created graph into memory. 
client.load_graph("my_graph")
If raise_if_loaded=False, it will silently continue if the graph is already loaded.

​
query(query: str) → pandas.DataFrame

Runs a Cypher query on the current graph. 
df = client.query("MATCH (n:Person) RETURN n.name, n.age")
Returns results as a pandas.DataFrame, with automatic typing and parsing.

​
🧬 Version Control Helpers

TuringDB supports snapshot isolation and versioned commits. Use the following helpers to navigate graph history or work in isolated changes:

​
checkout(change: int | str = "main", commit: str = "HEAD")

Switches the working context to a specific change or commit. 
client.checkout(change=2, commit="abc123")
client.checkout("main")  # Reset to default
  • change: change ID or "main"
  • commit: commit hash or "HEAD"

​
set_commit(commit: str)

Manually set the commit hash to use. 
client.set_commit("haax42")

​
set_change(change: int | str)

Manually set the change ID to use (accepts int or hex string). 
client.set_change(3)

​
set_graph(graph_name: str)

Change the current graph context. 
client.set_graph("another_graph")

​
📄 Response Format

All queries return a pandas.DataFrame, typed according to schema:
Cypher TypePython (NumPy)
Stringstr
Int64int64
UInt64uint64
Doublefloat64
Booleanbool

​
⚠️ Error Handling

All SDK errors raise a custom TuringDBException. 
try:
    client.query("MATCH (x) RETURN x")
except TuringDBException as e:
    print("Query failed:", e)

​
🧪 Example Workflow

client = TuringDB(instance_id="...", auth_token="...")

client.create_graph("biograph")
client.load_graph("biograph")

client.set_graph("biograph")

client.checkout(change=1)

df = client.query("MATCH (n:Protein{name~='apoe'}) RETURN n.name, n.id")
print(df)

​
🧠 Notes

  • The SDK uses httpx for async-compatible HTTP requests
  • Responses are parsed using orjson and converted into pandas.DataFrame for easy usage
  • Only graph name, change ID, and commit hash are sent with requests
  • SDK supports full TuringDB Cypher dialect, including @ node injection, ~= matching, and versioned queries
Need help writing queries? → See the TuringDB Query Cheatsheet You can also find the TuringDB PythonSDK in Github