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.
Please use [email protected] to raise any questions or feedback.
- Why q for VS Code?
- Get Started
- Connections
- kdb language server
- Execute code
- View results
- Settings
- Shortcuts
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 q with the kdb VS Code extension; see install q.
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:
| item | write q | run q queries | explore results | shared kdb process with kdb Insights |
|---|---|---|---|---|
| kdb+ Personal Edition | yes | yes | yes | no |
| kdb Insights Personal Edition | yes | yes | yes | no |
| kdb Insights Enterprise | yes | yes | yes | yes |
Contact [email protected] 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, k4.lic or 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.
The k4.lic or 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 C:\q, then QHOME is C:\q.
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 can be remote, referred to as an unmanaged q session or a managed q session, which uses the q installed as part of the kdb VS Code extension installation. It runs a child q process from within the extension and is fully managed by the extension. Only one connection can be active at any given time.
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: A new window will open with the type of connection you desire to add, Select Bundled q.
Step 3: The server name / alias will already be set as local.
Step 4: The connection address will be already be set as 127.0.0.1 which corresponds to your 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: Click Create connection to confirm the connection creation
Step 7: Right-click the q bundled process listed under KX:CONNECTIONS, and click Start q process.
Step 8: 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.
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: A new window will open with the type of connection you desire to add, Select My q.
Step 4: Assign a server name / alias. The server name selected cannot be local or insights, as these are reserved for use by Bundled q connections and Insights connections, respectively; e.g. dev
Step 5: Set the connection address 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
Step 7: If authentication is needed, fill in the username and password fields, otherwise, leave these fields blank
Step 8: If TLS is enabled, check the checkbox.
- I want to learn more about TLS encryption.
Step 9: Click Create connection to confirm the connection creation
Upon completion, the localhost connection appears under KX:CONNECTIONS in the left hand panel.
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: A new window will open with the type of connection you desire to add, Select Insights connection.
Step 3: Create a server name / alias; this can be any name, aside from local, which is used by Bundled q connection.
Step 4: Set the hostname. This is the remote address of your kdb Insights Enterprise deployment: e.g https://mykdbinsights.cloudapp.azure.com
Step 5: Click Create connection to confirm the connection creation
Step 6: The kdb Insights Enterprise connection is listed under KX:Connections, with its own icon. Right-click the connection and Connect to Insights
Step 7: 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.
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.
Linting is supported for assignment to reserved words and literals, unused arguments and variables, line length, deprecated date time, too many globals, locals and constants. More linter rules will be supported for future releases.
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
Supports renaming symbols in text editor. Right-click and select "Rename Symbol" on any identifier and extension will rename it.
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.
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
Takes the current file and executes it against the connected q process. Results are displayed in the output window. Returned data are displayed in the kdb results window.
-
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.
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.
Note You can hide or show the full details in the console output. Go to settings of the vscode, search for kdb, check the option "Hide Detailed Console Query Output" (this option is checked by default)
-
A kdb results view
Results are displayed under the kdb results view, which shows the returned data in a table.
q REPL can be started from the command prompt by searching "q REPL".
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.
| Item | Action |
|---|---|
| Hide notification of installation path after first install | yes/no; default no |
| Hide subscription to newsletter after first install | yes/no; default no |
| Insights Enterprise Connections for Explorer | edit JSON settings |
| QHOME directory for q runtime | Display location path of q installation |
| Servers | edit JSON settings |
{
"security.workspace.trust.untrustedFiles": "open",
"editor.accessibilitySupport": "off",
"workbench.colorTheme": "Default Dark+",
"kdb.qHomeDirectory": "C:\\qhomedirectory",
"kdb.hideInstallationNotification": true,
"kdb.servers": {
"23XdJyFk7hXb35Z3yw2vP87HOHFIfy0PDoo5+/G1o7A=": {
"auth": true,
"serverName": "127.0.0.1",
"serverPort": "5001",
"serverAlias": "5001",
"managed": false
}
},
"kdb.hideSubscribeRegistrationNotification": true,
"kdb.insightsEnterpriseConnections": {
"b61Z6R1TGF3vsudDAmo5WWDcGEmRQpmQKoWrluXJD9g=": {
"auth": true,
"alias": "servername.com",
"server": "https://servername.com/"
}
}
}{
"security.workspace.trust.untrustedFiles": "open",
"editor.accessibilitySupport": "off",
"workbench.colorTheme": "Default Dark+",
"kdb.qHomeDirectory": "C:\\qhomedirectory",
"kdb.hideInstallationNotification": true,
"kdb.servers": {
"23XdJyFk7hXb35Z3yw2vP87HOHFIfy0PDoo5+/G1o7A=": {
"auth": true,
"serverName": "127.0.0.1",
"serverPort": "5001",
"serverAlias": "5001",
"managed": false
}
},
"kdb.hideSubscribeRegistrationNotification": true,
"kdb.insightsEnterpriseConnections": {
"b61Z6R1TGF3vsudDAmo5WWDcGEmRQpmQKoWrluXJD9g=": {
"auth": true,
"alias": "servername.com",
"server": "https://servername.com/"
}
}
}| Key | Action |
|---|---|
| F12 | Go to definition |
| Shift + F12 | Go to references |
| Ctrl + Shift + F12 | Find all references |
| Ctrl + D | Execute current selection |
| Ctrl + Shift + D | Execute entire file |
| Ctrl + Shift + R | Run q file in new q instance |
| Key | Action |
|---|---|
| F12 | Go to definition |
| Shift + F12 | Go to references |
| ⌘ + Shift + F12 | Find all references |
| ⌘ + D | Execute current selection |
| ⌘ + Shift + D | Execute entire file |
| ⌘ + Shift + R | Run q file in new q instance |