Executing a query using web-sockets

It is possible to use web-sockets to execute a query and get status information from the server while the query is executing.

Url:

ws/query

The following example uses wscat to execute a query.

Example:
wscat -H 'Authorization: Bearer  <access token>' -c  ws://localhost:54321/ws/query
Connected (press CTRL+C to quit)
> {"type": "queryRequest", "query": "SELECT * FROM [\"Hello\", \"World\"] ", "settings": {"X-RAW-output-format": "hjson"}}
< {"type":"userMessage","level":"debug","message":"Starting query compilation"}
< {"type":"userMessage","level":"debug","message":"Finished query compilation"}
< {"type":"userMessage","level":"debug","message":"Starting query execution"}
< {"type":"querySuccess","properties":{}}
< {"type":"userMessage","level":"debug","message":"Starting writing results"}
< "Hello"
"World"
< {"type":"userMessage","level":"debug","message":"Finished query execution"}
< {"type":"userMessage","level":"debug","message":"Finished writing results"}
< {"type":"queryStreamingEnd"}
<
Disconnected (code: 1000, reason: "")
Please note that:
  • Binary frames from the server will contain query results and can, for instance, be appended to a file.

  • Text frames are used as a json protocol to get status information about the query.

The rest of this chapter will describe all possible json messages to and from the server.

Messages to the server

Query request

Execute query request.

query

string

the query to execute

settings

record

key-value pairs string->string of settings
for this query for e.g.:
{"X-RAW-output-format": "hjson"}

type

string

literal string queryRequest

Example:
{"type": "queryRequest", "query": "SELECT * FROM [\"Hello\", \"World\"] ", "settings": {"X-RAW-output-format": "hjson"}}

Messages from the server:

User message

Message with status information on the query.

level

string

log level: debug, info, warning or error

message

string

the message

type

string

literal string userMessage

Example:
{"type":"userMessage","level":"debug","message":"Finished query execution"}

Query success

Sent when the query executed successfully.

properties

record

type

string

literal string querySuccess

Example:
{"type":"querySuccess","properties":{}}

Invalid Query

Sent when the query has errors.

errors

List[ExecutorError]

list of executor errors

type

string

literal string invalidQuery

Example:
{
    "type": "invalidQuery"
    "errors": [{
         "message":"bb is not declared", "positions":[{
            "begin":{ "line":1, "column":1 },
            "end":{ "line":1, "column": 3 }
         }]
    }]
}

Query streaming end

Sent before closing the connection after the execution of a query.

type

string

literal string queryStreamingEnd

Example:
{"type":"queryStreamingEnd"}

Invalid Message

Sent when if the message is invalid for example unknown message type or a malformed json string.

error

string

error message

type

string

literal string invalidMessage

Example:
{"type":"invalidMessage","error":"Error processing message: Unrecognized token 'll'"}