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.

Request:

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

Response:

result: null
error: present when the backend configuration could not be loaded

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: a partial Settings object

The provided values are merged into the current settings: every key that is present overrides the current value, every key that is omitted keeps it. Only the settings that actually change have to be sent.

{ "format": { "alignPredicates": false } }

Objects are merged recursively, all other values — including arrays — are replaced. To empty a list, send an empty array; to unset an optional section, send null:

{ "replacements": null }

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)

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

Diagnostics

completionQuery

Report a completion query that was just rendered and (attempted to be) executed. Purely diagnostic: it lets the client show the rendered query, its result size and its failure reason while a completion template is being edited.

Note

This is a server-to-client notification, only available in WASM builds. It is sent for every completion query, including those that fail to render.

Notification (server to client):

method: qlueLs/completionQuery
params: CompletionQueryParams defined as follows:

interface CompletionQueryParams {
    requestId: number | string;  // Id of the `textDocument/completion` request
    template: string;      // Template name, as registered in tera: `{backend}-{template}`
    query: string;         // The rendered query. Empty if rendering the template failed
    url: string;           // The endpoint the query was sent to
    durationMs: number;
    resultCount?: number;  // Number of bindings returned, before search-term filtering
    error?: string;        // Present when rendering or executing the query failed
}

Exactly one of resultCount and error is present.

Notifications are correlated by requestId, not one per completion request:

A location can dispatch several templates for one request — predicate completions race a context-sensitive and a context-insensitive query, and only the first result to arrive reaches the client. Both are reported, under the same requestId, and the losing one may arrive after the completion response.
Locations that are answered without a backend (keywords, variables, aggregates) send no notification at all.

LSP Extensions

Backend Management

addBackend

getBackend

listBackends

updateDefaultBackend

pingBackend

Settings

defaultSettings

changeSettings

Query Execution

executeOperation

cancelQuery

partialResult

Navigation

jump

parseTree

identifyOperationType

Diagnostics

completionQuery