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, connecting to your cloud instance, creating your first graph, and running Cypher queries.

​
🐍 1. Install the SDK

​
Option A: Using pip

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

​
Option B: Using uv (modern package manager)

Requires an initialized Python project 
mkdir my_app
cd my_app
uv init --app
uv add turingdb

​
🔐 2. Connect to Your TuringDB Instance

To interact with TuringDB, you’ll need:
  • ✅ Your Instance ID
  • 🔑 Your API Token
These are found in your TuringDB Cloud UI. See Authentication Guide 
from turingdb import TuringDB

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

​
🧬 3. Create a Graph:

Create a 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.query("CHANGE NEW")["Change ID"][0]

# 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()

​
🔍 5. Query the Graph

Retrieve data using Cypher MATCH queries. Results are returned as a pandas DataFrame for easy inspection: 
# Basic match query
df = client.query("MATCH (n:Person) RETURN n.name, n.age")
print(df)

# Find nodes with name similar to 'alice'
df = client.query('MATCH (n{name~="marie"}) RETURN n')

​
📦 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

​
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


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

client.create_graph("people")
client.load_graph("people")
client.set_graph("people")

client.query('CREATE (:Person {name="Marie", age=33})')
client.query('CREATE (:Person {name="Jane"})-[:FRIEND_OF]-(:Person {name="John"})')

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

​
🛠 What’s Next?

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