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)
• Dual execution modes: Separate buttons for running entire file or selected text
• 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
• Comment filtering: Automatically skips comment-only queries (SQL --, C-style // and /* */)
• Progress tracking: Real-time progress indicator showing "Executing query X/Y..."
• Query statistics: Detailed execution time and performance metrics per query
• USE statement support: Automatic graph switching with USE <graph_name> statements
• Query history: Track previously executed queries with timestamps and execution times

🔧 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

Execute Entire File:

• Click the ▶️ play button in the editor toolbar to run all queries in the file
• Right-click in editor → "Execute Entire GQL File"
• Command Palette → Ultipa GQL: Execute Entire GQL File

Execute Selected Text:

• Select text in the editor → A second ▶◯ play-circle button appears
• Click the ▶◯ button to run only the selected queries
• Right-click in editor → "Execute Selected GQL Query"
• Command Palette → Ultipa GQL: Execute Selected GQL Query

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 & Graph Switching

-- Switch to a specific graph (both syntaxes supported)
USE mygraph;
-- or
USE GRAPH mygraph;

-- 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;

-- Switch to another graph
USE anothergraph;

-- 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;

Progress Tracking: When executing multiple queries, you'll see real-time progress:

• Single query: "Executing query..."
• Multiple queries: "Executing query 3/14..." (shows current/total)

Comment Handling: The extension automatically filters out comment-only queries and strips comments before processing:

-- ============================================================================
-- File Header Comments (stripped before processing)
-- ============================================================================
USE GRAPH mygraph;  -- This USE statement is detected after stripping comments

-- This comment-only line will be skipped
MATCH (n) RETURN n;  -- This query will execute

// C-style comment (also skipped)
/* Multi-line comment
   also skipped */

MATCH (n)-[r]->(m) RETURN n, r, m;  -- Only actual queries are sent to database

⚙️ 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

-- Graph switching (detected by extension, not sent to database)
-- Both syntaxes are supported:
USE mygraph;
-- or
USE GRAPH mygraph;

-- 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