Cypher Query Language¶

Cypher is a declarative graph query language that allows for expressive and efficient querying of graph data.

Overview¶

QilbeeDB supports OpenCypher, the industry-standard query language for graph databases. Cypher uses ASCII-art syntax to make queries easy to read and write, using patterns to describe graph structures.

Why Cypher?¶

Declarative: Describe what you want, not how to get it
Pattern-based: Use ASCII-art patterns to match graph structures
Expressive: Complex queries are readable and concise
Standard: OpenCypher is widely adopted across graph databases

Graph Data Model¶

Cypher works with two fundamental elements:

Nodes¶

Nodes represent entities in your graph:

(u:User {name: 'Alice', age: 28})

u - Variable name
User - Label
{name: 'Alice', age: 28} - Properties

Relationships¶

Relationships connect nodes:

(alice:User)-[:KNOWS {since: '2020-01-15'}]->(bob:User)

[:KNOWS] - Relationship type
-> - Direction
{since: '2020-01-15'} - Properties

Basic Query Structure¶

A typical Cypher query follows this pattern:

MATCH (pattern)
WHERE (conditions)
RETURN (results)

Example Query¶

MATCH (u:User)-[:KNOWS]->(friend:User)
WHERE u.name = 'Alice' AND friend.age > 25
RETURN friend.name, friend.age
ORDER BY friend.age DESC
LIMIT 10

This query: 1. MATCH: Finds users named Alice and their friends 2. WHERE: Filters friends older than 25 3. RETURN: Returns friend names and ages 4. ORDER BY: Sorts by age descending 5. LIMIT: Returns only top 10 results

Common Clauses¶

MATCH - Pattern Matching¶

Find nodes and relationships:

MATCH (u:User)
MATCH (u:User)-[:KNOWS]->(f:User)
MATCH (u:User)-[:KNOWS*1..3]->(f)  -- Variable-length path

Learn more about MATCH

WHERE - Filtering¶

Filter matched patterns:

WHERE u.age > 25
WHERE u.name STARTS WITH 'A'
WHERE u.email =~ '.*@example.com'

Learn more about WHERE

RETURN - Output¶

Select what to return:

RETURN u.name, u.age
RETURN count(u) AS totalUsers
RETURN u.name, collect(f.name) AS friends

Learn more about RETURN

CREATE - Insert Data¶

Create nodes and relationships:

CREATE (u:User {name: 'Alice', age: 28})
CREATE (a)-[:KNOWS]->(b)

Learn more about CREATE

SET - Update Data¶

Update properties:

SET u.age = 29
SET u += {city: 'New York', updated: datetime()}

Learn more about SET

DELETE - Remove Data¶

Delete nodes and relationships:

DELETE r
DETACH DELETE u  -- Delete node and its relationships

Learn more about DELETE

ORDER BY - Sorting¶

Sort results:

ORDER BY u.age DESC
ORDER BY u.city, u.name

Learn more about ORDER BY

LIMIT - Restrict Results¶

Limit number of results:

LIMIT 10
SKIP 20 LIMIT 10  -- Pagination

Learn more about LIMIT

Complete Example¶

Let's build a social network:

Create Data¶

-- Create users
CREATE (alice:User {name: 'Alice', age: 28, city: 'San Francisco'})
CREATE (bob:User {name: 'Bob', age: 32, city: 'New York'})
CREATE (charlie:User {name: 'Charlie', age: 25, city: 'San Francisco'})

-- Create friendships
CREATE (alice)-[:KNOWS {since: '2020-01-15'}]->(bob)
CREATE (alice)-[:KNOWS {since: '2021-03-20'}]->(charlie)
CREATE (bob)-[:KNOWS {since: '2020-06-10'}]->(charlie)

Query Data¶

Find mutual friends:

MATCH (a:User {name: 'Alice'})-[:KNOWS]->(mutual:User)<-[:KNOWS]-(b:User)
WHERE a <> b
RETURN DISTINCT b.name AS mutualFriend

Find friends in same city:

MATCH (u:User {name: 'Alice'})-[:KNOWS]->(friend:User)
WHERE u.city = friend.city
RETURN friend.name, friend.city

Count friends by city:

MATCH (u:User)-[:KNOWS]->(friend:User)
RETURN friend.city, count(*) AS friendsCount
ORDER BY friendsCount DESC

Update Data¶

Update user information:

MATCH (u:User {name: 'Alice'})
SET u.age = 29, u.updated = datetime()
RETURN u

Delete Data¶

Remove a friendship:

MATCH (a:User {name: 'Alice'})-[r:KNOWS]->(b:User {name: 'Bob'})
DELETE r

Patterns¶

Simple Pattern¶

(a)-[:KNOWS]->(b)

Variable-Length Pattern¶

(a)-[:KNOWS*1..3]->(b)  -- 1 to 3 hops

Multiple Patterns¶

MATCH (a)-[:KNOWS]->(b)-[:WORKS_AT]->(c)

Shortest Path¶

MATCH path = shortestPath((a:User)-[:KNOWS*]-(b:User))
WHERE a.name = 'Alice' AND b.name = 'Charlie'
RETURN length(path)

Working with Properties¶

Property Access¶

RETURN u.name, u.age

Property Existence¶

WHERE exists(u.email)

Property Update¶

SET u.age = u.age + 1

Aggregations¶

Cypher supports powerful aggregations:

-- Count
RETURN count(u) AS totalUsers

-- Sum
RETURN sum(p.price) AS totalValue

-- Average
RETURN avg(u.age) AS averageAge

-- Collect
RETURN u.name, collect(f.name) AS friends

-- Min/Max
RETURN min(u.age), max(u.age)

Parameters¶

Use parameters for dynamic queries:

MATCH (u:User)
WHERE u.age > $minAge AND u.city = $city
RETURN u

Python example:

graph.query("""
    MATCH (u:User)
    WHERE u.age > $minAge
    RETURN u
""", {'minAge': 25})

Best Practices¶

Use Parameters
Improves security (prevents injection)
Enables query plan caching
Makes queries reusable
Create Indexes
```
CREATE INDEX ON :User(email)
```

Use EXPLAIN

EXPLAIN MATCH (u:User) WHERE u.age > 25 RETURN u

Limit Results
Always use LIMIT for exploration
Prevents accidentally loading huge datasets

Use Specific Patterns

-- Good: Specific pattern
MATCH (u:User {email: 'alice@example.com'})

-- Bad: Broad scan
MATCH (u)
WHERE u.email = 'alice@example.com'

Common Operations¶

Create Node¶

CREATE (u:User {name: 'Alice', age: 28})
RETURN u

Find Node¶

MATCH (u:User {name: 'Alice'})
RETURN u

Update Node¶

MATCH (u:User {name: 'Alice'})
SET u.age = 29
RETURN u

Delete Node¶

MATCH (u:User {name: 'Alice'})
DETACH DELETE u

Create Relationship¶

MATCH (a:User {name: 'Alice'}),
      (b:User {name: 'Bob'})
CREATE (a)-[:KNOWS]->(b)

Find Relationships¶

MATCH (a:User)-[r:KNOWS]->(b:User)
WHERE a.name = 'Alice'
RETURN a, r, b

Functions¶

Cypher includes many built-in functions:

String Functions¶

toLower(s), toUpper(s), trim(s), substring(s, start, length)

Numeric Functions¶

abs(n), round(n), sqrt(n), rand()

Aggregation Functions¶

count(), sum(), avg(), min(), max(), collect()

Date/Time Functions¶

datetime(), date(), duration()

See all functions

Resources¶

MATCH Clause - Pattern matching
WHERE Clause - Filtering
RETURN Clause - Output selection
CREATE Clause - Data insertion
SET Clause - Data updates
DELETE Clause - Data deletion
ORDER BY Clause - Sorting
LIMIT Clause - Result limiting
Functions - Built-in functions

Next Steps¶

Try the Quick Start Guide
Learn about Graph Operations
Explore the Python SDK
Read about Query Optimization