GraphQL Query Language¶

GraphQL is a query language for APIs developed by Facebook. Grafeo supports GraphQL as an optional query language, enabling queries against graph data using familiar GraphQL syntax.

Overview¶

GraphQL provides a schema-driven approach to querying data. In Grafeo, node labels map to GraphQL types, and relationships map to nested fields.

Enabling GraphQL¶

GraphQL support is optional and requires a feature flag:

cargo add grafeo-engine --features graphql

uv add grafeo[graphql]

Quick Reference¶

Basic Examples¶

Simple Queries¶

# Get all people with their names
{
  Person {
    name
  }
}

# Get multiple fields
{
  Person {
    name
    age
    email
  }
}

Filtering with Arguments¶

# Find person by name
{
  Person(name: "Alix") {
    name
    age
  }
}

# Filter by multiple properties
{
  Person(age: 30, city: "Utrecht") {
    name
    email
  }
}

Where Clause with Operators¶

Use the where argument for advanced filtering with comparison operators:

# Greater than
{
  Person(where: { age_gt: 30 }) {
    name
    age
  }
}

# Multiple conditions (AND)
{
  Person(where: { age_gte: 25, age_lte: 40 }) {
    name
    age
  }
}

# String operations
{
  Person(where: { name_contains: "Ali", email_ends_with: "@example.com" }) {
    name
    email
  }
}

Supported operators:

Pagination¶

Use first and skip to paginate results:

# Get first 10 people
{
  Person(first: 10) {
    name
  }
}

# Skip first 20, get next 10
{
  Person(first: 10, skip: 20) {
    name
  }
}

# With filtering
{
  Person(where: { age_gt: 25 }, first: 5) {
    name
    age
  }
}

Ordering¶

Use orderBy to sort results:

# Sort by name ascending
{
  Person(orderBy: { name: ASC }) {
    name
    age
  }
}

# Sort by age descending
{
  Person(orderBy: { age: DESC }) {
    name
    age
  }
}

# Multiple sort keys
{
  Person(orderBy: { age: DESC, name: ASC }) {
    name
    age
  }
}

# Combined with pagination
{
  Person(orderBy: { age: DESC }, first: 10) {
    name
    age
  }
}

Nested Relationships¶

# Get person and their friends
{
  Person(name: "Alix") {
    name
    friends {
      name
      age
    }
  }
}

# Multiple levels deep
{
  Person(name: "Alix") {
    name
    friends {
      name
      friends {
        name
      }
    }
  }
}

Using Aliases¶

# Query multiple people with aliases
{
  alix: Person(name: "Alix") {
    name
    age
  }
  gus: Person(name: "Gus") {
    name
    age
  }
}

Mutations¶

GraphQL mutations support creating and deleting nodes in the graph.

Creating Nodes¶

Use create<Type> to create new nodes:

# Create a new person
mutation {
  createPerson(name: "Alix", age: 30) {
    id
    name
  }
}

# Create with multiple properties
mutation {
  createUser(name: "Gus", email: "gus@example.com", active: true) {
    id
    name
    email
  }
}

The mutation field name follows the pattern create<NodeLabel>. Arguments become node properties.

Deleting Nodes¶

Use delete<Type> to delete nodes:

# Delete by ID
mutation {
  deletePerson(id: 123)
}

# Delete by property
mutation {
  deleteUser(email: "gus@example.com")
}

Mutation Examples in Python¶

import grafeo

db = grafeo.GrafeoDB()

# Create a node with GraphQL
result = db.execute_graphql('''
mutation {
  createPerson(name: "Alix", age: 30) {
    id
    name
  }
}
''')

# Query the created node
result = db.execute_graphql('''
{
  Person(name: "Alix") {
    name
    age
  }
}
''')

# Delete the node
db.execute_graphql('''
mutation {
  deletePerson(name: "Alix")
}
''')

Python Usage¶

import grafeo

db = grafeo.GrafeoDB()

# Create some data using GQL
db.execute("INSERT (:Person {name: 'Alix', age: 30})")
db.execute("INSERT (:Person {name: 'Gus', age: 25})")
db.execute("""
    MATCH (a:Person {name: 'Alix'}), (b:Person {name: 'Gus'})
    INSERT (a)-[:friends]->(b)
""")

# Query with GraphQL
result = db.execute_graphql('''
{
  Person(name: "Alix") {
    name
    age
    friends {
      name
    }
  }
}
''')

for row in result:
    print(row)

Rust Usage¶

use grafeo_engine::GrafeoDB;

let db = GrafeoDB::new_in_memory();

// Create data
db.execute("INSERT (:Person {name: 'Alix'})").unwrap();

// Query with GraphQL
let result = db.execute_graphql(r#"
{
  Person {
    name
  }
}
"#).unwrap();

How It Maps to the Graph¶

GraphQL queries are translated to graph traversals:

Example Translation¶

{
  Person(name: "Alix") {
    age
    friends {
      name
    }
  }
}

Translates to:

1. Find nodes with label Person where name = "Alix"
2. Return the age property
3. Traverse friends edges
4. Return name property of connected nodes

Supported Features¶

Query Operations¶

• Root type queries (label-based node selection)
• Field selection (property access)
• Arguments (property filtering)
• Where clause with comparison operators (_gt, _lt, _contains, etc.)
• Pagination (first, skip)
• Ordering (orderBy with ASC/DESC)
• Nested selections (relationship traversal)
• Aliases (multiple queries with names)
• Fragments (named and inline)

Mutation Operations¶

• create<Type> - Create new nodes with properties
• update<Type> - Update node properties by filter match
• delete<Type> - Delete nodes by property match

Mutations operate on node properties only. Relationship creation, update, or deletion is not supported through GraphQL mutations. Use GQL or Cypher for relationship manipulation.

Subscriptions¶

GraphQL subscriptions are not supported. The subscription keyword is parsed, but rejected at execution time with an error.

Type Mapping¶

• GraphQL types map to node labels
• GraphQL fields map to properties or relationships
• Scalar fields return property values
• Object fields traverse relationships

Learn More¶