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 uv package manager (you will need to create a project first): 
uv add turingdb
or using pip: 
pip install turingdb

​
Getting Started

from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host=<local_URL>,  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id=<your_instance_ID>,  # found on the Database Instances management page
#    auth_token=<your_auth_token>  # your authentification token
#)

# List available graphs
print(client.list_available_graphs())

​
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

from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host=<local_URL>,  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id=<your_instance_ID>,  # found on the Database Instances management page
#    auth_token=<your_auth_token>  # your authentification token
#)

# Create and set working graph
client.create_graph("biograph")
client.set_graph("biograph")

# Create and set new change
change = client.new_change()
print(f"Change: {change}")
client.checkout(change=change)

# Multiple nodes and edges can be created at the same time
# using the following syntax
client.query("""CREATE (apoe_gene:Gene {name: 'APOE', chromosome: '19', location: '19q13.32'}),
(apoe_protein:Protein {name: 'Apolipoprotein E', function: 'Lipid_transport', tissue: 'Brain_and_liver'}),
(alzheimers:Disease {name: 'Alzheimers_Disease', type: 'Neurodegenerative'}),
(cholesterol:Molecule {name: 'Cholesterol', type: 'Lipid'}),
(apoe_gene)-[:ENCODES]->(apoe_protein),
(apoe_protein)-[:BINDS]->(cholesterol),
(apoe_protein)-[:ASSOCIATED_WITH]->(alzheimers)
""")

# Commit the change
client.query("COMMIT")
client.query("CHANGE SUBMIT")

# Checkout into main
client.checkout()

# Query graph
df = client.query("MATCH (n:Gene {name: 'APOE'}) RETURN n.name, n.chromosome")
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