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 cypher CREATE INDEX ON :User(email)
Use EXPLAIN cypher 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 ```cypher -- Good: Specific pattern MATCH (u:User {email: '[email protected]'})

-- Bad: Broad scan MATCH (u) WHERE u.email = '[email protected]' ```

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

Edit this page on GitHub