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

# TuringDB Query Language Cheatsheet

> A compact reference for querying, creating, and exploring graphs in TuringDB using Cypher-like syntax + TuringDB-specific extensions.

## MATCH: Pattern Matching

```jsx theme={null}
MATCH (n) RETURN n
MATCH (n:Person {name: 'Alice'}) RETURN n.age
MATCH (a:Person)-->(b:Company) RETURN a.name, b.name
```

* `()` → Node
* `[]` → Edge
* `-` → Undirected edge
* Labels: `:Label`
* Properties: `{key: 'value', age: 30}`

## CREATE: Add Nodes & Edges

```jsx theme={null}
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)-[FRIEND_OF]->(lynette),
...
```

* Labels **required** for node creation
* No `RETURN` clause
* Use commas to create multiple items at once

## MATCH + CREATE and MATCH + CREATE + RETURN

```jsx theme={null}
// Create two nodes Person
CREATE (:Person {name: 'Alice', age: 24}),
	   (:Person {name: 'John', age: 27})

// Match two nodes to create the edge between them
MATCH (n:Person {name: 'Alice'}), (m:Person {name: 'John'})
CREATE (n)-[:FRIENDS_WITH]->(m)

// RETURN clause can also be added
MATCH (n:Person {name: 'Alice'}), (m:Person {name: 'John'})
CREATE (n)-[:FRIENDS_WITH]->(m)
RETURN n.name, n.age, m.name, m.age
```

## SET: Update Properties

```jsx theme={null}
// Update a single property
MATCH (n:Person {name: 'Alice'})
SET n.age = 30

// Update multiple properties at once
MATCH (n:Person {name: 'Alice'})
SET n.position = 'Developer', n.surname = 'Taylor'

// Update from an expression
MATCH (p:Product)
SET p.discountPrice = p.price * (1 - 0.15)

// Update edge property
MATCH (n:Person {name: 'Alice'})-[e:KNOWS]->(m:Person {name: 'Bob'})
SET e.since = 2020

// Set an embedding vector
MATCH (n:Person {name: 'Alice'})
SET n.emb = (1.2, 2.0, 0.0, 12.0)

// Set an embedding vector by node ID
MATCH (n) WHERE n = 1234
SET n.emb = (1.2, 2.0, 0.0, 12.0)

// Conditional update with WHERE
MATCH (n:Person)
WHERE n.age < 18
SET n.isMinor = true
```

* Always used with `MATCH`, not `CREATE`
* Creates the property if it does not already exist
* Use `COMMIT` to persist changes

## WHERE: Filter nodes and edges by properties

To filter on node label:

```jsx theme={null}
MATCH (n)
WHERE n:Person
RETURN n, n.age
```

To filter on node property:

```jsx theme={null}
MATCH (n)
WHERE n.name = 'Alice'
RETURN n, n.age
```

To filter on edge label:

```jsx theme={null}
MATCH (n)-[e]->(m)
WHERE e:PLAY_POKER_TOGETHER
RETURN n.name, m.age
```

To filter on edge property:

```jsx theme={null}
MATCH (n)-[e]->(m:Person)
WHERE n.name = 'Gabby'
AND e.play_poker_together = true
RETURN n.name, m.age
```

## SKIP and LIMIT

```jsx theme={null}
// Return first 10 results
MATCH (n) RETURN n LIMIT 10

// Pagination: skip 10, return next 10
MATCH (n) RETURN n SKIP 10 LIMIT 10
```

## ORDER BY

```jsx theme={null}
// Sort ascending (default)
MATCH (n:Person) RETURN n.name, n.age ORDER BY n.age

// Sort descending
MATCH (n:Person) RETURN n.name, n.age ORDER BY n.age DESC

// Sort by multiple properties
MATCH (n:Person) RETURN n.name, n.age, n.city ORDER BY n.city, n.age DESC

// Combined with pagination
MATCH (n:Person) RETURN n.name, n.age ORDER BY n.age DESC SKIP 10 LIMIT 10
```

## Joins and Cartesian Products

```jsx theme={null}
// Cartesian product: all combinations of Person × Interest
MATCH (a:Person), (b:Interest) RETURN a.name, b.name

// Three-way cartesian product
MATCH (p:Person), (i:Interest), (c:Category) RETURN p.name, i.name, c.name

// Join on shared variable: persons sharing an interest
MATCH (a:Person)-->(b:Interest)<--(c:Person)
WHERE a.name <> c.name
RETURN a.name, b.name, c.name

// With explicit edge types
MATCH (a:Person)-[:INTERESTED_IN]->(b:Interest)<-[:INTERESTED_IN]-(c:Person)
WHERE a.name <> c.name
RETURN a.name, b.name, c.name

// Multi-hop join
MATCH (a:Person)-->(i:Interest)-->(c:Category)
RETURN a.name, i.name, c.name

// Mix path + cartesian product
MATCH (a:Person)-->(i:Interest), (c:Category)
WHERE c.name = 'Cat1'
RETURN a.name, i.name, c.name

// Two independent paths (cartesian of each path's results)
MATCH (a:Person)-->(i1:Interest), (b:Person)-->(i2:Interest)
WHERE a.name <> b.name
RETURN a.name, i1.name, b.name, i2.name
```

* Comma `,` separates independent patterns
* Shared variables between patterns create joins
* Unrelated patterns create cartesian products (N × M rows)

## Property Match Operators

```jsx theme={null}
MATCH (n {name: 'Alice'}) RETURN n
// exact equivalent of
MATCH (n) WHERE n.name = 'Alice' RETURN n
```

* `:` → exact match using property filter in node directly
* `=` → exact match using property filter in WHERE clause

## Boolean operators

* `OR`

  ```jsx theme={null}
  MATCH (n:Person)
  WHERE n.medication = "Aspirin"
  OR n.medication = "Ibuprofen"
  RETURN n.name
  ```
* `AND`

  ```jsx theme={null}
  MATCH (n)
  WHERE n.name = 'Matt'
  AND n.age = 20
  AND n.hasPhD = false
  RETURN n
  ```

## Comparison operators

* Equal: `=`

  ```jsx theme={null}
  # Find antibodies targeting proteins in Human
  MATCH (ab:Antibody)-->(prot:Protein)
  WHERE prot.host = 'Human'
  RETURN ab.name, prot.name
  ```
* Inequal: `<>`

  ```jsx theme={null}
  # Find antibodies (associated to a protein) used together
  # in same publication (2-hop)
  MATCH (ab1:Antibody)-->(prot:Protein), (ab2:Antibody)-->(prot:Protein)
  WHERE ab1.name <> ab2.name
  RETURN ab1.name, ab2.name, prot.name, prot.gene_name
  ```
* Less than: `<`
* Less than or equal to: `<=`
* Greater than: `>`
* Greater than or equal to: `>=`

  ```jsx theme={null}
  # Publications published on 2020 or after
  MATCH (pub:Publication)
  WHERE pub.published_year >= 2020
  RETURN pub.displayName, pub.pubmedid, pub.published_year, pub.country
  ```
* is null:`IS NULL`
* is not null:`IS NOT NULL`

  ```jsx theme={null}
  # Publications from the United States
  MATCH (pub:Publication)
  WHERE pub.country = 'United States'
  AND pub.institution IS NOT NULL
  RETURN pub.displayName, pub.institution, pub.published_year
  ```

## Data Types

| Type      | Example                |
| --------- | ---------------------- |
| String    | `'hello'` or `"hello"` |
| Integer   | `age=30`               |
| Boolean   | `flag=true`            |
| Double    | `score=3.14`           |
| Embedding | `emb=(1.2, 2.0, 0.0)`  |

## RETURN Clause

```jsx theme={null}
MATCH (n)-->(m) RETURN n.name, n.age, m.name, m.age
```

* Select fields with `RETURN n.prop, m.prop`

## Expression evaluation

```jsx theme={null}
// Multiply property by constant
MATCH (n) RETURN n.price * 1.1

// Divide two properties
MATCH ()-[r]->() RETURN r.a / r.b

// Add two properties
MATCH (n) RETURN n.val + n.tax
```

## LOAD graphs

### Load TuringDB graph

Files have to be available in `graphs` subdirectory of `turing-dir`.

```jsx theme={null}
LOAD graph_name
```

### Load external data into TuringDB graph

Files have to be available in `data` subdirectory of `turing-dir`.

```jsx theme={null}
LOAD GML 'mygml.gml' AS my_graph
```

```jsx theme={null}
LOAD JSONL 'myjsonl.jsonl' AS my_graph
```

## Procedures (`CALL`)

| Query                     | Description                         |
| ------------------------- | ----------------------------------- |
| `CALL db.labels()`        | All node labels                     |
| `CALL db.propertyTypes()` | All node/edge property keys & types |
| `CALL db.edgeTypes()`     | All edge types                      |
| `CALL db.history()`       | Commit history                      |

## Graph algorithms

| Function                                   | Description                                              |
| ------------------------------------------ | -------------------------------------------------------- |
| `shortestPath(n, m, distance, dist, path)` | Shortest path between nodes using the Dijkstra processor |

## Functions

| Function          | Description                                                        |
| ----------------- | ------------------------------------------------------------------ |
| `labels(n)`       | Returns the label of node `n` as a string (RETURN only, not WHERE) |
| `toInteger(expr)` | Parses a string as an integer                                      |
| `toFloat(expr)`   | Parses a string as a float                                         |

```jsx theme={null}
// Label introspection
MATCH (n) RETURN labels(n), n.name

// Type conversion
MATCH (n) WHERE n.year > toInteger("2020") RETURN n.name
MATCH (n) RETURN n.price * toFloat("1.07")
```

## Engine Commands

| Command                                | Description                                                                                                                           |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `CREATE GRAPH <name>`                  | Create a new named graph                                                                                                              |
| `LOAD GRAPH <name>`                    | Load an existing graph                                                                                                                |
| `LOAD GML 'mygraph.gml' AS my_graph`   | Load the specified GML as TuringDB graph. Requires the GML to be accessible in TuringDB directory (`--turing-dir`, `data` subdir)     |
| `LOAD JSONL 'mygraph.gml' AS my_graph` | Load the specified JSONL as TuringDB graph. Requires the JSONL to be accessible in TuringDB directory (`--turing-dir`, `data` subdir) |
| `LOAD COMMIT '<hash>'`                 | Load a past commit into memory (needed for REST API queries on non-HEAD commits; CLI and SDK do this automatically)                   |
| `LIST GRAPH`                           | List all available graphs                                                                                                             |
| `HISTORY`                              | Show commit history (versioning)                                                                                                      |
| `CHANGE NEW`                           | Create a new isolated change                                                                                                          |
| `CHANGE SUBMIT`                        | Merge current change into main                                                                                                        |
| `CHANGE DELETE`                        | Delete current change                                                                                                                 |
| `CHANGE LIST`                          | List active uncommitted changes                                                                                                       |

## Useful Patterns

```jsx theme={null}
// Two-hop connection
MATCH (a)-[r1]->(b)-[r2]->(c) RETURN c

// All people named John
MATCH (n:Person {name: 'John'}) RETURN n
/// exact equivalent of
MATCH (n:Person) WHERE n.name = 'John' RETURN n

// Find co-authors: two persons linked to the same publication
MATCH (a:Person)-->(p:Publication)<--(b:Person)
WHERE a.name <> b.name
RETURN a.name, b.name, p.title

// Match existing nodes then create edge between them
MATCH (n:Person {name: 'Alice'}), (m:Person {name: 'Bob'})
CREATE (n)-[:KNOWS]->(m)

// Cartesian: pair every person with every city
MATCH (p:Person), (c:City) RETURN p.name, c.name
```