Skip to main content

​
QuickStart: TuringDB Python SDK

This guide walks you through the essentials of getting started with the turingdb Python SDK: installing the SDK, creating your first graph, and running Cypher queries.

​
1. Install the SDK

​
Option A: Using uv (modern package manager)

mkdir my_app
cd my_app
uv init
uv add turingdb

​
Option B: Using pip

python3 -m venv .venv
source .venv/bin/activate
pip install turingdb

​
2. Create a Graph:

Create a graph and set active graph: 
# Create a new graph
client.create_graph("my_first_graph")

# Set the active graph context
client.set_graph("my_first_graph")

​
3. Create Nodes & Edges

First of all, create a new change on the graph 
# Create a new change on the graph
change = client.new_change()

# Checkout into the change
client.checkout(change=change)
Use Cypher CREATE queries to add data: 
# Create a node
client.query("CREATE (:Person {name: 'Marie', age: 33})")

# Create two nodes and an edge
client.query("CREATE (:Person {name: 'Jane'})-[:KNOWS]->(:Person {name: 'John'})")
⚠️ All created entities must have at least one label (:Label)
Once you’re ready, commit and submit your changes: 
# Commit and submit the change
client.query("COMMIT")
client.query("CHANGE SUBMIT")

# Get back to the main branch
client.checkout()
You can create as many commits as you want before submitting a change

​
4. Query the Graph

Retrieve data using Cypher MATCH queries. Results are returned as a pandas DataFrame for easy inspection: 
# Match all nodes of label 'Person'
# and return their name and age
df = client.query("MATCH (n:Person) RETURN n.name, n.age")
print(df)

​
5. Version Control & Snapshots

TuringDB supports versioned graphs and snapshot isolation.

​
Create a new change (branch):

client.checkout(change=1)  # Move to change ID 1

# or use

change = client.new_change()
client.checkout(change=change)

​
Query a specific commit:

client.checkout(change=1, commit="abc123")

​
Go back to main branch:

client.checkout("main")

# or simply

client.checkout()

​
Example: Full Session

from turingdb import TuringDB

# Create TuringDB client
# Connect to a locally running TuringDB server (default host shown):
client = TuringDB(host="http://localhost:6666")

# Or run the engine in-process, with no server:
# client = TuringDB(type="embedded", data_dir="~/.turing")

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

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

# Create nodes and edges
client.query("CREATE (:Person {name: 'Marie', age:33})")
client.query("CREATE (:Person {name: 'Jane'})-[:FRIEND_OF]->(:Person {name: 'John'})")

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

# Query graph
df = client.query("MATCH (p:Person) RETURN p.name")
print(df)

​
🛠 What’s Next?

Questions or feedback? → Join the Discord or open an issue