PyQ 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')
>>> 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 statistical covariance
K.scov() q.scov() scov statistical covariance
K.sdev() q.sdev() sdev statistical standard deviation
K.sdev() q.sdev() sdev statistical 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 statistical variance
K.svar() q.svar() svar statistical 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