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 {
    service: BackendService;
    requestMethod?: "GET" | "POST";
    default: boolean;
    prefixMap?: Record<string, string>;
    queries?: Record<string, string>;
}

interface BackendService {
    name: string;
    url: string;
    healthCheckUrl?: string;
    engine?: "QLever" | "GraphDB" | "Virtuoso" | "MillenniumDB" | "Blazegraph" | "Jena";
}

getBackend

Get information about the currently active default backend.

Request:

• method: qlueLs/getBackend
• params: none

Response:

• result: BackendService | null

interface BackendService {
    name: string;
    url: string;
    healthCheckUrl?: string;
    engine?: "QLever" | "GraphDB" | "Virtuoso" | "MillenniumDB" | "Blazegraph" | "Jena";
}

listBackends

List all registered backends.

Request:

• method: qlueLs/listBackends
• params: none

Response:

• result: BackendService[]

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)

Navigation

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

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