kdb Visual Studio Code extension¶
This is a companion extension for kdb developers to edit q files, connect to kdb processes, and run queries. This VS Code extension can be used alongside kdb Insights Enterprise when using a shared kdb process.
Why q for VS Code?¶
With the kdb VS Code extension you can:
- Install q.
- Write q syntax with support for predict and autocomplete.
- Execute q from a single line of code, code block or q file.
- Write and execute q code against kdb Insights Enterprise.
- View results from your queries.
If you have an existing q installation, you will see the message
q runtime installed and can go directly to adding connections.
If you are new to q, you can install the pre-packaged q in the kdb VS Code extension; open Install q with VS Code. Alternatively, install q locally, but remember to start the q process before creating the connection in the VS Code extension; you don't have to worry about starting the q process if using Install q with VS Code.
Step 1: Download the latest version of kdb+. Different versions of kdb+ are available, and the version you download will determine the supported features in VS Code:
|run q queries
|shared kdb process with kdb Insights
|kdb+ Personal Edition
|kdb Insights Personal Edition
|kdb Insights Enterprise Personal Edition
Contact email@example.com for commercial kdb licensing.
Step 2: After registering, you will receive an email with a link to download an installation file.
Extract the file to a directory; instructions are available for Linux, macOS and Windows.
I want to learn more about kdb+ installation
Step 3: The welcome email will also have your kdb,
kc.lic license as an attachment. We recommend you add your kdb license to your q installation directory, or
QHOME, and define this location in your environment variables. It is essential you define an environment variable for VS Code to recognize a valid license.
Note: If your kdb license is stored outside of your q (
QHOME) directory, create a
QLIC environment variable instead.
I want to learn how to define a QHOME environment variable.
You can install q from the VS Code extension. You still need to register for kdb Insights Personal Edition to obtain a license and VS Code will guide you through steps to install. The license will be incorporated as part of the kdb VS Code extension, although a
QHOME environment variable is still required if you wish to utilise the q installation outside of VS Code.
Step 1: Click
Install new instance from the prompt if no q installation is flagged. If this prompt is cancelled, then use the aforementioned install q.
Step 2: If you have already registered for kdb+ or kdb Insights, then choose
Select/Enter a license. If you haven't registered, choose
Acquire license, this will open a dialog with a redirect link to register for kdb Insights Personal Edition.
Step 3: With the license secured, you can then link this to VS Code by either
pasting license string or
selecting license file from your PC; the latter method is recommended for new users.
The base64 encoded license string can be found in the welcome email received after registration, under the download link for the license file.
kc.lic license file can be downloaded to your PC.
Step 4: Set a
QHOME environment variable to the location used by the kdb VS Code install. A notification dialog displays the location of q, as do the extension settings. This will allows you to use q outside of VSCode.
If q is installed at
To finish, a prompt is offered with an opt-in to receive a newsletter.
The kdb VS Code extension allows you to connect VS Code to a q process. This connection can be remote, referred to as an unmanaged q session, and must be started before creating a connection in the kdb VS Code extension. A managed q session connection uses a child q process installed and fully managed by the kdb VS Code extension. Additionally, a kdb Insights Enterprise connection can be added if using kdb Insights Enterprise UI.
Only one connection can be active at any given time. Also, it may be necessary to reconnect if you switch away from the extension or are timed out.
Step 1: Identify the remote location of a running process. The hostname and port will be required along with any authentication information.
Step 2: Within the kdb VS Code extension, click connect to kdb server, or Add new connection** from the *CONNECTIONS context menu.
Step 3: When prompted to select the kdb type, choose Enter a kdb endpoint.
Step 5: Set the hostname or ip address of the kdb server; e.g. localhost.
Step 6: Set the port used by the kdb server; e.g. 5001.
I want to learn more about setting a q port
Upon completion, the localhost connection appears under KX:CONNECTIONS in the left hand panel.
Step 7: Right-click the connection to connect kdb server. Ensure the q process is running.
If the connection requires authentication, define user and password access from Add Authentication in the dropdown menu; click Enter for each input.
Enable TLS encryption from the dropdown menu if required; default is false.
I want to learn more about TLS encryption.
This runs a q session using the existing kdb installed as part of the kdb VS Code extension.
Step 1: Click connect to kdb server or Add new connection from the CONNECTIONS context menu.
Step 2: When prompted to select the kdb type, choose Enter a kdb endpoint.
Step 3: Set the server name / alias to
Step 4: Set the hostname; e.g. localhost
Step 5: Set the port for the kdb server. Ensure the port used doesn't conflict with any other running q process; e.g. 5002
I want to learn more about setting a q port
Step 6: Right-click the managed q process listed under KX:CONNECTIONS, and click Start q process.
Step 7: From the same right-click menu, click Connect kdb server. This connects to the child q process running inside the kdb VS Code extension.
If you close the extension, the connection to the child q process also closes.
For kdb Insights Enterprise, the kdb VS Code extension is using a shared kdb process. Unlike for a managed q session, you must have kdb Insights Enterprise Personal Edition running before using these connections.
Step 1: Click connect to kdb server.
Step 2: When prompted to select a kdb type, choose Connect to kdb insights
Step 3: Create a server name / alias; this can be any name, aside from
local, which is used by the managed q session.
Step 4: Set the hostname. This is the remote address of your kdb Insights Enterprise deployment: e.g
Step 5: The kdb Insights Enterprise connection is listed under KX:Connections, with its own icon. Right-click the connection and Connect to Insights
Step 6: The kdb VS Code extension runs an authentication step with the remote kdb Insights Enterprise process; sign-in to kdb Insights Enterprise.
After a successful connection to a kdb Insights Enterprise process, a new DATA SOURCES panel will become available in the kdb VS Code extension.
Once connected to a q process, go to execute code.
kdb language server¶
A kdb language server is bundled with the kdb VS Code extension. It offers various common features to aid in the development of kdb code within VS Code, including:
The extension provides keyword syntax highlighting, comments and linting help.
While developing q scripts, the kdb VS Code extension supports:
- Go to definition
Navigate to the definition of a function
- Find/go to all references
View references of a function both on the side view and inline with the editor
- Keyword auto complete for the q language
- Autocomplete for local and remotely connected q processes
Leaning on VS Code's extensive integrations with SCMs, all code is typically stored and loaded into a VS Code workspace. From there, the kdb VS Code extension allows you execute code against both kdb processes, and kdb Insights Enterprise endpoints.
kdb process executing code¶
There are three options available from the right-click menu for executing code:
Execute current selection
Takes the current selection (or current line if nothing is selected) and executes it against the connected q process. Results are displayed in the output window and/or the kdb results window.
Execute entire file
Run q file in new q instance
If q is installed and executable from the terminal, you can execute an entire script on a newly launched q instance. Executing a file on a new instance is done in the terminal, and allows interrogation of the active q process from the terminal window.
Insights query execution¶
kdb Insights Enterprise offers enhanced connectivity and enterprise level API endpoints, providing additional means to query data and interact with kdb Insights Enterprise that are not available with standard kdb processes. You must have an instance of kdb Insights Enterprise running, and have created a connection within the kdb VS Code extension.
Similarly, you can execute arbitrary code against kdb Insights Enterprise. The code is executed on a user-specific sandbox process within the kdb Insights Enterprise deploy. The sandbox is instanciated upon the first request to execute code when connected to a kdb Insights Enterprise connection. It remains active until timed out or until you log out.
kdb Insights Enterprise supports the use of data sources, where you can build a query within VS Code and run it against the kdb Insights Enterprise API endpoints. The UI helps you to build a query based on the available API on your instance of kdb Insights Enterprise, parameterize it and return the data results to the output or kdb results window.
To create a data source:
In the Data Sources view, click the Options button and select 'Add Data Source'.
Click on the created data source where the name, API and parameterization can be applied.
Click Save to persist the data source to the VS Code workspace.
To run a data source, click 'Run' and the results populate the output and kdb results windows.
In addition to API queries, if the query environment is enabled on the deployed instance of kdb Insights Enterprise, qSQL and SQL queries can be used within a data source with the appropriate parameterization.
You can use a data source to populate a scratchpad with a dataset, allowing you to build complex APIs and pipelines within VS Code and kdb Insights Enterprise.
To do this:
Create a data source and execute it using the 'Populate Scratchpad' button. The scratchpad is populated.
At the prompt, provide a variable to populate your own scratchpad instance with the data.
Return to VS Code and execute q code against the data in your scratchpad.
All query executions happen remotely from the kdb VS Code extension either against a running q process or against an instance of kdb Insights Enterprise. The results, successful or otherwise, are returned to VS Code as:
An output view
The output view displays results as they are received by the kdb VS Code extension. It includes the query executed, a timestamp and the results.
Note: You can enable/disable auto-scrolling in the VS Code settings. This setting determines whether the output view scrolls to the latest results.
A kdb results view
Results are displayed under the kdb results view, which shows the returned data in a table.
To update kdb VS Code settings, search for
kdb from Preferences > Settings, or right-click the settings icon in kdb VS Code marketplace panel and choose Extension Settings.
|Hide notification of installation path after first install
|Hide subscription to newsletter after first install
|Insights Enterprise Connections for Explorer
|edit JSON settings
|QHOME directory for q runtime
|Display location path of q installation
|edit JSON settings
Insights Enterprise Connections for Explorer¶
Settings used by the Insights Enterprise connection for the VS Code extension. These settings are defined in the setup between Insights Enterprise UI and VS Code extension.
"workbench.colorTheme": "Default Dark+",
This is a record of the settings used by server connections for the VS Code extension, and are defined by the connection setup process.
"workbench.colorTheme": "Default Dark+",
|Go to definition
|Shift + F12
|Go to references
|Cmd/Ctrl + Shift + F12
|Find all references
|Ctrl + Q
|Execute current selection
|Ctrl + Shift + Q
|Execute entire file
|Ctrl + Shift + R
|Run q file in new q instance