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. Connect
Start a server with turingdb -demon (see CLI commands), then connect to it:
from turingdb import TuringDB
# Connect to the server running on localhost:6666
client = TuringDB(host="localhost", port=6666)The client connects right away, and raises Failed to connect to localhost:6666: Connection refused if no server is running. To run the engine inside your Python process instead, with no server, use TuringDB(type="embedded", data_dir="/home/me/.turing") (see client backends).
3. 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")4. 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'})"
)
# Pass values as parameters: no quoting or escaping needed
client.query(
"CREATE (:Person {name: $name, age: $age})",
{"name": "O'Brien", "age": 41},
)⚠️ 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
5. 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)6. 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
# Connect to the TuringDB server (default: localhost:6666)
client = TuringDB(host="localhost", port=6666)
# Or run the engine in-process, with no server
# (use an absolute path for data_dir):
# client = TuringDB(type="embedded", data_dir="/home/me/.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
- 🌐 Query TuringDB from JavaScript or TypeScript with the JavaScript SDK
Questions or feedback? → Join the Discord or open an issue