Skip to content

Autocomplete Plugin Feature

Overview

The Autocomplete Plugin provides intelligent, database-aware Cypher query autocomplete suggestions. Unlike generic autocomplete, this feature uses actual database schema information (labels, properties, relationship types) to provide context-aware suggestions.

Architecture

Backend Components

  1. Plugin Action: heimdall_watcher_autocomplete_suggest
  2. Location: plugins/heimdall/plugin.go (Watcher plugin)

  3. Queries the database for:

    • All node labels (CALL db.labels() YIELD label)
    • All relationship types (CALL db.relationshipTypes() YIELD relationshipType)
    • Sample properties from nodes (limited to 50 for performance)

  4. API Endpoint: /api/bifrost/autocomplete

  5. Location: pkg/heimdall/handler.go
  6. Method: POST
  7. Request: { "query": "MATCH (n", "cursor_position": 10 }

  8. Response: { "suggestion": "...", "schema": { "labels": [...], "properties": [...], "relTypes": [...] } }

  9. SLM Integration

  10. If the action doesn't provide a suggestion, the handler uses the SLM to generate one
  11. The SLM receives the current query plus schema context (labels, properties, relTypes)
  12. Prompt includes instructions to add LIMIT 25 if missing

Frontend Components

  1. QueryAutocomplete Component
  2. Location: ui/src/components/browser/QueryAutocomplete.tsx
  3. Calls /api/bifrost/autocomplete endpoint
  4. Debounced (800ms) to avoid excessive API calls

  5. Displays suggestions in a dropdown below the query editor

  6. Integration

  7. Integrated into QueryPanel.tsx
  8. Toggleable via lightning bolt icon
  9. Keyboard navigation support (Arrow keys, Enter, Escape)

How It Works

  1. User Types Query: User starts typing a Cypher query (e.g., MATCH (n)

  2. Debounce: After 800ms pause, the component sends the partial query to /api/bifrost/autocomplete

  3. Backend Processing:

  4. Action queries database for schema (labels, properties, relTypes)
  5. If SLM is available, generates completion using schema context

  6. Returns both the suggestion and schema info

  7. Suggestion Display:

  8. If a valid suggestion is returned, it appears in a dropdown
  9. User can accept via click, Enter key, or continue typing

Benefits

✅ Database-Aware: Uses actual labels, properties, and relationship types from your database
✅ Context-Aware: Suggestions are based on what actually exists in your graph
✅ Intelligent: SLM generates completions with full schema context
✅ Performance: Debounced requests prevent excessive API calls
✅ User-Friendly: Keyboard navigation and toggleable feature

API Details

Endpoint

POST /api/bifrost/autocomplete

Request

{
  "query": "MATCH (n",
  "cursor_position": 10  // optional
}

Response

{
  "suggestion": "MATCH (n) RETURN n LIMIT 25",
  "schema": {
    "labels": ["Person", "File", "Document"],
    "properties": ["name", "age", "title"],
    "relTypes": ["KNOWS", "OWNS", "AUTHORED"]
  }
}

Example Flow

  1. User types: MATCH (n:Per
  2. Backend queries: Gets all labels, finds "Person" exists
  3. SLM generates: MATCH (n:Person) RETURN n LIMIT 25
  4. UI displays suggestion
  5. User presses Enter → Query is completed

Future Enhancements

  • Property value suggestions based on context
  • Relationship pattern suggestions
  • Multi-line query support
  • Syntax error detection and correction
  • Query optimization suggestions