Ultipa GQL Runner for VS Code

Execute ISO GQL (Graph Query Language) files on Ultipa Graph Database with rich interactive visualization and multi-query support.

⚠️ Important: This extension is for ISO GQL (Graph Query Language), NOT GraphQL. They are completely different languages:

ISO GQL: Graph database query language for graph databases like Ultipa

GraphQL: API query language for web services

✨ Features

🚀 Query Execution

Execute ISO GQL queries directly from VS Code (.gql, .ugql files)
Multi-query support: Execute multiple queries separated by semicolons in a single file
Smart query parsing: Respects string literals and handles semicolons within strings correctly
Query statistics: Detailed execution time and performance metrics

🔧 Connection Management

Multiple connections: Define and switch between multiple Ultipa servers
Secure authentication: Passwords prompted securely (never stored in config)
Connection persistence: Maintains connections across VS Code sessions
Easy switching: Status bar integration for quick connection changes

📊 Advanced Visualization

Interactive graph visualization: Powered by vis.js with nodes, edges, and paths
Configurable styling: Customizable node/edge appearance, colors, and labels
Dynamic labeling: Use custom properties for node/edge labels
Performance optimized: Right-click tooltips to avoid hover lag with large datasets
Multiple view modes: Toggle between graph view and tabular data view

🎛️ Enhanced UI/UX

Tabbed results: Navigate between multiple query results and data aliases
Auto-centering: Graphs automatically center when switching tabs or queries
Selectable tooltips: Right-click nodes/edges to see detailed properties
Responsive design: Adapts to VS Code themes and window sizes
Rich data display: Handles nodes, edges, paths, attributes, and raw data

⚙️ Configuration System

YAML configuration: ultipa.config.yml for comprehensive settings
Visualization customization: Node shapes, sizes, colors, physics settings
Default values: Sensible defaults with easy customization
Hot reload: Configuration changes apply immediately

Note: This extension focuses on query execution and visualization. For ISO GQL syntax highlighting, use a separate syntax highlighting extension.

🚀 Quick Start

1. First Time Setup

Open any .gql or .ugql file in VS Code
When you first run a query, the extension will create a ultipa.config.yml file
Configure your connections in this file (see Configuration section below)

2. Connect to Server

Click the Ultipa status in the status bar to select a connection
Enter password when prompted (passwords are never stored in files)
Connection status is shown in the status bar

3. Execute Queries

Click the ▶️ play button in the editor toolbar
Right-click in editor → "Execute GQL Query"
Command Palette → Ultipa GQL: Execute Query
Keyboard shortcut (if configured)

4. View Results

Results open in a dedicated webview panel
Multiple tabs for different query results
Right-click nodes/edges to see detailed properties in tooltips
Toggle between views: Graph visualization ↔ Table data
Auto-centering: Graphs center automatically when switching tabs

5. Multi-Query Support

-- Execute multiple queries in one file
MATCH (n:Person) RETURN n LIMIT 5;

MATCH (n:Person)-[r:KNOWS]->(m:Person) 
RETURN n, r, m LIMIT 10;

-- Path queries with ISO GQL syntax
MATCH path = (a)-[:FOLLOWS]->{1,2}(b) RETURN path;

-- Handles semicolons in strings correctly  
MATCH (n) WHERE n.name != "Complex;String" RETURN n;

⚙️ Configuration

The extension uses a ultipa.config.yml file in your workspace root. The extension will create a default one on first use:

version: '1.0'
defaultConnection: local
connections:
  - name: local
    host: localhost:60061
    username: admin
    password: <configured>  # Prompted securely, never stored
    defaultGraph: default
    timeout: 30
  - name: production
    host: prod.example.com:60061
    username: prod_user
    defaultGraph: main
    timeout: 60
    
visualization:
  enabled: true
  node:
    size: 25
    labelProperty: ['name', 'id']  # Try 'name' first, fallback to 'id'
    shape: 'dot'                   # dot, ellipse, box, diamond, star
    borderWidth: 2
    font:
      size: 14
      color: '#ffffff'
  edge:
    width: 3
    labelProperty: 'type'          # Property to use for edge labels
    arrows: true
    smooth: true
    font:
      size: 12
      color: '#000000'
  physics:
    enabled: true
    stabilization: true
    barnesHut:
      gravitationalConstant: -8000
      centralGravity: 0.3
      springLength: 120
  layout:
    randomSeed: 1
    improvedLayout: true
  interaction:
    hover: true
    dragNodes: true
    dragView: true
    zoomView: true

Configuration Features:

🔗 Multiple Connections: Define multiple server environments
🎨 Visual Customization: Node shapes, sizes, colors, label properties
⚡ Physics Settings: Control graph layout and animation behavior
🎯 Dynamic Labels: Use any node/edge property for labels
🔐 Secure Passwords: Passwords prompted at runtime, never stored

💡 Example ISO GQL Queries

-- Basic node queries
MATCH (n) RETURN n LIMIT 10;

-- Pattern matching with relationships  
MATCH (person:Person)-[r:KNOWS]->(friend:Person)
RETURN person, r, friend LIMIT 20;

-- Path queries with ISO GQL syntax
MATCH path = (start:Person)-[:KNOWS]->{,3}(end:Person)
WHERE start.name = "Alice" AND end.name = "Bob"
RETURN path;

-- Variable length paths
MATCH (a:Person)-[:KNOWS]->{1,3}(b:Person)
FILTER a.name = "Alice"
RETURN a, b;

-- Aggregation and attributes
MATCH (n:Person)
RETURN table(n.name, n.age, n.city) AS person_info;

-- Complex filtering
MATCH (n:Product)
WHERE n.price > 100 AND n.category = "Electronics"
RETURN n.name, n.price
ORDER BY n.price DESC;

-- Multi-query execution
SHOW GRAPH;
MATCH (n:Person) RETURN count(n) AS person_count;
MATCH ()-[r]->() RETURN count(r) AS edge_count;

📦 Installation & Development

From VS Code Marketplace

# Install from marketplace (when published)
code --install-extension ultipa.vscode-gql-ultipa-runner

👥 Contributors

Jason ZHANG - Initial development and architecture

📝 License

MIT