GQL API

Overview

Introduction to GQL in RageDB

RageDB provides native, high-performance support for GQL (Graph Query Language), the ISO standard query language for property graphs. Rather than using procedural traversals, GQL allows you to express declarative graph patterns. The query engine automatically compiles, optimizes, and executes these matches across RageDB's sharded, in-memory architecture.

A GQL query uses Graph Pattern Matching (GPM) to search for structures in the graph. Patterns are built by combining node patterns, edge patterns, path patterns, and complex graph match modes.

Example Schema: Wizarding & Mana Alliance

Throughout the GQL documentation, all query examples use a shared domain model: the Wizarding School & Mana Alliance schema. This model represents wizards, the spells they know or teach, and the channeled mana paths they establish to boost their powers.

Nodes
  • Wizard: Represents a magic practitioner.
    • name (string): The wizard's name (e.g., "Albus", "Severus").
    • level (integer): The magical level/power of the wizard.
    • affinity (string): The elemental magic affinity (e.g., "Fire", "Ice", "Lightning", "Light", "Dark").
  • Spell: Represents a magic spell.
    • name (string): The spell's name (e.g., "Fireball", "Shield of Light").
    • element (string): The element of the spell (e.g., "Fire", "Ice", "Lightning").
    • base_damage (integer): The spell's baseline damage.
Edges
  • Knows: Wizard → Wizard. Social or knowledge link. No properties.
  • AlliedWith: Wizard → Wizard. A channeled mana alliance connection.
    • mana_cost (integer): The cost in mana points to sustain the channel.
    • affinity_boost (integer): The boost given to affinity-matching spells.
  • Teaches: Wizard → Spell. Represents academic instruction.
    • experience_required (integer): The exp required by a student to learn it.

Initializing the Graph

You can populate the database with the example schema using the following GQL INSERT statement:

INSERT 
  (albus:Wizard {name: "Albus", level: 95, affinity: "Light"}),
  (severus:Wizard {name: "Severus", level: 80, affinity: "Dark"}),
  (harry:Wizard {name: "Harry", level: 45, affinity: "Light"}),
  (hermione:Wizard {name: "Hermione", level: 50, affinity: "Light"}),
  (ron:Wizard {name: "Ron", level: 30, affinity: "Earth"}),
  (luna:Wizard {name: "Luna", level: 40, affinity: "Air"}),
  (draco:Wizard {name: "Draco", level: 45, affinity: "Dark"}),

  (fireball:Spell {name: "Fireball", element: "Fire", base_damage: 50}),
  (frostbolt:Spell {name: "Frostbolt", element: "Ice", base_damage: 45}),
  (shield_light:Spell {name: "Shield of Light", element: "Light", base_damage: 0}),
  (shadow_curse:Spell {name: "Shadow Curse", element: "Dark", base_damage: 75}),

  (albus)-[:Knows]->(severus),
  (harry)-[:Knows]->(hermione),
  (harry)-[:Knows]->(ron),
  (ron)-[:Knows]->(luna),
  (severus)-[:Knows]->(draco),

  (albus)-[:AlliedWith {mana_cost: 5, affinity_boost: 10}]->(harry),
  (harry)-[:AlliedWith {mana_cost: 10, affinity_boost: 5}]->(hermione),
  (hermione)-[:AlliedWith {mana_cost: 15, affinity_boost: 8}]->(ron),
  (ron)-[:AlliedWith {mana_cost: 8, affinity_boost: 3}]->(luna),
  (draco)-[:AlliedWith {mana_cost: 12, affinity_boost: 6}]->(severus),

  (albus)-[:Teaches {experience_required: 500}]->(shield_light),
  (severus)-[:Teaches {experience_required: 400}]->(shadow_curse),
  (hermione)-[:Teaches {experience_required: 200}]->(fireball),
  (harry)-[:Teaches {experience_required: 150}]->(frostbolt)