Reference¶

You can access most of this material using pydoc or the built-in help method.

class K: Proxies for kdb+ objects
namespace q: A portal to kdb+
pyq.kerr: alias of error

class K¶

>>> q('2005.01.01 2005.12.04')
k('2005.01.01 2005.12.04')

Iteration over simple lists produces Python objects

>>> list(q("`a`b`c`d"))
['a', 'b', 'c', 'd']

Iteration over q tables produces q dictionaries

>>> list(q("([]a:`x`y`z;b:1 2 3)"))
[k('`a`b!(`x;1)'), k('`a`b!(`y;2)'), k('`a`b!(`z;3)')]

Iteration over a q dictionary iterates over its key

>>> list(q('`a`b!1 2'))
['a', 'b']

As a consequence, iteration over a keyed table is the same as iteration over its key table

>>> list(q("([a:`x`y`z]b:1 2 3)"))
[k('(,`a)!,`x'), k('(,`a)!,`y'), k('(,`a)!,`z')]

Callbacks into Python

>>> def f(x, y):
...     return x + y
>>> q('{[f]f(1;2)}', f)
k('3')

Buffer protocol¶

The following session illustrates how the buffer protocol implemented by K objects can be used to write data from Python streams directly to kdb+.

Create a list of chars in kdb+

>>> x = kp('xxxxxx')

Open a pair of file descriptors

>>> r, w = os.pipe()

Write 6 bytes to the write end

>>> os.write(w, b'abcdef')
6

Read from the read-end into x

>>> f = os.fdopen(r, mode='rb')
>>> f.readinto(x)
6

Now x contains the bytes that were sent through the pipe

>>> x
k('"abcdef"')

Close the descriptors and the stream

>>> os.close(w); f.close()

Low-level interface¶

The K type provides a set of low-level functions that are similar to the C API provided by the k.h header. The C API functions that return K objects in C are implemented as class methods that return instances of K type.

Atoms:

>>> K._kb(True), K._kg(5), K._kh(42), K._ki(-3), K._kj(2**40)
(k('1b'), k('0x05'), k('42h'), k('-3i'), k('1099511627776'))

>>> K._ke(3.5), K._kf(1.0), K._kc(b'x'), K._ks('xyz')
(k('3.5e'), k('1f'), k('"x"'), k('`xyz'))

>>> K._kd(0), K._kz(0.0), K._kt(0)
(k('2000.01.01'), k('2000.01.01T00:00:00.000'), k('00:00:00.000'))

Tables and dictionaries:

>>> x = K._xD(k('`a`b`c'), k('1 2 3')); x, K._xT(x)
(k('`a`b`c!1 2 3'), k('+`a`b`c!1 2 3'))

Keyed table:

>>> t = K._xD(K._xT(K._xD(k(",`a"), k(",1 2 3"))),
...           K._xT(K._xD(k(",`b"), k(",10 20 30"))))
>>> K._ktd(t)
k('+`a`b!(1 2 3;10 20 30)')

K objects can be used in Python arithmetic expressions.

>>> x, y, z = map(K, (1, 2, 3))
>>> print(x + y, x * y,
...       z/y, x|y, x&y, abs(-z))  
3 2 1.5 2 1 3

Mixing K objects with Python numbers is allowed.

>>> 1/q('1 2 4')
k('1 0.5 0.25')
>>> q.til(5)**2
k('0 1 4 9 16f')

__call__: Call self as a function
__contains__(item): membership test

>>> 1 in q('1 2 3')
True
>>> 'abc' not in q('(1;2.0;`abc)')
False

__eq__(other): Test equality

>>> K(1) == K(1)
True
>>> K(1) == None
False

__float__(): Converts K scalars to Python float

>>> [float(q(x)) for x in '1b 2h 3 4e `5 6.0 2000.01.08'.split()]
[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0]

__get__: Return an attribute of instance, which is of type owner.
__getattr__(a): Table columns can be accessed via dot notation

>>> q("([]a:1 2 3; b:10 20 30)").a
k('1 2 3')

__getitem__(x): Item from a list

>>> k("10 20 30 40 50")[k("1 3")]
k('20 40')
&gt;&gt;&gt; k("`a`b`c!1 2 3")['b']
2

__int__(): Converts K scalars to Python int

>>> [int(q(x)) for x in '1b 2h 3 4e `5 6.0 2000.01.08'.split()]
[1, 2, 3, 4, 5, 6, 7]

exec(columns=(), by=(), where=(), **kwds*_): exec from self

>>> t = q('([]a:1 2 3; b:10 20 30)')
>>> t.exec_('a', where='b > 10').show()
2 3

keys()

Returns q(‘key’, self)

Among other uses, enables interoperability between q and Python dicts.


>>> from collections import OrderedDict
>>> OrderedDict(q('`a`b!1 2'))
OrderedDict([('a', 1), ('b', 2)])
>>> d = {}; d.update(q('`a`b!1 2'))
>>> list(sorted(d.items()))
[('a', 1), ('b', 2)]

select(columns=(), by=(), where=(), **kwds)

select from self

>>> t = q('([]a:1 2 3; b:10 20 30)')
>>> t.select('a', where='b > 20').show()
a
-
3

show(start=0, geometry=None, output=None)

Pretty-print data to the console

(similar to q.show, but uses Python stdout by default)


>>> x = q('([k:`x`y`z]a:1 2 3;b:10 20 30)')
>>> x.show()

k| a b
-| ----
x| 1 10
y| 2 20
z| 3 30

The first optional argument, start specifies the first row to be printed (negative means from the end)


>>> x.show(2) 
k| a b
-| ----
z| 3 30
>>> x.show(-2)

k| a b
-| ----
y| 2 20
z| 3 30

The geometry is the height and width of the console


>>> x.show(geometry=[4, 6])
k| a..
-| -..
x| 1..
..

update(columns=(), by=(), where=(), **kwds)

update from self


>>> t = q('([]a:1 2 3; b:10 20 30)')
>>> t.update('a*2',
...          where='b > 20').show()

a b

1 10
2 20
6 30

namespace q¶

pyq.q

q.__call__(m=None, *args)

Execute q code.

When called without arguments in an interactive session, q() presents a q) prompt where user can interact with kdb+ using q language commands.

The first argument to that may be given to q() should be a string containing a q language expression. If that expression evaluates to a function, the arguments to this function can be provided as additional arguments to q().

For example, the following passes a list and a number to the q ? (find) function:


>>> q('?', [1, 2, 3], 2)
k('1')

K and q functions¶

K class	q namespace	q	function
`K.abs()`	`q.abs()`	`abs`	absolute value The `abs` function computes the absolute value of its argument. Null is returned if the argument is null. `>>> q.abs([-1, 0, 1, None])` `k('1 0 1 0N')`
`K.acos()`	`q.acos()`	`acos`	arc cosine
`K.aj()`	`q.aj()`	`aj`	as-of join
`K.aj0()`	`q.aj0()`	`aj`	as-of join
`K.all()`	`q.all()`	`all`	all nonzero
`K.and_()`	`q.and_()`	`and`	and
`K.any()`	`q.any()`	`any`	any item is non-zero
`K.asc()`	`q.asc()`	`asc`	ascending sort
`K.asin()`	`q.asin()`	`asin`	arc sine
`K.asof()`	`q.asof()`	`asof`	as-of operator
`K.atan()`	`q.atan()`	`atan`	arc tangent
`K.attr()`	`q.attr()`	`attr`	attributes
`K.avg()`	`q.avg()`	`avg`	arithmetic mean
`K.avgs()`	`q.avgs()`	`avgs`	running averages
`K.bin()`	`q.bin()`	`bin`	binary search
`K.binr()`	`q.binr()`	`bin`	binary search
`K.ceiling()`	`q.ceiling()`	`ceiling`	lowest integer above
`K.cols()`	`q.cols()`	`cols`	column names of a table
`K.cor()`	`q.cor()`	`cor`	correlation
`K.cos()`	`q.cos()`	`cos`	cosine
`K.count()`	`q.count()`	`count`	number of items
`K.cov()`	`q.cov()`	`cov`	statistical covariance
`K.cross()`	`q.cross()`	`cross`	cross product
`K.csv()`	`q.csv()`	`csv`	comma delimiter
`K.cut()`	`q.cut()`	`cut`	cut
`K.deltas()`	`q.deltas()`	`deltas`	differences between consecutive pairs
`K.desc()`	`q.desc()`	`desc`	descending sort
`K.dev()`	`q.dev()`	`dev`	standard deviation
`K.differ()`	`q.differ()`	`differ`	flag differences in consecutive pairs
`K.distinct()`	`q.distinct()`	`distinct`	unique items
`K.div()`	`q.div()`	`div`	integer division
`K.dsave()`	`q.dsave()`	`dsave`	save global tables to disk
`K.ej()`	`q.ej()`	`ej`	equi-join
`K.ema()`	`q.ema()`	`ema`	exponentially-weighted moving average
`K.ema()`	`q.ema()`	`ema`	exponentially-weighted moving average
`K.enlist()`	`q.enlist()`	`enlist`	arguments as a list
`K.eval()`	`q.eval()`	`eval`	evaluate a parse tree
`K.except_()`	`q.except_()`	`except`	left argument without items in right argument
`K.exp()`	`q.exp()`	`exp`	power of e
`K.fby()`	`q.fby()`	`fby`	filter-by
`K.fills()`	`q.fills()`	`fills`	forward-fill nulls
`K.first()`	`q.first()`	`first`	first item
`K.fkeys()`	`q.fkeys()`	`fkeys`	foreign-key columns mapped to their tables
`K.flip()`	`q.flip()`	`flip`	transpose
`K.floor()`	`q.floor()`	`floor`	greatest integer less than argument
`K.get()`	`q.get()`	`get`	get
`K.getenv()`	`q.getenv()`	`getenv`	value of an environment variable
`K.group()`	`q.group()`	`group`	dictionary of distinct items
`K.gtime()`	`q.gtime()`	`gtime`	UTC timestamp
`K.hclose()`	`q.hclose()`	`hclose`	close a file or process
`K.hcount()`	`q.hcount()`	`hcount`	size of a file
`K.hdel()`	`q.hdel()`	`hdel`	delete a file
`K.hopen()`	`q.hopen()`	`hopen`	open a file
`K.hsym()`	`q.hsym()`	`hsym`	convert symbol to filename or IP address
`K.iasc()`	`q.iasc()`	`iasc`	indices of ascending sort
`K.idesc()`	`q.idesc()`	`idesc`	indices of descending sort
`K.ij()`	`q.ij()`	`ij`	inner join
`K.ijf()`	`q.ijf()`	`ijf`	The ijf function.
`K.in_()`	`q.in_()`	`in`	membership
`K.insert()`	`q.insert()`	`insert`	append records to a table
`K.inter()`	`q.inter()`	`inter`	items common to both arguments
`K.inv()`	`q.inv()`	`inv`	matrix inverse
`K.key()`	`q.key()`	`key`	key
`K.keys()`	`q.keys()`	`keys`	names of a table’s columns
`K.last()`	`q.last()`	`last`	last item
`K.like()`	`q.like()`	`like`	pattern matching
`K.lj()`	`q.lj()`	`lj`	left join
`K.ljf()`	`q.ljf()`	`ljf`	left join
`K.load()`	`q.load()`	`load`	load binary data
`K.log()`	`q.log()`	`log`	natural logarithm
`K.lower()`	`q.lower()`	`lower`	lower case
`K.lsq()`	`q.lsq()`	`lsq`	least squares matrix divide
`K.ltime()`	`q.ltime()`	`ltime`	local timestamp
`K.ltrim()`	`q.ltrim()`	`ltrim`	function remove leading spaces
`K.mavg()`	`q.mavg()`	`mavg`	moving average
`K.max()`	`q.max()`	`max`	maximum
`K.maxs()`	`q.maxs()`	`maxs`	maxima of preceding items
`K.mcount()`	`q.mcount()`	`mcount`	moving count
`K.md5()`	`q.md5()`	`md5`	MD5 hash
`K.mdev()`	`q.mdev()`	`mdev`	moving deviation
`K.med()`	`q.med()`	`med`	median
`K.meta()`	`q.meta()`	`meta`	metadata of a table
`K.min()`	`q.min()`	`min`	minimum
`K.mins()`	`q.mins()`	`mins`	minimum of preceding items
`K.mmax()`	`q.mmax()`	`mmax`	moving maxima
`K.mmin()`	`q.mmin()`	`mmin`	moving minima
`K.mmu()`	`q.mmu()`	`mmu`	mmu
`K.mod()`	`q.mod()`	`mod`	remainder
`K.msum()`	`q.msum()`	`msum`	moving sum
`K.neg()`	`q.neg()`	`neg`	negate
`K.next()`	`q.next()`	`next`	next items
`K.not_()`	`q.not_()`	`not`	not
`K.null()`	`q.null()`	`null`	null
`K.or_()`	`q.or_()`	`or`	or
`K.parse()`	`q.parse()`	`parse`	parse a string
`K.peach()`	`q.peach()`	`peach`	peach
`K.pj()`	`q.pj()`	`pj`	plus join
`K.prd()`	`q.prd()`	`prd`	product
`K.prds()`	`q.prds()`	`prds`	cumulative products
`K.prev()`	`q.prev()`	`prev`	previous items
`K.prior()`	`q.prior()`	`prior`	prior
`K.rand()`	`q.rand()`	`rand`	random number
`K.rank()`	`q.rank()`	`rank`	grade up
`K.ratios()`	`q.ratios()`	`ratios`	ratios of consecutive pairs
`K.raze()`	`q.raze()`	`raze`	join items
`K.read0()`	`q.read0()`	`read0`	read file as lines
`K.read1()`	`q.read1()`	`read1`	read file as bytes
`K.reciprocal()`	`q.reciprocal()`	`reciprocal`	reciprocal of a number
`K.reval()`	`q.reval()`	`reval`	variation of eval
`K.reverse()`	`q.reverse()`	`reverse`	reverse the order of items
`K.rload()`	`q.rload()`	`rload`	load a splayed table
`K.rotate()`	`q.rotate()`	`rotate`	rotate items
`K.rsave()`	`q.rsave()`	`rsave`	rsave
`K.rtrim()`	`q.rtrim()`	`rtrim`	remove trailing spaces
`K.save()`	`q.save()`	`save`	save global data to file
`K.scov()`	`q.scov()`	`scov`	sample covariance
`K.sdev()`	`q.sdev()`	`sdev`	sample standard deviation
`K.set()`	`q.set()`	`set`	set
`K.setenv()`	`q.setenv()`	`setenv`	set an environment variable
`K.show()`	`q.show()`	`show`	format to the console
`K.signum()`	`q.signum()`	`signum`	sign of its argument/s
`K.sin()`	`q.sin()`	`sin`	sine
`K.sqrt()`	`q.sqrt()`	`sqrt`	square root
`K.ss()`	`q.ss()`	`ss`	string search
`K.ssr()`	`q.ssr()`	`ssr`	string search and replace
`K.string()`	`q.string()`	`string`	cast to string
`K.sublist()`	`q.sublist()`	`sublist`	sublist of a list
`K.sum()`	`q.sum()`	`sum`	sum of a list
`K.sums()`	`q.sums()`	`sums`	cumulative sums of a list
`K.sv()`	`q.sv()`	`sv`	consolidate
`K.svar()`	`q.svar()`	`svar`	sample variance
`K.system()`	`q.system()`	`system`	system
`K.tables()`	`q.tables()`	`tables`	sorted list of tables
`K.tan()`	`q.tan()`	`tan`	tangent
`K.til()`	`q.til()`	`til`	integers up to x
`K.trim()`	`q.trim()`	`trim`	remove leading and trailing spaces
`K.type()`	`q.type()`	`type`	data type
`K.uj()`	`q.uj()`	`uj`	union join
`K.ujf()`	`q.ujf()`	`ujf`	The ujf function.
`K.ungroup()`	`q.ungroup()`	`ungroup`	flattened table
`K.union()`	`q.union()`	`union`	distinct items of combination of two lists
`K.upper()`	`q.upper()`	`upper`	upper-case
`K.upsert()`	`q.upsert()`	`upsert`	add table records
`K.value()`	`q.value()`	`value`	value
`K.var()`	`q.var()`	`var`	variance
`K.view()`	`q.view()`	`view`	definition of a dependency
`K.views()`	`q.views()`	`views`	list of defined views
`K.vs()`	`q.vs()`	`vs`	split
`K.wavg()`	`q.wavg()`	`wavg`	weighted average
`K.where()`	`q.where()`	`where`	replicated items
`K.within()`	`q.within()`	`within`	flag items within range
`K.wj()`	`q.wj()`	`wj`	window join
`K.wj1()`	`q.wj1()`	`wj1`	window join
`K.wsum()`	`q.wsum()`	`wsum`	weighted sum
`K.ww()`	`q.ww()`	`ww`	The ww function.
`K.xasc()`	`q.xasc()`	`xasc`	table sorted ascending by columns
`K.xbar()`	`q.xbar()`	`xbar`	interval bar
`K.xcol()`	`q.xcol()`	`xcol`	rename table columns
`K.xcols()`	`q.xcols()`	`xcols`	re-order table columns
`K.xdesc()`	`q.xdesc()`	`xdesc`	table sorted descending by columns
`K.xexp()`	`q.xexp()`	`xexp`	raised to a power
`K.xgroup()`	`q.xgroup()`	`xgroup`	table grouped by keys
`K.xkey()`	`q.xkey()`	`xkey`	set primary keys of a table
`K.xlog()`	`q.xlog()`	`xlog`	base-x logarithm
`K.xprev()`	`q.xprev()`	`xprev`	previous items
`K.xrank()`	`q.xrank()`	`xrank`	items assigned to buckets