> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turingdb.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> References for TuringDB Python SDK

# TuringDB Python SDK

The TuringDB Python SDK provides an easy interface for connecting to your local TuringDB server, running queries, and managing graphs programmatically.

> Install the PythonSDK:

Using `uv`  package manager (you will need to create a project first):

```bash theme={null}
uv add turingdb
```

or using `pip`:

```bash theme={null}
pip install turingdb
```

## Getting Started

```python theme={null}
from turingdb import TuringDB

# Create TuringDB client
# set host parameter to the URL (as string) on which TuringDB is running,
# default "http://localhost:6666"
client = TuringDB(host="http://localhost:6666")

# 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.

```python theme={null}
client.list_available_graphs()
```

### `list_loaded_graphs() → list[str]`

Returns the currently loaded graphs in memory.

```python theme={null}
client.list_loaded_graphs()
```

### `create_graph(graph_name: str)`

Creates a new empty graph with the specified name.

```python theme={null}
client.create_graph("mygraph")
```

> Internally executes `CREATE GRAPH "graph_name"`

### `load_graph(graph_name: str, raise_if_loaded: bool = True)`

Loads a previously created graph into memory.

```python theme={null}
client.load_graph("mygraph")
```

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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
client.set_commit("haax42")
```

### `set_change(change: int | str)`

Manually set the change ID to use (accepts int or hex string).

```python theme={null}
client.set_change(3)
```

### `set_graph(graph_name: str)`

Change the current graph context.

```python theme={null}
client.set_graph("another_graph")
```

## Response Format

All queries return a `pandas.DataFrame`, typed according to schema:

| Cypher Type | Python (NumPy) |
| ----------- | -------------- |
| `String`    | `str`          |
| `Int64`     | `int64`        |
| `UInt64`    | `uint64`       |
| `Double`    | `float64`      |
| `Boolean`   | `bool`         |

## Error Handling

All SDK errors raise a custom `TuringDBException`.

```python theme={null}
try:
    client.query("MATCH (x) RETURN x")
except TuringDBException as e:
    print("Query failed:", e)
```

## Example Workflow

```python theme={null}
from turingdb import TuringDB

# Create TuringDB client
# set host parameter to the URL (as string) on which TuringDB is running,
# default "http://localhost:6666"
client = TuringDB(host="http://localhost:6666")

# Create a new graph called mygraph
client.create_graph("mygraph")

# Set working graph
client.set_graph("mygraph")

# Create a new change on the graph
change = client.new_change()

# Checkout into the 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](/query/cheatsheet)

You can also find the TuringDB PythonSDK in [Github](https://github.com/turing-db/turingdb-sdk-python)