TuringDB

https://docs.turingdb.ai
Admin
TuringDB is the fastest graph database engine for analytical, AI-driven, and read-intensive...
Tokens:30,542
Snippets:243
Trust Score:4.6
Update:9 months ago
Show doc for...
Tokens:
Raw
### Full Session Example with TuringDB Python SDK

Source: https://docs.turingdb.ai/pythonsdk/get_started

A comprehensive example showcasing a typical workflow with the TuringDB Python SDK. It covers client initialization (local and cloud), graph creation, change management, data insertion, querying, and committing changes.

```python
from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host=<local_URL>,  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id=<your_instance_ID>,  # found on the Database Instances management page
#    auth_token=<your_auth_token>  # your authentification token
#)

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

--------------------------------

### Start Jupyter Lab Server

Source: https://docs.turingdb.ai/tutorials/example_notebooks

Starts the Jupyter Lab server using the 'uv' package manager. This command launches the interactive development environment where you can run and explore the TuringDB example notebooks.

```bash
uv run jupyter lab
```

--------------------------------

### Getting Started with TuringDB Python SDK

Source: https://docs.turingdb.ai/pythonsdk/reference

Basic setup and usage of the TuringDB Python SDK, including client initialization and listing available graphs.

```APIDOC
## Getting Started

### Description
Initialize the TuringDB client and perform basic operations like listing available graphs.

### Client Initialization

#### Local Instance
```python
from turingdb import TuringDB

client = TuringDB(
	host="<local_URL>",  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
```

#### Cloud Instance
```python
#client = TuringDB(
#	instance_id="<your_instance_ID>",  # found on the Database Instances management page
#    auth_token="<your_auth_token>"  # your authentification token
#)
```

### Listing Available Graphs
```python
print(client.list_available_graphs())
```
```

--------------------------------

### Install Dependencies with uv

Source: https://docs.turingdb.ai/tutorials/example_notebooks

Installs project dependencies using the 'uv' package manager. This command ensures that all necessary libraries for running the TuringDB examples, including Python packages, are correctly installed.

```bash
uv sync
```

--------------------------------

### Install TuringDB Python SDK using uv

Source: https://docs.turingdb.ai/pythonsdk/get_started

Installs the TuringDB Python SDK using the `uv` package manager. This involves creating a new application directory, initializing `uv`, and adding the `turingdb` package.

```bash
mkdir my_app
cd my_app
uv init
uv add turingdb
```

--------------------------------

### Install TuringDB Python SDK using pip

Source: https://docs.turingdb.ai/pythonsdk/get_started

Installs the TuringDB Python SDK using `pip`. This process includes creating a virtual environment, activating it, and then installing the `turingdb` package.

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

--------------------------------

### TuringDB Example MATCH Queries

Source: https://docs.turingdb.ai/query/cypher_subset

Presents several syntactically valid TuringDB MATCH queries showcasing different combinations of labels, properties, and return clauses. These examples highlight the flexibility of the query language.

```sql
MATCH (n:Person) return n.name
```

```sql
MATCH (:Person)—(n:Person) return n.age
```

```sql
MATCH (n:Person,Woman,SoftwareEngineer)—(m)-[e]-(p:Man)-[f]-(q) return e,f
```

--------------------------------

### Clone TuringDB Examples Repository

Source: https://docs.turingdb.ai/tutorials/example_notebooks

Clones the TuringDB examples repository from GitHub. This is the first step in setting up the environment to run the provided examples, including the healthcare knowledge graph notebook.

```bash
git clone https://github.com/turing-db/turingdb-examples.git
cd turingdb-examples
```

--------------------------------

### TuringDB Node and Edge Syntax Examples

Source: https://docs.turingdb.ai/query/cypher_subset

Demonstrates the basic syntax for defining nodes and edges with labels and properties in TuringDB's query language. This syntax is fundamental for constructing all queries.

```sql
(n:Person,Man{name="John", age=20})
```

--------------------------------

### Example Workflow

Source: https://docs.turingdb.ai/pythonsdk/reference

A comprehensive example demonstrating a typical workflow including graph creation, data insertion, committing changes, and querying.

```APIDOC
## Example Workflow

### Description
This example demonstrates a full workflow: initializing the client, creating a graph, creating a new change, adding data using a Cypher query, committing the change, and then querying the data.

### Steps

1.  **Initialize Client:** Connect to your TuringDB instance.
2.  **Create and Set Graph:** Create a new graph named `biograph` and set it as the current working graph.
3.  **Create New Change:** Initiate a new versioned change.
4.  **Add Data:** Execute a Cypher query to create nodes and relationships.
5.  **Commit Change:** Commit the staged changes.
6.  **Submit Change:** Submit the committed change for the version history.
7.  **Checkout Main:** Switch back to the main branch.
8.  **Query Data:** Execute a query to retrieve specific data.

### Code Example

```python
from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host="<local_URL>",  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id="<your_instance_ID>",  # found on the Database Instances management page
#    auth_token="<your_auth_token>"  # your authentification token
#)

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

# Create and set new change
change = client.new_change()
print(f"Change: {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)
```
```

--------------------------------

### Example Workflow: Create, Modify, and Query Graph in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/reference

A comprehensive example demonstrating the typical workflow: initializing the client, creating a new graph, setting it as the active graph, creating a new change, adding data using Cypher, committing the change, and querying the data. This also shows how to checkout back to the main branch.

```python
from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host=<local_URL>,  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id=<your_instance_ID>,  # found on the Database Instances management page
#    auth_token=<your_auth_token>  # your authentification token
#)

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

# Create and set new change
change = client.new_change()
print(f"Change: {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)
```

--------------------------------

### TuringDB Python SDK Installation

Source: https://docs.turingdb.ai/pythonsdk/reference

Instructions on how to install the TuringDB Python SDK using pip or uv.

```APIDOC
## TuringDB Python SDK Installation

### Description
Install the TuringDB Python SDK using your preferred package manager.

### Installation Methods

#### Using `uv`
```bash
uv add turingdb
```

#### Using `pip`
```bash
pip install turingdb
```
```

--------------------------------

### Manage changes and commits in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Demonstrates how to manage version control within TuringDB. This includes checking out specific changes by ID, checking out specific commits by hash, and returning to the main branch.

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

# or use

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

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

client.checkout("main")

# or simply

client.checkout()
```

--------------------------------

### Install TuringDB Python SDK

Source: https://docs.turingdb.ai/pythonsdk/reference

Instructions for installing the TuringDB Python SDK using either the 'uv' package manager or 'pip'. Ensure you have a project set up before using 'uv'.

```bash
uv add turingdb
```

```bash
pip install turingdb
```

--------------------------------

### Create nodes and edges using Cypher in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Adds data to the TuringDB graph using Cypher `CREATE` statements. This example shows how to create a single node and how to create multiple nodes connected by an edge. Note that entities require at least one label.

```python
# 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'})")
```

--------------------------------

### MATCH and CREATE Queries with Exact and Approximate Operators

Source: https://docs.turingdb.ai/query/cypher_subset

Provides examples of using both exact matching operators (`:` and `=`) and the approximate string operator (`~=`) in TuringDB queries. Both `:` and `=` function identically for exact matches.

```jsx
MATCH (n{name="Matt", age:20, hasPhD=false}) RETURN n

```

```jsx
MATCH (n{name:"Matt", age=20, hasPhD:false}) RETURN n

```

--------------------------------

### Create Graph using cURL

Source: https://docs.turingdb.ai/graph_dev/create_graph

This example shows how to create a graph named 'my_graph' using a cURL command. It involves sending a POST request to the TuringDB SDK endpoint with appropriate authentication headers (API key and Instance ID) and the 'CREATE GRAPH' query in the request body. An example JSON response is also provided.

```bash
# Create a new graph called my_graph
curl "https://engines.turingdb.ai/sdk/query" \
     -H "Authorization: Bearer $MY_API_KEY" \
     -H "Turing-Instance-Id: $MY_INSTANCE_ID" \
     -H "Accept: application/json" \
     -d "CREATE GRAPH my_graph"
```

```json
{
  "header": {"column_names": [],"column_types": []},
  "data": [],
  "time": 0.873002
}
```

--------------------------------

### Create and set active graph in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Demonstrates how to create a new graph and set it as the active graph context using the TuringDB Python client. This is a prerequisite for performing operations within a specific graph.

```python
# Create a new graph
client.create_graph("my_first_graph")

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

--------------------------------

### Install networkx for GML Parsing

Source: https://docs.turingdb.ai/tutorials/create_graph

Installs the `networkx` library required for parsing GML files. This library is essential for reading and processing the graph structure from GML format before converting it into TuringDB compatible queries.

```bash
pip install networkx
# or
uv add networkx
```

--------------------------------

### Create a new change and checkout in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Initializes a new change (similar to a branch) on the graph and checks it out for subsequent modifications. This is part of TuringDB's version control system.

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

# Checkout into the change
client.checkout(change=change)
```

--------------------------------

### CREATE Queries

Source: https://docs.turingdb.ai/query/cypher_subset

Learn how to create nodes and edges in TuringDB, including property and label constraints, and the requirement for at least one label per node/edge.

```APIDOC
## CREATE Queries

### Description
`CREATE` queries are used to insert new nodes and edges into the TuringDB graph. They share syntax similarities with `MATCH` queries for specifying nodes, edges, and constraints, but lack a `RETURN` clause. A key requirement is that all nodes and edges must possess at least one label.

### Method
`CREATE`

### Endpoint
N/A (This is a query language statement, not a REST endpoint)

### Parameters
No specific parameters for the `CREATE` statement itself, but it defines nodes, edges, and their properties/labels within the query.

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (The structure is defined within the query language)

### Request Example
```sql
CREATE (n:Person {name: "Alice", age: 30})
CREATE (a:Person)-[:FRIENDS_WITH]->(b:Person)
CREATE (c:Company {name: "TechCorp"})
CREATE (a)-[:WORKS_FOR {role: "Developer"}]->(c)
```

### Response
`CREATE` queries do not return data directly. Their success is indicated by the absence of errors. The impact is a modification of the graph's state.

#### Success Response
No explicit success response body. A successful execution means the data has been added to the graph.

#### Response Example
None

### Notes
- All nodes and edges must have at least one label (e.g., `CREATE (n:Person)` is valid, `CREATE (n)` is not).
- Variables for nodes/edges are optional but can be useful for complex creations or multiple edge relationships.
- String properties can be enclosed in double quotes (`"`), single quotes (`'`), or backticks (`` ` ``).
```

--------------------------------

### Install TuringDB using pip or uv

Source: https://docs.turingdb.ai/quickstart

Installs the TuringDB package using either the pip package manager or the uv package manager. pip is a general-purpose package installer for Python, while uv is a faster alternative. Ensure Python is installed for pip.

```bash
pip install turingdb
```

```bash
uv add turingdb
```

--------------------------------

### Basic CREATE Query Syntax

Source: https://docs.turingdb.ai/query/cypher_subset

Demonstrates the fundamental syntax for CREATE queries in TuringDB. Unlike MATCH queries, CREATE queries do not have RETURN clauses and require all nodes and edges to have at least one label.

```jsx
CREATE (n)

```

```jsx
CREATE (n:Person)

```

--------------------------------

### Example 1-Hop Cypher Query

Source: https://docs.turingdb.ai/query/benchmarks

A simple Cypher query to find direct successors of a node named 'Autophagy'. This demonstrates a basic graph traversal operation.

```jsx
match (n{displayName:"Autophagy"})-->(m) return id(m)
```

--------------------------------

### Create and Query Graph in Python

Source: https://docs.turingdb.ai/graph_dev/graph_examples

Demonstrates how to connect to TuringDB, create a new graph change, add nodes and edges, submit the change, and query the main graph to validate the additions. This involves using the `TuringDB` client and its `query` and `checkout` methods.

```python
from turingdb import TuringDB

# Connect to your TuringDB instance
client = TuringDB()

# Set the graph you want to work with
graph_name = "graph_name"
client.set_graph(graph_name)

# 1. Create a new change
change_response = client.query("CHANGE NEW")

# Extract the change ID (in hex format)
change_id = change_response.iloc[0, 0]
print(f"Created change ID: {change_id}")

# 2. Checkout to the new change
client.checkout(change=change_id)

# 3. Submit a query to that change
client.query('CREATE (n:Person {Name:"Jane"})-[e:knows]-(m:Person {Name:"John"})')

# 4. Submit the change to the main graph
client.query("CHANGE SUBMIT")

# 5. Query the main branch to validate
client.checkout("main")  # back to HEAD
df = client.query('MATCH (n:Person {Name:"Jane"})-[e:knows]-(m:Person {Name:"John"}) RETURN n, e, m')
print(df)
```

--------------------------------

### CREATE Queries with Multiple Edges and Named Variables

Source: https://docs.turingdb.ai/query/cypher_subset

Illustrates how to create multiple edges and utilize named variables within CREATE queries to define complex relationships, such as creating a triangle pattern.

```sql
CREATE (:Person)-[:FriendsWith]-(:Person)

```

```sql
CREATE (a:Corner)-[:Edge]-(b:Corner), (b)-[:Edge]-(c:Corner), (c)-[:Edge]-(a)

```

--------------------------------

### Transport: Check 1-Hop Path on Specific Line (Cypher)

Source: https://docs.turingdb.ai/tutorials/example_notebooks

This query checks for a direct connection (1 hop) between two specific London transport stations using a particular line. It verifies if a direct route exists and returns the start station, line, and end station names. Useful for analyzing direct connectivity on specific routes.

```cypher
MATCH (start {displayName: 'Notting Hill Gate'})-[e:CONNECTED {Line: 'Circle'}]->
      (end {displayName: 'High Street Kensington'})
RETURN start.displayName, e.Line, end.displayName
```

--------------------------------

### Metaquery to List All Properties

Source: https://docs.turingdb.ai/query/cypher_subset

Shows the syntax for the `CALL PROPERTIES ()` metaquery, which returns a list of all node and edge properties along with their respective data types present in the TuringDB database.

```sql
CALL PROPERTIES ()

```

--------------------------------

### Metaquery to List Label Combinations

Source: https://docs.turingdb.ai/query/cypher_subset

Explains the `CALL LABELSETS ()` metaquery, which returns information about combinations of node labels present in the database, presented in two columns.

```sql
CALL LABELSETS ()

```

--------------------------------

### Metaquery to List All Labels

Source: https://docs.turingdb.ai/query/cypher_subset

Demonstrates the `CALL LABELS ()` metaquery, used to retrieve a list of all unique node labels defined within the TuringDB graph.

```sql
CALL LABELS ()

```

--------------------------------

### Data Types and Property Constraints

Source: https://docs.turingdb.ai/query/cypher_subset

Understand the supported data types for node and edge properties in TuringDB and how to specify them, including unsigned integers.

```APIDOC
## Data Types and Property Constraints

### Description
TuringDB supports a set of data types for properties associated with nodes and edges. Understanding these types is crucial for accurate data storage and retrieval. Special handling is available for unsigned integers.

### Supported Data Types
*   String
*   Boolean
*   Integer (signed)
*   Unsigned integer
*   Double (decimal)

### Usage
By default, whole-number numeric values are stored as signed integers. To explicitly use an unsigned integer, append the `u` suffix to the numeric value.

### Example
```sql
CREATE (n:User {id: 123, score: 95u, isActive: true, rating: 4.5, description: "A sample user"})
```

### Type Coercion
- `MATCH` queries automatically coerce integers to unsigned integers. A query like `MATCH (n{age=20})` will match a node created with `age=20u`.
- The reverse coercion (unsigned to signed) is not supported. Querying with an unsigned value (`u` suffix) will specifically look for unsigned integer properties.
- Mismatched property types between `CREATE` and `MATCH` queries (outside of the documented integer/unsigned integer coercion) will result in query failure.

### String Delimiters
String properties can be enclosed using double quotes (`"`), single quotes (`'`), or backticks (`` ` ``).
```

--------------------------------

### TuringDB MATCH Query with RETURN *

Source: https://docs.turingdb.ai/query/cypher_subset

Demonstrates the use of the '*' operator in the RETURN clause of a TuringDB MATCH query. 'RETURN *' is a shorthand to return all entities (nodes and edges) involved in the MATCH pattern.

```sql
MATCH (n:Person)-[e]-(m) RETURN *
```

--------------------------------

### MATCH Query for Unsigned Integer Coercion

Source: https://docs.turingdb.ai/query/cypher_subset

Demonstrates how a MATCH query can automatically coerce an integer to an unsigned integer when querying properties. This query will match the node created with `age=20u`.

```jsx
MATCH (n{age=20}) return n.name

```

--------------------------------

### Crypto: Find 4-Hop Transaction Chains (Cypher)

Source: https://docs.turingdb.ai/tutorials/example_notebooks

This query explores cryptocurrency transaction data to find chains of four hops between entities (e.g., wallets, exchanges). It's designed to uncover complex fund flows and layered structures potentially used for illicit activities. Returns the entities involved in the chain.

```cypher
MATCH (a:Entity)-[:TRANSACTION]->(b:Entity)-[:TRANSACTION]->
      (c:Entity)-[:TRANSACTION]->(d:Entity)
RETURN a, b, c, d
```

--------------------------------

### CREATE Query with Explicit Unsigned Integer Property

Source: https://docs.turingdb.ai/query/cypher_subset

Shows how to specify an unsigned integer for a node property using the 'u' suffix in a CREATE query. This ensures the value is stored as an unsigned integer, which can be important for specific data requirements.

```sql
CREATE (n:Person{age=20u, name="Jane"})

```

--------------------------------

### TuringDB: Useful Query Patterns

Source: https://docs.turingdb.ai/query/cheatsheet

Provides common and practical query patterns for graph traversal and data retrieval in TuringDB. Examples include finding two-hop connections, filtering by specific names, and using approximate matching.

```sql
-- Two-hop connection
MATCH (a)-[r1]->(b)-[r2]->(c) RETURN c

-- All people named John
MATCH (n:Person {name: 'John'}) RETURN n

-- All nodes with approx match
MATCH (n {name ~= 'kinase'}) RETURN n
```

--------------------------------

### Finance: Find 2-Hop Transaction Chains (Cypher)

Source: https://docs.turingdb.ai/tutorials/example_notebooks

This Cypher query discovers transaction chains involving three accounts and two intermediate transactions. It helps in identifying multi-step money flows, which can be indicative of more complex fraudulent activities like mule accounts. Returns details of accounts and transactions in the chain.

```cypher
MATCH (a1:Account)-[s1:SENT]->(t1:Transaction)-[r1:RECEIVED]->
      (a2:Account)-[s2:SENT]->(t2:Transaction)-[r2:RECEIVED]->
      (a3:Account)
RETURN a1.id, a2.id, a3.id, t1.id, t1.type, t1.amount, t1.step, t1.is_fraud ,
       t2.id, t2.type, t2.amount, t2.step, t2.is_fraud 
```

--------------------------------

### Supply Chain: Find Nodes with String Approximation (Cypher)

Source: https://docs.turingdb.ai/tutorials/example_notebooks

This Cypher query finds relationships between nodes where the 'description' property approximately matches a given string (e.g., 'FPGA'). It uses fuzzy matching to identify related components or materials in a supply chain. Returns details of the connected nodes and the relationship.

```cypher
MATCH (n{description ~= "FPGA"})-[e]-(m)
RETURN n.displayName, n.description, e, m.displayName, m.description
```

--------------------------------

### Initialize TuringDB Client

Source: https://docs.turingdb.ai/pythonsdk/reference

Demonstrates how to create a TuringDB client instance. Supports connection to both locally running TuringDB instances via a host URL and cloud instances using an instance ID and authentication token.

```python
from turingdb import TuringDB

# Create TuringDB client
## if TuringDB is running locally
client = TuringDB(
	host=<local_URL>,  # URL on which local TuringDB is running, e.g. "http://localhost:6666"
)
### if TuringDB is running on a cloud instance
#client = TuringDB(
#	instance_id=<your_instance_ID>,  # found on the Database Instances management page
#    auth_token=<your_auth_token>  # your authentification token
#)

# List available graphs
print(client.list_available_graphs())
```

--------------------------------

### Approximate string search in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Performs an approximate string search on node properties using the `~=` operator in Cypher. This is useful for finding nodes with similar string values.

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

--------------------------------

### Query nodes and retrieve data as pandas DataFrame in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Retrieves data from the TuringDB graph using Cypher `MATCH` queries. The results are automatically converted into a pandas DataFrame for easy analysis and manipulation.

```python
# 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)
```

--------------------------------

### Commit and submit changes in TuringDB

Source: https://docs.turingdb.ai/pythonsdk/get_started

Commits the current change set and submits it to the graph history. This action makes the changes persistent. You can create multiple commits before submitting. It also shows how to return to the main branch.

```python
# Commit and submit the change
client.query("COMMIT")
client.query("CHANGE SUBMIT")

# Get back to the main branch
client.checkout()
```

--------------------------------

### TuringDB MATCH Query Ignoring Edge Variable

Source: https://docs.turingdb.ai/query/cypher_subset

Provides an example of a MATCH query in TuringDB where the edge variable is omitted. This query returns node 'm' when connected to any node via any edge, useful when edge details are not needed.

```sql
MATCH (n)--(m) RETURN m
```

--------------------------------

### Clone Benchmarking Repository

Source: https://docs.turingdb.ai/query/benchmarks

This command clones the turing-db/turing-bench repository to your local machine. This repository contains the tools and scripts necessary for running the benchmarks.

```bash
git clone <https://github.com/turing-db/turing-bench>
cd turing-bench
```

--------------------------------

### Run TuringDB Benchmark Query

Source: https://docs.turingdb.ai/query/benchmarks

This command runs a benchmark query against TuringDB using the turing-bench executable. It specifies the dataset, query file, number of repetitions, and enables parallel execution.

```bash
cd build/build_package
./turing-bench -l reactome -q samples/reactome/str-prop-multihop.cypher -r 100 -p
```

--------------------------------

### Run Neo4j Benchmark Query

Source: https://docs.turingdb.ai/query/benchmarks

This command executes a specific Cypher query against a Neo4j instance using the turing-bench suite. It specifies the query file and the number of repetitions for the benchmark.

```bash
cd src/neo4j
python3 bench.py -q "samples/reactome/neo4j-str-prop-multihop.cypher" -r 3
```

--------------------------------

### Create and query a graph using TuringDB Python SDK

Source: https://docs.turingdb.ai/quickstart

Demonstrates how to interact with TuringDB using its Python SDK. This includes creating a graph, adding nodes and edges, committing changes, and performing a match query.

```python
from turingdb import TuringDB

client = TuringDB(http://localhost)

# Create a new graph
client.query('CREATE GRAPH mygraph')
client.set_graph('mygraph')

# Create a new change on the graph
change = client.query("CHANGE NEW")["Change ID"][0]

# Checkout into the change
client.checkout(change=change)

# Create a node Person (Jane) - Edge (knows) - node (John)
client.query('CREATE (n:Person {Name:"Jane"})-[e:knows]-(m:Person {Name:"John"})')

# Commit the change
client.query("COMMIT")
client.query("CHANGE SUBMIT")
```

--------------------------------

### Operators for Property Matching

Source: https://docs.turingdb.ai/query/cypher_subset

Details on the operators used for exact and approximate matching of node and edge properties in TuringDB queries.

```APIDOC
## Operators for Property Matching

### Description
TuringDB provides operators to specify conditions for matching nodes and edges based on their properties. Both exact and approximate matching are supported.

### Exact Matching Operators
- The colon (`:`) and equals sign (`=`) operators both perform exact matching of property values.
- They are interchangeable and function identically.

### Example (Exact Match)
```jsx
MATCH (n {name: "Matt", age: 20, hasPhD: false}) RETURN n
MATCH (n {name: 'Matt', age=20, hasPhD:false}) RETURN n
```

### Approximate String Matching Operator
- The `~=` operator is used for approximate string matching. (Specific details on the algorithm or tolerance are not provided in the input text).

### Example (Approximate Match)
```jsx
MATCH (n {name ~= "Jon"}) RETURN n // Example usage, exact behavior needs further definition
```

### Notes
- When querying properties, ensure the data type in the query matches the stored type, or falls within the supported coercion rules (e.g., integer to unsigned integer).
- Using different delimiters for strings (`, `"`, `` ` ``) does not affect the matching outcome as long as the string content is identical.
```

--------------------------------

### Run TuringDB server

Source: https://docs.turingdb.ai/quickstart

Launches the TuringDB server. Can be run interactively in the CLI or as a background daemon process for persistent operation.

```bash
turingdb
```

```bash
turingdb -demon
```

--------------------------------

### Node ID Injection

Source: https://docs.turingdb.ai/query/cypher_subset

Learn how to reference existing nodes in the database using their internal IDs for more precise querying and graph manipulation.

```APIDOC
## Node ID Injection

### Description
Node ID injection allows you to reference specific, existing nodes within your TuringDB queries by using their unique internal identifier. This method provides a direct way to target nodes without relying solely on their properties.

### Method
Node ID injection is performed using the `@` operator or the `AT` keyword within `MATCH` clauses.

### Syntax and Examples
Node ID injection can be applied in various contexts:

- **Single Node ID:**
  ```jsx
  MATCH (n @ 1) RETURN n.name
  MATCH (n:Person @ 1) RETURN n.name
  MATCH (n:Person{name:"Jane"} @ 1) RETURN n.name
  MATCH (n @ 1 {name:"Jane"}) RETURN n.name
  MATCH (n {name:"Jane"} @ 1) RETURN n.name
  ```

- **Using `AT` keyword:** The `AT` keyword is interchangeable with the `@` operator.
  ```jsx
  MATCH (n AT 1) RETURN n.name
  MATCH (n:Person AT 1) RETURN n.name
  ```

- **Multiple Node IDs (Comma-Separated):** Inject multiple nodes by providing a comma-separated list of IDs.
  ```jsx
  MATCH (n:Person @ 1, 2, 3) RETURN n.name
  ```
  This query will return the `name` property for nodes with IDs 1, 2, and 3.

### Internal ID
The internal ID of a node is the value obtained when querying `MATCH (n) RETURN n`.
```

--------------------------------

### Modifying Graph and Committing Changes (TuringDB CLI)

Source: https://docs.turingdb.ai/concepts/commits

Example of how to modify the graph using Cypher-style queries and then commit these changes within the current workspace.

```cli
> CREATE ...
> SET ...
> commit
```

--------------------------------

### TuringDB: Creating Nodes and Edges

Source: https://docs.turingdb.ai/query/cheatsheet

Illustrates how to create new nodes and edges in the graph database. Labels are required for node creation, and multiple items can be created simultaneously using commas. The CREATE clause does not use a RETURN clause.

```sql
CREATE (:Person {name: 'Alice', age: 30})
CREATE (:Person {name: 'Mick'})-[:FRIEND_OF]->(:Person {name: 'John'})
CREATE (a)-[:EDGE]->(b), (b)-[:EDGE]->(c), (c)-[:EDGE]->(a)

CREATE (gabby:Person {name: 'Gabby', age: 27}),
(susan:Person {name: 'Susan', age: 35}),
(lynette:Person {name: 'Lynette', age: 41}),
(bree:Person {name: 'Bree', age: 42}),
(gabby)-[FRIEND_OF]->(susan),
(gabby)-[NEIGHBORS_OF]->(susan),
...
```

--------------------------------

### Metaqueries for Graph Metadata

Source: https://docs.turingdb.ai/query/cypher_subset

Explore TuringDB's metaqueries, which provide insights into the graph's structure, including properties, labels, and edge types.

```APIDOC
## Metaqueries for Graph Metadata

### Description
TuringDB supports special "metaqueries" that do not alter or retrieve data directly from the graph, but rather provide metadata *about* the graph itself. These queries are useful for understanding the data schema and planning further graph operations.

### Method
Metaqueries are invoked using the `CALL` syntax.

### Supported Metaqueries

1.  **`CALL PROPERTIES ()`**
    *   **Description:** Returns a list of all distinct node and edge properties present in the database, along with their respective data types.
    *   **Example:** `CALL PROPERTIES ()`

2.  **`CALL LABELS ()`**
    *   **Description:** Returns a list of all unique node labels used within the graph.
    *   **Example:** `CALL LABELS ()`

3.  **`CALL EDGETYPES()`**
    *   **Description:** Returns a list of all unique edge types (similar to node labels for edges) present in the graph.
    *   **Example:** `CALL EDGETYPES()`

4.  **`CALL LABELSETS ()`**
    *   **Description:** Returns information about combinations of node labels that are used together in the graph, typically presented in two columns.
    *   **Example:** `CALL LABELSETS ()`

### Use Cases
Metaqueries are particularly helpful for:
- Exploring the available data schema before writing complex `MATCH` or `CREATE` queries.
- Understanding the diversity of node types and relationships.
- Validating the structure of the graph.
```

--------------------------------

### Create Graph using Javascript Fetch API

Source: https://docs.turingdb.ai/graph_dev/create_graph

This snippet illustrates creating a graph named 'my_graph' via Javascript using the Fetch API. It makes a POST request to the TuringDB SDK endpoint, including authorization and instance ID in the headers, and the 'CREATE GRAPH' command in the request body. An example JSON response is included.

```javascript
// Create a new graph called my_graph
fetch(`https://engines.turingdb.ai/sdk/query`, {
    method: "POST",
    headers: {
        Authorization: `Bearer ${MY_API_KEY}`,
        "Turing-Instance-Id": `${MY_INSTANCE_ID}`,
        Accept: "application/json",
    },
    body: "CREATE GRAPH my_graph",
});
```

```json
{
  "header": {"column_names": [],"column_types": []},
  "data": [],
  "time": 0.873002
}
```

--------------------------------

### Create Graph using TuringDB Python SDK

Source: https://docs.turingdb.ai/graph_dev/create_graph

This snippet demonstrates how to create a new graph named 'my_graph' using the TuringDB Python SDK. It requires setting up the client with your instance ID and authentication token. The function executes a 'CREATE GRAPH' query and sets the active graph.

```python
from turingdb import TuringDB

# Setup TuringDB client
client = TuringDB(
    instance_id="...",  # Replace by your instance id
    auth_token="...",   # Replace by your API token
)

# Create a new graph called my_graph
client.query('CREATE GRAPH my_graph')
client.set_graph('my_graph')
```

--------------------------------

### TuringDB MATCH Query for All Nodes

Source: https://docs.turingdb.ai/query/cypher_subset

Shows a simple MATCH query to retrieve all nodes present in the TuringDB database. This is a fundamental query for inspecting the entire dataset.

```sql
MATCH (n) RETURN n
```

--------------------------------

### Metaquery to List All Edge Types

Source: https://docs.turingdb.ai/query/cypher_subset

Presents the `CALL EDGETYPES()` metaquery, which returns a list of all distinct edge types (similar to node labels for edges) present in the graph.

```sql
CALL EDGETYPES()

```

--------------------------------

### Core Methods

Source: https://docs.turingdb.ai/pythonsdk/reference

Details on essential methods for managing graphs and executing queries.

```APIDOC
## Core Methods

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

#### Description
Returns all graphs you have access to on the TuringDB Cloud backend.

#### Example
```python
client.list_available_graphs()
```

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

#### Description
Returns the currently loaded graphs in memory.

#### Example
```python
client.list_loaded_graphs()
```

### `create_graph(graph_name: str)`

#### Description
Creates a new empty graph with the specified name.

#### Example
```python
client.create_graph("my_new_graph")
```

> Internally executes `CREATE GRAPH "graph_name"`

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

#### Description
Loads a previously created graph into memory. If `raise_if_loaded=False`, it will silently continue if the graph is already loaded.

#### Example
```python
client.load_graph("my_graph")
```

### `query(query: str) → pandas.DataFrame`

#### Description
Runs a Cypher query on the current graph. Returns results as a `pandas.DataFrame`, with automatic typing and parsing.

#### Example
```python
df = client.query("MATCH (n:Person) RETURN n.name, n.age")
```
```
Tokens:
Raw