Skip to content

🔌 LSP Extensions

Qlue-ls extends the Language Server Protocol with custom methods. These methods are prefixed with qlueLs/ and provide SPARQL-specific functionality that goes beyond standard LSP capabilities.

Note

Your LSP client will not have built-in support for these methods. You will need to implement custom handlers in your client to use them.

Backend Management

Backends represent SPARQL endpoints that the language server can connect to for completions, hover information, and query execution.

➕ addBackend

Register a SPARQL endpoint with the language server.

Notification:

  • method: qlueLs/addBackend
  • params: AddBackendParams defined as follows:
interface AddBackendParams {
    name: string;
    url: string;
    healthCheckUrl?: string;
    engine?: "QLever" | "GraphDB" | "Virtuoso" | "MillenniumDB" | "Blazegraph" | "Jena";
    requestMethod?: "GET" | "POST";
    default: boolean;
    prefixMap?: Record<string, string>;
    queries?: Record<string, string>;
    additionalData?: any;
}

🔍 getBackend

Get information about a backend. If backend is provided, returns that specific backend; otherwise returns the default backend.

Request:

  • method: qlueLs/getBackend
  • params: GetBackendParams defined as follows:
interface GetBackendParams {
    backend?: string;  // If omitted, returns the default backend
}

Response:

  • result: BackendConfiguration | null
  • error: GetBackendError | null — present when the requested backend is not found
interface BackendConfiguration {
    name: string;
    url: string;
    healthCheckUrl?: string;
    engine?: "QLever" | "GraphDB" | "Virtuoso" | "MillenniumDB" | "Blazegraph" | "Jena";
    requestMethod?: "GET" | "POST";
    prefixMap: Record<string, string>;
    default: boolean;
    queries: Record<string, string>;
    additionalData?: any;
}

interface GetBackendError {
    code: number;
    message: string;
}

📋 listBackends

List all registered backends.

Request:

  • method: qlueLs/listBackends
  • params: none

Response:

  • result: ListBackendsItem[]
interface ListBackendsItem {
    name: string;
    url: string;
    default: boolean;
}

🔄 updateDefaultBackend

Change the active default backend.

Notification:

  • method: qlueLs/updateDefaultBackend
  • params: UpdateDefaultBackendParams defined as follows:
interface UpdateDefaultBackendParams {
    backendName: string;
}

📡 pingBackend

Test connectivity to a SPARQL endpoint.

Request:

  • method: qlueLs/pingBackend
  • params: PingBackendParams defined as follows:
interface PingBackendParams {
    backendName?: string;  // If omitted, pings the default backend
}

Response:

  • result: PingBackendResult defined as follows:
interface PingBackendResult {
    available: boolean;
}

Settings

⚙ defaultSettings

Get the default server settings.

Request:

  • method: qlueLs/defaultSettings
  • params: none

Response:

  • result: Settings defined as follows:
interface Settings {
    format: FormatSettings;
    completion: CompletionSettings;
    prefixes?: PrefixesSettings;
}

See Configuration for details on the settings structure.

🔧 changeSettings

Update server settings at runtime.

Notification:

  • method: qlueLs/changeSettings
  • params: Settings

Warning

This replaces all current settings with the provided values.

Query Execution

▶ executeOperation

Execute a SPARQL query or update operation against the configured backend.

Request:

  • method: qlueLs/executeOperation
  • params: ExecuteOperationParams defined as follows:
interface ExecuteOperationParams {
    textDocument: TextDocumentIdentifier;
    maxResultSize?: number;
    resultOffset?: number;
    queryId?: string;
    lazy?: boolean;       // WASM only: stream results incrementally
    accessToken?: string; // For authenticated endpoints
}

Response:

  • result: ExecuteOperationResult | null
  • error: ExecuteOperationError | null
type ExecuteOperationResult = 
    | { queryResult: QueryResult }
    | { updateResult: UpdateResult[] };

interface QueryResult {
    timeMs: number;
    result?: SparqlResult;
}

interface ExecuteOperationError {
    code: number;
    message: string;
    data: ExecuteOperationErrorData;
}

type ExecuteOperationErrorData =
    | { type: "QLeverException"; exception: string; query: string; status: "ERROR"; metadata?: ErrorMetadata }
    | { type: "Connection"; /* connection error details */ }
    | { type: "Canceled"; query: string }
    | { type: "InvalidFormat"; query: string; message: string }
    | { type: "Unknown" };

⏹ cancelQuery

Cancel a running SPARQL query.

Notification:

  • method: qlueLs/cancelQuery
  • params: CancelQueryParams defined as follows:
interface CancelQueryParams {
    queryId: string;
}

Note

The queryId must match the one provided in the executeOperation request.

⏩ partialResult

Stream partial SPARQL results as they become available.

Note

This is a server-to-client notification, only available in WASM builds when lazy: true is set in executeOperation.

Notification (server to client):

  • method: qlueLs/partialResult
  • params: PartialResult (partial SPARQL result data)

🕳 jump

Enable "tab navigation" within SPARQL queries. The server provides the next (or previous) relevant position in the query. The LSP client should move the cursor to this position.

Request:

  • method: qlueLs/jump
  • params: JumpParams defined as follows:
interface JumpParams extends TextDocumentPositionParams {
    previous?: boolean;
}

Response:

  • result: JumpResult | null defined as follows:
interface JumpResult {
    position: Position;
    insertBefore: string | null;
    insertAfter: string | null;
}

🌳 parseTree

Get the full parse tree for a document. Each element is annotated with its LSP range. By default the tree is lossless — it contains every character from the source text, including whitespace and comments. Set skipTrivia to true to exclude whitespace and comment tokens.

Request:

  • method: qlueLs/parseTree
  • params: ParseTreeParams defined as follows:
interface ParseTreeParams {
    textDocument: TextDocumentIdentifier;
    skipTrivia?: boolean;  // If true, excludes whitespace and comment tokens
}

Response:

  • result: ParseTreeResult defined as follows:
interface ParseTreeResult {
    tree: ParseTreeElement;
    timeMs: number;  // Time spent parsing in milliseconds
}

type ParseTreeElement =
    | { type: "node";  kind: string; range: Range; children: ParseTreeElement[] }
    | { type: "token"; kind: string; range: Range; text: string };

Node elements represent syntax tree nodes (e.g. SelectQuery, WhereClause) and contain child elements. Token elements represent individual tokens (e.g. SELECT, WHITESPACE) and carry their source text.

❓ identifyOperationType

Determine if a SPARQL document is a query or update operation.

Request:

  • method: qlueLs/identifyOperationType
  • params: IdentifyOperationTypeParams defined as follows:
interface IdentifyOperationTypeParams {
    textDocument: TextDocumentIdentifier;
}

Response:

  • result: IdentifyOperationTypeResult defined as follows:
interface IdentifyOperationTypeResult {
    operationType: OperationType;
}

type OperationType = "Query" | "Update" | "Unknown";