Command line options

The command line for invoking kdb+ has the form:

q [file] [-option [parameters] … ]

Options -b blocked -q quiet mode -c console size -r replicate -C HTTP size -s secondary threads -e error traps -S random seed -E TLS Server Mode -t timer ticks -g garbage collection -T timeout -l log updates -u disable syscmds -L log sync -u usr-pwd local -m memory domain -U usr-pwd -o UTC offset -w workspace -p listening port -W start week -P display precision -z date format

.z.x (argv), .z.X (raw command line)

file

This is either the script to load (*.q, *.k, *.s), or a file or a directory.

$ q sp.q
KDB+ 3.5t 2017.02.28 Copyright (C) 1993-2017 Kx Systems
m32/ 4()core 8192MB sjt mint.local 192.168.0.39 NONEXPIRE

+`p`city!(`p$`p1`p2`p3`p4`p5`p6`p1`p2;`london`london`london`london`london`lon..
(`s#+(,`color)!,`s#`blue`green`red)!+(,`qty)!,900 1000 1200
+`s`p`qty!(`s$`s1`s1`s1`s2`s3`s4;`p$`p1`p4`p6`p2`p2`p4;300 200 100 400 200 300)
q)

Operating systems may create hidden files, such as .DS_Store, that block loading of a directory.

-b (blocked)

-b

Block write-access to a kdb+ database, for any handle context (.z.w) other than 0. Blocks hdel keyword (since V4.1t 2021.10.13, V4.0 2023.08.11). Blocks hopen of a file (since 4.1t 2021.10.13, 4.0 2023.08.11)

~/q$ q -b

q)aa:([]bb:til 4)
q)\p 5001
q)

and in another task

q)h:hopen 5001
q)h"count aa"
4
q)h"aa:10#aa"
'noupdate
q)

Use \_ to check if client write-access is blocked:

~/q$ q -b
..
q)\_
1

-c (console size)

-c r c

Set console maximum rows and columns, default 25 80.

\c system command for detail

-C (HTTP size)

-C r c

Set HTTP display maximum rows and columns.

\C system command for detail

-e (error traps)

-e [0|1|2]

Sets error-trapping mode. The default is 0 (off).

\e system command for detail

-E (TLS Server Mode)

-E 0        / plain
-E 1        / plain & TLS
-E 2        / TLS only

Since V3.4.

\E system command
SSL/TLS

-g (garbage collection)

-g 0        / deferred (default)
-g 1        / immediate

Sets garbage-collection mode.

\g system command for detail

-l (log updates)

-l

Log updates to filesystem.

Logging

-L (log sync)

-L

As -l, but sync logging.

Logging

-m (memory-domain)

-m path

Memory can be backed by a filesystem, allowing use of DAX-enabled filesystems (e.g. AppDirect) as a non-persistent memory extension for kdb+.

This command-line option directs kdb+ to use the filesystem path specified as a separate memory domain. This splits every thread’s heap into two:

domain description
--------------------------------------------------------------------------
0      regular anonymous memory, active and used for all allocs by default
1      filesystem-backed memory

The .m namespace is reserved for objects in memory domain 1, however names from other namespaces can reference them too, e.g. a:.m.a:1 2 3

-o (UTC offset)

-o N

Sets local time offset as N hours from UTC, or minutes if abs[N]>23 (Affects .z.Z)

\o system command for detail

-p (listening port)

Set listening port

-p [rp,][hostname:](portnumber|servicename)

See Listening port for detail.

hopen
\p system command
Multithreaded input mode, Changes in 3.5
Socket sharding with kdb+ and Linux

-P (display precision)

-P N

Display precision for floating-point numbers, i.e. the number of digits shown.

\P system command for detail

-q (quiet mode)

-q

Quiet, i.e. no startup banner text or session prompts. Typically used where no console is required.

~/q$ q
KDB+ 3.5t 2017.02.28 Copyright (C) 1993-2017 Kx Systems
…

q)2+2
4
q)

and with -q

~/q$ q -q

2+2
4

.z.q (quiet mode)

-r (replicate)

-r :host:port[:user[:password]]

Replicate from :host:port.

\r system command

-s (secondary threads)

-s N

Number of secondary threads or processes available for parallel processing.

\s system command for detail

-S (random seed)

-S N

Sets N as value of random seed.

\S system command for detail
Roll, Deal

-t (timer ticks)

-t N

Period in milliseconds between timer ticks. Default is 0, for no timer.

\t system command for detail

-T (timeout)

-T N

Timeout in seconds for client queries, i.e. maximum time a client call will execute. Default is 0, for no timeout.

\T system command for detail

-u (disable syscmds)

-u (usr-pwd local)

-U (usr-pwd)

-u 1        / blocks system functions and file access
-U file     / sets password file, blocks \x
-u file     / both the above

-u 1 disables

• system commands from a remote (signals 'access), including exit via "\\"
• access to files outside the current directory for any handle context (.z.w) other than 0. Segmented database partitions using directories outside the current working directory can be enabled using the method described here.
• hopen on a fifo (since 4.1t 2021.10.13, 4.0 2023.08.11)
• hopen of a file (since 4.1t 2021.10.13, 4.0 2023.08.11)
• the exit keyword (since 4.1t 2021.07.12)
• the hdel keyword (since V4.1t 2021.10.13, V4.0 2023.08.11)

Only a simple protection against “wrong” queries

For example, setting a system command in .z.ts and starting the timer still works. The right system command could for example expose a terminal, so the user running the database could be fully impersonated and compromised from then on.

-U file

• sets a password file
• disables \x (even on the local console)

The password file is a text file with one credential on each line. (No trailing blank line/s.)

user1:password1
user2:password2

The password can be

• plain text
• an MD5 hash of the password
• an SHA-1 hash of the password (since V4.0 2020.03.17)

q)raze string md5 "this is my password"
"210d53992dff432ec1b1a9698af9da16"
q)raze string -33!"mypassword" / -33! calculates sha1
"91dfd9ddb4198affc5c194cd8ce6d338fde470e2"

Internal function -33!

-u file combines the above, i.e. -u file is equivalent to -u 1 -U file.

-w (workspace)

-w N

Workspace limit in MB for the heap across threads for memory domain 0. Default is 0: no limit.

\w system command for detail
.Q.w

Before V4.0 2020.03.17 this command set the limit for the heap per thread.

Other ways to limit resources

On Linux systems, administrators might prefer cgroups as a way of limiting resources.

On Unix systems, memory usage can be constrained using ulimit, e.g.

ulimit -v 262144

limits virtual address space to 256MB.

-W (start week)

-W N

Set the start-of-week offset, where 0 is Saturday. The default is 2, i.e Monday.

\W system command for detail

-z (date format)

-z [0|1]

Set the format for "D"$ date parsing: 0 for mm/dd/yyyy and 1 for dd/mm/yyyy.

\z system command

xkcd.com