---
title: "Cypher Query Language Reference"
---

# Cypher Query Language Reference

:::caution[Planned]
Graph-RAG and Code-Graph for HeliosDB Full are planned. Code-Graph (`hdb_code`),
Graph-RAG (`WITH CONTEXT`) and the native MCP server are available in HeliosDB Nano
as build-from-source features. The Cypher queries and GraphRAG features on this page
are not reachable in the current HeliosDB Full release; this page describes the planned feature.
:::

## Quick Reference Card

### Pattern Matching

```cypher
-- Node patterns
(n)                         -- Any node
(n:Person)                  -- Node with label
(n:Person {name: 'Alice'})  -- Node with label and properties

-- Relationship patterns
-[r]->                      -- Any directed relationship
-[r:KNOWS]->               -- Typed relationship
-[r:KNOWS {since: 2020}]-> -- Relationship with properties
-[r*1..3]->                -- Variable length (1 to 3 hops)
-[r]-                      -- Undirected relationship
```

### MATCH Clauses

```cypher
-- Basic match
MATCH (n:Person) RETURN n

-- Pattern with relationship
MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a, b

-- Variable-length paths
MATCH (a)-[:KNOWS*1..3]->(b) RETURN a, b

-- Multiple patterns
MATCH (a:Person), (b:Person)
WHERE a.age > b.age
RETURN a, b
```

### WHERE Conditions

```cypher
-- Comparison
WHERE n.age > 18
WHERE n.name = 'Alice'
WHERE n.age >= 18 AND n.age <= 65

-- String operations
WHERE n.name STARTS WITH 'A'
WHERE n.name ENDS WITH 'son'
WHERE n.name CONTAINS 'ali'

-- Null checks
WHERE n.email IS NOT NULL
WHERE n.phone IS NULL

-- List operations
WHERE n.age IN [18, 21, 25]
WHERE n.tags CONTAINS 'developer'

-- Existence
WHERE EXISTS { MATCH (n)-[:KNOWS]->() }
```

### CREATE Statements

```cypher
-- Create node
CREATE (n:Person {name: 'Alice', age: 30})

-- Create relationship
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020}]->(b)

-- Create path
CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})
```

### UPDATE Operations

```cypher
-- Set properties
MATCH (n:Person {name: 'Alice'})
SET n.age = 31, n.city = 'NYC'

-- Add label
MATCH (n:Person {name: 'Alice'})
SET n:Employee

-- Remove property
MATCH (n:Person {name: 'Alice'})
REMOVE n.age

-- Replace all properties
MATCH (n:Person {name: 'Alice'})
SET n = {name: 'Alice Smith', age: 31}
```

### DELETE Operations

```cypher
-- Delete relationship
MATCH (a)-[r:KNOWS]->(b)
DELETE r

-- Delete node (must delete relationships first)
MATCH (n:Person {name: 'Alice'})
DELETE n

-- Delete node and relationships
MATCH (n:Person {name: 'Alice'})
DETACH DELETE n
```

### Aggregations

```cypher
-- Count
MATCH (n:Person) RETURN count(n)

-- Sum, Avg, Min, Max
MATCH (n:Person) RETURN avg(n.age), min(n.age), max(n.age)

-- Group by
MATCH (n:Person)
RETURN n.city, count(n), avg(n.age)

-- Collect
MATCH (p:Person)-[:KNOWS]->(f)
RETURN p.name, collect(f.name) AS friends
```

### Ordering and Limiting

```cypher
-- Order by
MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC

-- Limit
MATCH (n:Person)
RETURN n
LIMIT 10

-- Skip
MATCH (n:Person)
RETURN n
ORDER BY n.age
SKIP 10
LIMIT 10
```

### Functions

**String Functions**:
```cypher
RETURN toLower('HELLO')           -- 'hello'
RETURN toUpper('hello')           -- 'HELLO'
RETURN trim('  hello  ')          -- 'hello'
RETURN substring('hello', 0, 3)   -- 'hel'
```

**Math Functions**:
```cypher
RETURN abs(-5)                    -- 5
RETURN round(3.14159)             -- 3
RETURN ceil(3.1)                  -- 4
RETURN floor(3.9)                 -- 3
RETURN sqrt(16)                   -- 4
```

**List Functions**:
```cypher
RETURN size([1,2,3])              -- 3
RETURN head([1,2,3])              -- 1
RETURN tail([1,2,3])              -- [2, 3]
RETURN range(1, 10)               -- [1,2,3,4,5,6,7,8,9,10]
```

**Path Functions**:
```cypher
MATCH p = (a)-[:KNOWS*1..3]->(b)
RETURN length(p), nodes(p), relationships(p)
```

### Complex Queries

**Shortest Path**:
```cypher
MATCH p = shortestPath((a:Person {name: 'Alice'})-[:KNOWS*..5]->(b:Person {name: 'Bob'}))
RETURN p
```

**All Shortest Paths**:
```cypher
MATCH p = allShortestPaths((a)-[:KNOWS*..5]->(b))
WHERE a.name = 'Alice' AND b.name = 'Bob'
RETURN p
```

**CASE Expressions**:
```cypher
MATCH (n:Person)
RETURN n.name,
  CASE
    WHEN n.age < 18 THEN 'Minor'
    WHEN n.age >= 18 AND n.age < 65 THEN 'Adult'
    ELSE 'Senior'
  END AS ageGroup
```

**UNION**:
```cypher
MATCH (n:Person) RETURN n.name
UNION
MATCH (n:Company) RETURN n.name
```

**WITH Clause** (pipeline):
```cypher
MATCH (n:Person)
WITH n, n.age AS age
WHERE age > 18
RETURN n.name, age
ORDER BY age DESC
LIMIT 5
```

### Performance Tips

1. Use indexes for frequent lookups
2. Add LIMIT when possible
3. Use PROFILE to analyze queries
4. Avoid Cartesian products
5. Use variable-length paths carefully

**Example Query Plan**:
```cypher
PROFILE
MATCH (a:Person)-[:KNOWS*1..3]->(b:Person)
WHERE a.name = 'Alice'
RETURN b.name
LIMIT 10
```

## HeliosDB Extensions

### HTAP Hints

```cypher
-- Force OLTP execution
MATCH /*+ OLTP */ (n:Person {id: 123}) RETURN n

-- Force OLAP execution
MATCH /*+ OLAP */ (n:Person) RETURN count(n), avg(n.age)

-- Suggest index usage
MATCH (n:Person /*+ INDEX(name) */) WHERE n.name = 'Alice' RETURN n
```

### Vector Similarity (HeliosDB Extension)

```cypher
-- Find similar nodes by embedding
MATCH (n:Document)
WHERE vectorSimilarity(n.embedding, $queryEmbedding) > 0.8
RETURN n.text, vectorSimilarity(n.embedding, $queryEmbedding) AS score
ORDER BY score DESC
LIMIT 10
```

### Geospatial Queries (HeliosDB Extension)

```cypher
-- Find nearby locations
MATCH (n:Location)
WHERE distance(n.coordinates, point({latitude: 40.7128, longitude: -74.0060})) < 1000
RETURN n.name, distance(n.coordinates, point({latitude: 40.7128, longitude: -74.0060})) AS distanceMeters
ORDER BY distanceMeters
```

### Full-Text Search (HeliosDB Extension)

```cypher
-- Full-text search on properties
MATCH (n:Document)
WHERE fulltext(n.content, 'machine learning graph database')
RETURN n.title, fulltextScore(n.content, 'machine learning graph database') AS score
ORDER BY score DESC
LIMIT 10
```

---

**Complete Syntax Guide**: 100+ pages in full documentation