How to Use the q Terminal (REPL)

This page offers a concise, step-by-step guide to launching, interacting with, and configuring the q terminal (REPL) for data exploration and script execution.

The q terminal, also known as the Read–Eval–Print Loop (REPL), is your primary interface for interacting with KDB-X. Whether you're writing quick expressions, exploring data, or running full scripts, the REPL offers a fast and expressive environment for development and analysis. This guide walks you through the key steps to get started with the terminal—from launching a session and evaluating expressions, to viewing results, handling output, using system commands, and safely exiting. It’s designed to help both new and experienced users work efficiently in the q console.

Overview of Steps

1. Start a q session
2. Evaluate expressions in the REPL
3. View data
4. Handle console size and truncation
5. Use command-line options
6. Execute system commands and handle errors
7. Cancel long-running processes
8. Exit the session

1. Start a q session

To start a basic q session:

$ q

You’ll notice a banner showing the version, build date, and environment details:

KDB-X 3.7t 2025.02.14 Copyright (C) 1993-2025 Kx Systems
m64/ 4()core ...
q)

If you prefer, you can also launch it with a script:

$ cat hello.q
1 "hello world";
exit 0

$ q hello.q
hello world

2. Evaluate expressions

The q terminal allows you to directly evaluate q expressions. When you press Enter, it evaluates q expression(s) from right to left and prints the result to the console:

q)sum 44.95 1032 107.15
1184.1
q)acos -1
3.141593

You can define variables using the : operator and reuse them:

q)pi:acos -1
q)pi
3.141593

Use the show keyword to define a variable and simultaneously display it:

q)show pi:acos -1
3.141593

To run an expression without displaying its result, add a semicolon ; at the end. Here's an example using til:

q)til 5
0 1 2 3 4
q)til 5;
q)

The semicolon ; also serves as an expression separator, allowing you to run multiple expressions sequentially on a single line. Although q evaluates individual expressions from right to left, it executes multiple expressions separated by semicolons from left to right:

q)a:5;b:10;100*a+b
1500

In this example:

1. a is assigned the value 5.
2. b is assigned the value 10.
3. 100*a+b is evaluated, resulting in 1500.

k code

The k language is a predecessor of q and shares similar functionality with different syntax. For example:

• The q keyword count is # in k.
• The q keyword first is * in k.

You can use k code within a q session. This is useful for users familiar with the k syntax or those working with legacy k code.

You can run k code in the following ways:

• Prefix code with k).
• Go into and out of the k interpreter, by typing a single backslash (\) in the terminal.
• Load a file of k code using the \l command or launch KDB-X with the file passed as a command line parameter), where the file has the .k extension.

The following example shows how to use count and first in q, and then how to perform the same operations in k:

q)a:3 4 77 100 66 2
q)count a
6
q)first a
3
q)k)#a
6
q)k)*a
3
q)\
  #a
6
  *a
3
  \
q)

3. View data

To view the value of the variable, type its name into the prompt and press Enter.

The session below creates two long integers, a table, and a view. To view each value, type the corresponding variable name in the console:

q)a:22
q)b:33
q)t:([]a:33 44;b: 44 55)
q)v::a+b
q)
q)a
22
q)b
33
q)t
a  b 
-----
33 44
44 55
q)v
55

The KDB-X system commands provide a way to view the names of variables (\v), tables (\a), views (\b), and more.

q)\a
,`t
q)\b
,`v
q)\v
`s#`a`b`t

4. Handle console size and truncation

Large data outputs are truncated automatically in the console. When printing values with many elements, you may notice the output ends with .., indicating that only a portion of the data is displayed.

This behavior helps prevent excessive use of system resources that would be required to print large datasets - potentially billions of elements - to the screen. The full data still exists in memory; it's simply not shown in its entirety.

You can adjust the console size using the system command \c (or command-line option -c).

In the example below, the number of rows is set to a number smaller than the million-row table, followed by using count to check the number of rows in the table:

q)a:([]a:til 1000000;b:til 1000000)
q)\c 5 10000
q)a
a b
---
0 0
1 1
2 2
3 3
4 4
..
q)count a
1000000

5. Use command-line options

You can customize session behavior using various command-line flags. You can include multiple options when launching a q session.

This example uses -q to prevent the banner and session prompt from appearing, whilst listening on port (-p) 5000:

$ q -p 5000 -q

Custom options

You can pass custom options to your session. Access them using .z.x, and parse them into a dictionary with .Q.opt:

$ q -myparam 5432 -custom "data_processing_mode"

q).Q.opt .z.x
myparam| "5432"
custom | "data_processing_mode"

6. Execute system commands and handle errors

System commands

Prefix system commands with a backslash (\). For example:

q)\P
7i

To capture output from a system command:

q)show p:system"P"
7i

Unrecognized system commands are forwarded to the OS:

q)\ls -al ~/.
"total 1560"
"drwxr-xr-x+  87 sjt   staff ..."

Comments

In q, anything following a forward slash (/) on a line is treated as a comment and ignored during execution.

q)2+2 3 4   / add atom to vector
4 5 6
q)/ This is just a comment

Errors

q signals an error if an expression is invalid:

q)2+"a"
'type
  [0]  2+"a"
        ^

If inside a function, it suspends the function and allows investigation:

q){x+2} "xyz"
'type
  [1]  {x+2}
         ^
         
q))x
"xyz"

Abort the suspended function using:

q))\

7. Cancel long running processes

You can interrupt infinite loops or slow computations by pressing Ctrl+C.

For example, running an infinite loop doesn't return control to the terminal for further instructions:

q)while[1b]

Pressing Ctrl+C forces the loop to exit:

q)while[1b]
'stop
  [0]  while[1b]
             ^

8. Exit the session

To exit the session type \\ and press Enter:

q)\\
$

You can also use the exit keyword.

Summary

In this guide, you learned how to:

• Launch an interactive q REPL session
• Execute scripts and commands
• Evaluate expressions and managed outputs
• View data structures and system info
• Customize session behavior with flags
• Handle errors and interrupts gracefully
• Exit cleanly

Next steps

• Explore working with functions
• Integrate q scripts into your workflow or production environment
• Dive into conditional logic and loops
• Check your memory usage as you scale up

Feel free to revisit this guide as you deepen your use of the KDB-X q terminal. Happy querying!