Java REST service for connecting to kdb+
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


An open source REST service written in java 8 used to connect to an instance of kdb using JSON. The REST service can provide a single query to run or call a function predefined on the instance of kdb.

Pre-requisite Configuration


There is an file in the resources folder, connect the rest service and the instance of kdb by updating the properties below:

The requests are sent in HTTPS format and to provide this the project has a self-signed certifiate embedded within. It is strongly recommended that you add your own certificate. Updating the certificate will require an update to the following properties in


The q-REST service uses basic authentication and is using a single username and password which are configured in the file:


These value are provided within the header of the request, it is strongly recommended to invoke your own security if you use the project.


The q-REST service provides two endpoints: executeFunction and executeQuery.

ExecuteFunction Request

The executeFunction provides a means to call a predefined function and pass parameters to the kdb instance. For example this is the format of a request calling a function called plus which passes two arguments labelled "xarg" and "yarg" with values 96.3 and 9.7:

e.g. FunctionRequest

"function_name" : "plus",
"arguments" : 
            "xarg" : "96.3",
            "yarg" : "9.7"
ExecuteQuery Request

The executeQuery provides a means to provide a query to the kdb instance, by default this endpoint is disabled using the property freeform.query.mode.enabled, to enable change the value to true. For example this is the format of a synchronous query request where the user expects a response to be returned:

e.g. QueryRequest

    "type" : "sync",   
    "query" : "select from table",
    "response" : true
Response from q-REST API

The json response for the endpoint calls will comprise of 4 parts: result, requestTime, responseTime and success.

  • Result is the response returned by KDB with some additional parsing.

  • RequestTime is the time the time the request began processing on the api.

  • ResponseTime is the time the response was returned from the api.

  • Success is a boolean which lets user know if the call to kdb was a success.

e.g. "query" : "([]a:enlist\"hello world\")" this should return a single item

        "result": [
                "a": "hello world"
        "requestTime": "2018-06-14T09:05:12.513Z",
        "responseTime": "2018-06-14T09:05:12.528Z",
        "success": true

e.g. "query" : "([]a:(\"hello\";\"world\"))" this should return a list of strings

        "result": [
                "a": "hello"
                "a": "world"
        "requestTime": "2018-06-14T09:05:51.610Z",
        "responseTime": "2018-06-14T09:05:51.620Z",
        "success": true

Failure response will follow a similar pattern except result will the error returned

e.g "query" : "([]a:enlist hello world)" Failure response (query should have quotes around the hello world therefore KDB fails) will follow a similar pattern except result will be the error returned

        "result": "error: failed to run query on server localhost:34203: world",
        "requestTime": "2018-06-14T09:04:28.634Z",
        "responseTime": "2018-06-14T09:04:28.649Z",
        "success": false


Pre-requisite: java 8 installed

  1. Configure your own file to point to your specific kdb instance and create an active profile:
  1. Download the most recent jar from release section of github master (

  2. Run following command from command prompt (ensure you select your file created in step 1):

    java -jar -Dspring.config.location=PathToFile\ q-REST-1.0.0_RELEASE.jar
  • would be the profile you wish to run the application with which would have its own application-{profileName}.properties file.

  • -Dspring.config.location would be the location of the custom properties file.

Alternatively, you can download the source code from git hub, update the project with your changes, run a maven build, then run project from your chosen ide by executing the main SpringBoot application class as seen within project.

Project may also be run as a docker image, please find a sample Dockerfile defined within project.

Swagger UI

The application has incorporated the Swagger UI utilities, to access the swagger page load the application and hit the swagger url:



The branch is currently locked down and will require a pull request reviewed by a member of the AquaQ team before any changes can be committed.