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 turingdbOption B: Using pip
python3 -m venv .venv
source .venv/bin/activate
pip install turingdb2. 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?
- 📘 Learn the Query Language
- 🔀 Explore Versioning & Changes
- 🔎 Try Vector Search
Questions or feedback? → Join the Discord or open an issue