Skip to content

How to use the q terminal (REPL)

This page explains how to work in the q terminal: starting a session, evaluating expressions and suppressing their output, viewing and timing results, controlling how much the console prints, running system commands, recovering from an error, and exiting cleanly.

The q terminal — a read-eval-print loop, or REPL — is the primary interface to KDB-X. It is where you try an expression, look at data, time a query and load a script, and it is worth knowing well: most q is written by evaluating fragments at the prompt until they do the right thing, then moving them into a script.

Start a session

q

The banner reports the version, build date and the environment q found:

KDB-X 5.0 2026.07.23 Copyright (C) 1993-2026 Kx Systems
l64/ 16(24)core 15644MB user machine 127.0.1.1 EXPIRE 2025.09.30 user@site.com COMMUNITY #12345678

Welcome to KDB-X Community Edition!
For Community support, please visit https://kx.com/slack
Tutorials can be found at https://github.com/KxSystems/tutorials
Ready to go beyond the Community Edition? Email preview@kx.com

q)

Naming a script runs it first, so a session can come up with your code already loaded — or do a job and exit:

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

$ q hello.q
hello world

See how to develop scripts for loading at startup versus at run time.

Evaluate expressions

Press Enter and q evaluates the line and prints the result. Expressions evaluate right to left:

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

Assign with :, and the assignment itself prints nothing:

q)pi:acos -1
q)pi
3.141593

show both assigns and displays, which saves repeating the name:

q)show pi:acos -1
3.141593

A trailing semicolon suppresses the result — useful when you want the effect but not a screenful of output:

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

Semicolons also separate expressions on one line. Individual expressions evaluate right to left, but a sequence of them runs left to right:

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

so a is assigned, then b, then 100*a+b is evaluated.

One line, one complete expression

The console evaluates each line on its own, so an expression cannot be continued onto a second line — both halves fail:

q)f:{[x]
'{
  [0]  f:{[x]
            ^
q)  x+1 }
'}
  [0]    x+1 }
             ^

Write it on one line, or put it in a script, where continuation lines are allowed if they are indented and contiguous.

Finding your way around the language

The reference card lists every q keyword, operator and utility on one page.

k code

k is the predecessor of q: the same engine, terser syntax. The q keyword count is # in k, and first is *.

You can run k from a q session three ways — prefix a line with k), switch interpreters with a lone \, or load a file with the .k extension via \l or on the command line:

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

This matters mostly when reading legacy code; \ on its own toggles back.

View data

Type a name to see its value:

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

System commands list what a session holds — \v for variables, \a for tables, \b for views:

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

Time an expression

Two system commands measure, and both belong in the REPL rather than in code.

\t gives elapsed milliseconds, and takes an optional repeat count so a fast expression can be measured meaningfully:

q)\t sum til 1000000
2
q)\t:100 sum til 10000
1

\ts reports time and space — milliseconds and bytes:

q)\ts sum til 1000000
2 8388880

The second figure is often the more interesting one when an expression is slower than expected.

Control the display

Large results are truncated, and a trailing .. marks where. This is deliberate: printing a billion elements would cost far more than the query that produced them. The data is all still there — only the display is cut.

\c sets the console size as rows and columns, and -c does the same at startup:

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

\P controls how many significant digits floats display with — worth remembering before concluding that two floats are equal, or that a value has been rounded.

Pass options on the command line

Session behavior is set with command-line options, and several can be combined. Here q listens on port 5000 with the banner and prompt suppressed:

q -p 5000 -q

Your own options are available too: q keeps anything it does not recognize in .z.x, and .Q.opt parses them into a dictionary.

q -myparam 5432 -custom "data_processing_mode"

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

Each value is a list of strings even when there is only one, which the console display does not make obvious. See handling command-line parameters for how to check that, and for defaults, type conversion and positional arguments.

Run system commands

System commands begin with a backslash:

q)\P
7i

system runs the same thing as a function, so the result can be captured:

q)show p:system"P"
7i

\cd changes the working directory and \pwd reports it. Both matter because relative paths — to scripts and to databases — resolve against it:

q)\pwd
"/home/me/proj"

Anything q does not recognize as a system command is handed to the operating system:

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

A mistyped system command runs as a shell command

That passthrough has no confirmation step. A typo in a backslash command is not rejected — it is executed by the shell, with whatever consequences follow. Be careful with commands typed in a hurry, especially in a production session.

Comments

Everything after a / on a line is a comment. The / must be preceded by whitespace, or it reads as an operator:

q)2+2 3 4   / add atom to vector
4 5 6
q)/ this whole line is a comment

Scripts support comment blocks as well — see comments.

When something goes wrong

An invalid expression signals an error, with a caret under the primitive that failed:

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

If the failure happens inside a function, q does not simply return the error — it suspends there and gives you a prompt inside the frame, indicated by the extra ). The function's arguments and locals are still in scope:

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

\ abandons the suspension and returns to the normal prompt:

q))\
q)

That prompt is a complete debugger — you can walk the call stack, read the locals in each frame, and resume with a value. See how to debug q code.

Interrupt a running expression

Ctrl+C stops a long-running or non-terminating expression, which q reports as 'stop:

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

For a process serving other people, prefer a query timeout to relying on somebody being at the keyboard.

Exit the session

\\ exits:

q)\\
$

exit does the same from within code, and takes a return code — exit 0 for success, which is what a script run as a batch job should end with.

Next steps