Appendix A: GQL Quick Reference

A comprehensive cheat sheet of GQL syntax supported by AstraeaDB. This appendix is designed as a desk reference—keep it open while writing queries. All examples follow the ISO GQL standard as implemented by AstraeaDB.

A.1 Pattern Matching

GQL queries are built around graph patterns—ASCII-art descriptions of the nodes and edges you want to find. The database matches these patterns against the stored graph and returns all matching subgraphs.

Pattern	Description	Example
(n)	Any node, bound to variable n	MATCH (n) RETURN n
(n:Person)	Node with label Person	MATCH (n:Person) RETURN n.name
(n:Person {name: "Alice"})	Node with label and inline property filter	MATCH (n:Person {name: "Alice"}) RETURN n
-[e]->	Outgoing directed edge	MATCH (a)-[e]->(b) RETURN a, e, b
<-[e]-	Incoming directed edge	MATCH (a)<-[e]-(b) RETURN a, b
-[e]-	Edge in either direction (undirected match)	MATCH (a)-[e]-(b) RETURN a, b
-[:KNOWS]->	Edge with a specific relationship type	MATCH (a)-[:KNOWS]->(b) RETURN b.name
-[e:KNOWS {since: 2020}]->	Edge with type and inline property filter	MATCH (a)-[e:KNOWS {since: 2020}]->(b) RETURN a.name, b.name

A.2 Clauses

Clauses are the building blocks of a GQL query. They are composed top-to-bottom in the order shown below.

MATCH

Declares the graph pattern to search for. This is the most fundamental clause in GQL.

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

WHERE

Filters the matched results using boolean expressions. Supports property access, comparison operators, and logical connectives.

MATCH (a:Person)-[:KNOWS]->(b:Person)
WHERE a.age > 25 AND b.name <> "Bob"

RETURN

Specifies which values to include in the query result. Supports property access, aliasing with AS, and aggregate functions.

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name, b.name AS friend

ORDER BY

Sorts results by one or more expressions. Use ASC (default) or DESC for sort direction.

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

SKIP and LIMIT

Paginate results. SKIP discards the first N rows; LIMIT caps the total rows returned.

MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC
SKIP 10 LIMIT 5

CREATE

Inserts new nodes and edges into the graph.

CREATE (n:Person {name: "Alice", age: 30})

SET

Updates properties on existing nodes or edges.

MATCH (n:Person {name: "Alice"})
SET n.age = 31

DELETE

Removes matched nodes or edges from the graph. Nodes with remaining edges cannot be deleted unless you also delete those edges.

MATCH (n:Person {name: "Bob"})
DELETE n

DISTINCT

Eliminates duplicate rows from the result set. Used as a modifier on RETURN.

MATCH (n:Person)
RETURN DISTINCT n.city

A.3 Operators

Comparison Operators

Operator	Meaning	Example
=	Equal to	WHERE n.name = "Alice"
<>	Not equal to	WHERE n.name <> "Bob"
<	Less than	WHERE n.age < 30
>	Greater than	WHERE n.age > 25
<=	Less than or equal	WHERE n.age <= 30
>=	Greater than or equal	WHERE n.age >= 18

Logical Operators

Operator	Meaning	Example
AND	Both conditions must be true	WHERE n.age > 25 AND n.city = "NYC"
OR	At least one condition must be true	WHERE n.age < 20 OR n.age > 60
NOT	Negates a condition	WHERE NOT n.active

String Operators

Operator	Meaning	Example
STARTS WITH	String prefix match	WHERE n.name STARTS WITH "Al"
ENDS WITH	String suffix match	WHERE n.email ENDS WITH "@example.com"
CONTAINS	Substring match	WHERE n.bio CONTAINS "engineer"

A.4 Functions

Element Functions

Function	Description	Example
id(n)	Returns the internal unique ID of a node or edge	RETURN id(n)
labels(n)	Returns the list of labels on a node	RETURN labels(n)
type(e)	Returns the relationship type of an edge	RETURN type(e)

Aggregate Functions

Function	Description	Example
count(n)	Count the number of matched results	RETURN count(n)
sum(n.x)	Sum numeric property values	RETURN sum(n.salary)
avg(n.x)	Calculate arithmetic mean	RETURN avg(n.age)
min(n.x)	Find the minimum value	RETURN min(n.age)
max(n.x)	Find the maximum value	RETURN max(n.age)
collect(n.x)	Aggregate values into a list	RETURN collect(n.name)

Conversion Functions

Function	Description	Example
toString(x)	Convert a value to its string representation	RETURN toString(n.age)
toInteger(x)	Convert a value to an integer	RETURN toInteger(n.score)
toFloat(x)	Convert a value to a floating-point number	RETURN toFloat(n.rating)
toBoolean(x)	Convert a value to a boolean	RETURN toBoolean(n.flag)

A.5 Common Query Patterns

The following examples demonstrate complete, ready-to-use GQL queries covering the most frequent operations you will encounter when working with AstraeaDB.

1. Find all nodes with a specific label

Retrieve every Person node in the graph.

MATCH (n:Person)
RETURN n.name, n.age

2. Find nodes with specific properties

Find all people older than 30 who live in New York.

MATCH (n:Person)
WHERE n.age > 30 AND n.city = "New York"
RETURN n.name, n.age, n.city

3. Find directly connected nodes

Find all people that Alice knows.

MATCH (alice:Person {name: "Alice"})-[:KNOWS]->(friend:Person)
RETURN friend.name, friend.age

4. Multi-hop traversal

Find friends-of-friends of Alice, excluding Alice herself and her direct friends.

MATCH (alice:Person {name: "Alice"})
      -[:KNOWS]->(friend)
      -[:KNOWS]->(fof)
WHERE fof <> alice
  AND NOT (alice)-[:KNOWS]->(fof)
RETURN DISTINCT fof.name

5. Aggregation with grouping

Count the number of people in each city and compute the average age.

MATCH (n:Person)
RETURN n.city AS city,
       count(n) AS population,
       avg(n.age) AS avg_age
ORDER BY population DESC

6. Sorted and paginated results

Retrieve the third page (10 items per page) of people sorted by age descending.

MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC
SKIP 20 LIMIT 10

7. Create a node with properties

Insert a new person into the graph and return the generated ID.

CREATE (n:Person {name: "Diana", age: 27, city: "London"})
RETURN id(n) AS new_id, n.name

8. Create a node and an edge in one query

Create a new person and immediately connect them to an existing person.

MATCH (alice:Person {name: "Alice"})
CREATE (eve:Person {name: "Eve", age: 29})
CREATE (alice)-[:KNOWS {since: 2024}]->(eve)
RETURN eve.name

9. Delete a node and its edges

Remove a person and all edges connected to them.

MATCH (n:Person {name: "Bob"})-[e]-()
DELETE e, n

10. Pattern with multiple relationship types

Find people who Alice both KNOWS and WORKS_WITH.

MATCH (alice:Person {name: "Alice"})-[:KNOWS]->(p:Person)
MATCH (alice)-[:WORKS_WITH]->(p)
RETURN p.name AS colleague_and_friend

A.6 AstraeaDB Extensions to GQL

AstraeaDB extends the standard GQL syntax with several built-in procedures for vector search, temporal queries, and graph algorithms. These are invoked using the CALL syntax.

Procedure	Description
CALL db.index.vector.search(embedding, k)	Find the k nearest nodes by cosine similarity to the given embedding vector
CALL db.index.hybrid.search(anchor, embedding, hops, k, alpha)	Combine vector similarity with structural proximity from an anchor node
CALL db.algo.bfs(start, max_depth)	Breadth-first search from a starting node up to a maximum depth
CALL db.algo.shortest_path(source, target, weighted)	Find the shortest path between two nodes, optionally using edge weights
CALL db.algo.pagerank(iterations, damping)	Compute PageRank centrality scores for all nodes
CALL db.temporal.neighbors_at(node, direction, timestamp)	Find neighbors of a node as they existed at a specific point in time
CALL db.rag.query(question, anchor, hops, max_nodes)	Execute a GraphRAG pipeline: vector search, subgraph extraction, and LLM response