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:

type ExecuteOperationParams = ExecuteOperationOptions & (
    | { textDocument: TextDocumentIdentifier } // resolve query from an open document
    | { query: string }                         // pass the SPARQL string inline
);

interface ExecuteOperationOptions {
    maxResultSize?: number;
    resultOffset?: number;
    queryId?: string;
    lazy?: boolean;       // WASM only: stream results incrementally
    accessToken?: string; // For authenticated endpoints
}

The request must carry exactly one of textDocument or query. The textDocument form looks up the query text in the server's document store (populated via textDocument/didOpen and textDocument/didChange). The query form lets clients submit a SPARQL string without first synchronizing it as a document.

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)

Navigation

jump

Enable "tab navigation" within SPARQL queries. The server formats the document, computes the next (or previous) relevant position in the formatted query and returns both in one atomic response. The LSP client should apply the edits and move the cursor to the returned position.

Request:

• method: qlueLs/jump
• params: JumpParams defined as follows:

interface JumpParams extends TextDocumentPositionParams {
    previous?: boolean;
    options?: FormattingOptions;
}

The position in the params is the cursor position in the document as it is before any edits are applied.

Response:

• result: JumpResult | null defined as follows:

interface JumpResult {
    edits: TextEdit[];
    position: Position | null;
}

The edits are expressed against the document as it was in the request and contain the format edits as well as any placeholder text inserted at the jump target. The position is the cursor position in the document after all edits are applied; it is null if no jump target was found.

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