Cheatsheet - Graph Query Language (GQL)

Important Note: GQL is an emerging ISO standard (ISO/IEC 3901). While its core concepts are stable, specific syntax and features might evolve until the standard is fully ratified and widely implemented by graph database vendors. This cheatsheet reflects the current understanding of the proposed GQL standard, drawing heavily on its similarities to well-established graph query languages like Cypher and SQL. It is not GraphQL, which is an API query language.

GQL is a declarative graph query language designed for managing and querying graph databases. It combines powerful graph pattern matching with a familiar SQL-like syntax for data manipulation and structure definition.

1. Core Graph Concepts

• Node (Vertex): Represents entities (e.g., Person, Product). Can have labels and properties.
• Relationship (Edge): Represents connections between nodes (e.g., FRIENDS_WITH, PURCHASED). Can have types and properties. Relationships are directed.
• Property: Key-value pairs associated with nodes or relationships (e.g., name: 'Alice', amount: 99.99).
• Label/Type: Categorizes nodes (labels) and relationships (types). A node can have multiple labels.

2. Basic Query Structure

GQL queries are typically composed of clauses, similar to SQL.

MATCH     (node_patterns)-[relationship_patterns]->(node_patterns)
WHERE     conditions_on_patterns
GROUP BY  grouping_expressions
ORDER BY  ordering_expressions
SKIP      offset_value
LIMIT     limit_value
RETURN    projection_expressions

3. Pattern Matching (MATCH Clause)

The MATCH clause is the heart of GQL for finding specific graph structures.

3.1 Node Patterns

| Pattern | Description | Example | | :---------------------- | :---------------------------------- | :--------------------------------- | --------------- | -------- | | (n) | Any node, assigned to variable n | MATCH (p) | | (:Label) | Any node with a specific label | MATCH (:Person) | | (n:Label) | Node with label, assigned to n | MATCH (p:User) | | (n:L1 | L2) | Node with label L1 OR L2 | MATCH (n:Movie | Series) | | (n:L1&L2) | Node with label L1 AND L2 | MATCH (n:Person&Employee) | | (n:Label {prop: val}) | Node with label and property filter | MATCH (p:Person {name: 'Alice'}) |

3.2 Relationship Patterns

| Pattern | Description | Example | | :------------------------ | :--------------------------------------------- | :------------------------------------------ | ----------------- | ---------- | | -[r]-> | Any outgoing relationship, assigned to r | MATCH (a)-[r]->(b) | | -[:TYPE]-> | Outgoing relationship of specific type | MATCH (a)-[:FRIENDS_WITH]->(b) | | -[r:TYPE]-> | Outgoing relationship of type, assigned to r | MATCH (a)-[f:FOLLOWS]->(b) | | <-- or <-[r]- | Incoming relationship | MATCH (a)<-[:LIKES]-(b) | | -- or -[r]- | Undirected relationship | MATCH (a)-[:KNOWS]-(b) | | -[r:T1 | T2]-> | Relationship of type T1 OR T2 | MATCH (a)-[:OWNS | HAS]->(b) | | -[r:TYPE {prop: val}]-> | Relationship with type and property filter | MATCH (a)-[:PURCHASED {amount: 100}]->(b) |

3.3 Path Patterns

Combine node and relationship patterns to describe graph structures.

• Simple Path: (start_node)-[rel]->(end_node)
  • MATCH (u:User)-[:POSTED]->(t:Tweet)
• Multiple Hops: Chain patterns.
  • MATCH (u:User)-[:FOLLOWS]->(p:Person)-[:WORKS_FOR]->(c:Company)
• Variable-Length Paths: Specify min/max hops using *min..max.
  • -[*min..max]->: Path of min to max hops.
  • -[*min..]->: Path of at least min hops.
  • -[*..max]->: Path of at most max hops.
  • -[*]->: Path of one or more hops.
  • MATCH (p:Person)-[*1..3]->(other:Person) (Find people connected by 1 to 3 relationships)
  • MATCH (p:Person)-[:KNOWS*]->(f:Person) (Find friends of friends)

4. Filtering (WHERE Clause)

Filters results based on conditions.

• Property Filtering:
  • WHERE p.age > 30
  • WHERE t.text CONTAINS 'GQL'
  • WHERE r.date = date('2023-01-01')
• Logical Operators: AND, OR, NOT, XOR
  • WHERE p.name = 'Alice' AND p.age < 40
• Comparison Operators: =, <>, <, >, <=, >=
• Collection Operators: IN, STARTS WITH, ENDS WITH
  • WHERE p.country IN ['USA', 'Canada']
• Pattern Predicates: EXISTS (MATCH ...) (not yet fully detailed in public GQL specs, but a common pattern)
• Null Checks: WHERE p.email IS NULL

5. Projection (RETURN Clause)

Defines what data is returned from the query.

• Return all matched elements: RETURN *
• Return specific nodes/relationships: RETURN n, r, m
• Return properties: RETURN p.name, t.text
• Aliasing: RETURN p.name AS userName
• Literals: RETURN 'Hello World' AS greeting
• Aggregations:
  • COUNT(n): Count nodes/relationships.
  • SUM(r.amount): Sum of properties.
  • AVG(p.age): Average of properties.
  • MIN(p.salary), MAX(p.salary): Min/Max values.
  • COLLECT(p.name): Collect values into a list.
• Distinct values: RETURN DISTINCT p.country

6. Ordering, Skipping, Limiting

• ORDER BY: Sort results.
  • ORDER BY p.age DESC, p.name ASC
• SKIP: Skip a number of initial results.
  • SKIP 10
• LIMIT: Limit the number of returned results.
  • LIMIT 5

7. Data Manipulation (DML)

7.1 CREATE (for Nodes and Relationships)

• Create a node:
  • CREATE (p:Person {name: 'Bob', age: 30})
• Create a relationship:
  • MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) CREATE (a)-[:FRIENDS_WITH {since: 2023}]->(b)
• Create node and relationship together:
  • CREATE (a:User {id: 1})-[:LOGGED_IN]->(l:Log {timestamp: datetime()})

7.2 DELETE (Nodes and Relationships)

• Delete relationships:
  • MATCH (a)-[r:LIKES]->(b) DELETE r
• Delete nodes (requires deleting all connected relationships first):
  • MATCH (p:Person {name: 'Charlie'}) DETACH DELETE p (deletes node and its relationships)
  • MATCH (p:Person {name: 'David'})-[r]-() DELETE r DELETE p (explicitly delete relationships then node)

7.3 SET / UPDATE (Properties)

• Update node properties:
  • MATCH (p:Person {name: 'Bob'}) SET p.age = 31, p.city = 'New York'
• Add a new property:
  • MATCH (p:Person {name: 'Alice'}) SET p.email = '[email protected]'
• Update relationship properties:
  • MATCH (a)-[r:FRIENDS_WITH]->(b) SET r.duration = '1 year'

8. Schema Definition (DDL)

GQL is expected to include DDL statements for defining graph schemas, moving beyond schema-optional graph databases.

• CREATE SCHEMA GRAPH <graph_name>: Defines a named graph within the database.
• CREATE (NODE | EDGE) TYPE <type_name> (properties, ...): Defines node and edge types with their properties and data types.
• CREATE (NODE | EDGE) TYPE <type_name> HAS KEY (property_name, ...): Defines primary keys for node/edge types.
• CREATE RELATIONSHIP TYPE <rel_type_name> FOR (source_node_type, target_node_type): Defines valid source/target node types for a relationship.

Example (Conceptual DDL):

CREATE SCHEMA GRAPH SocialNetwork;

CREATE NODE TYPE Person (
    id        STRING,
    name      STRING NOT NULL,
    age       INTEGER,
    HAS KEY (id)
);

CREATE NODE TYPE Post (
    id        STRING,
    text      STRING,
    timestamp DATETIME,
    HAS KEY (id)
);

CREATE EDGE TYPE FOLLOWS (
    since DATETIME
) FOR (Person, Person);

CREATE EDGE TYPE CREATED_POST (
    at DATETIME
) FOR (Person, Post);

GQL vs GraphQL

GQL (Graph Query Language) and GraphQL are not related projects, despite sharing very similar names and both dealing with "graphs." They serve completely different purposes in different layers of the technology stack.

In short: GQL is about talking to graph databases. GraphQL is about talking to APIs. They solve different problems and operate at different levels of a software stack.

Feature	GQL (Graph Query Language)	GraphQL
Primary Purpose	Querying & Manipulating Graph Databases	Querying & Mutating APIs
Technology Layer	Database layer	API layer (client-server communication)
Standard/Origin	ISO/IEC standard (emerging)	Open specification (Facebook initiated)
Syntax Focus	Graph pattern matching (MATCH, WHERE), SQL-like clauses	Data fetching structure (query, mutation)
Deals with "Graphs"	The structure of data in a graph database	The structure of an API's data relationships
Analogy	SQL for graph databases	A flexible alternative to REST APIs

\