kola

A Python Polars interface to kdb+/q, powered by Rust.

Installation

pip install kola

Requirements: Python ≥ 3.10, Polars ≥ 1.31.0, PyArrow ≥ 20.0.0

Quick Start

Create a Connection

import polars as pl
import kola

# basic connection
conn = kola.Q('localhost', 1800)

# with authentication
conn = kola.Q('localhost', 1800, user='user', passwd='password')

# with TLS and retry
conn = kola.Q('localhost', 1800, enable_tls=True, retries=3, timeout=30)

Parameters:

Connect / Disconnect

# explicitly connect (auto-connects on first query)
conn.connect()

# disconnect (auto-disconnects on IO error)
conn.disconnect()

String Query

conn.sync("select from trade where date=last date")

Functional Query

Supports Python basic data types, pl.Series, pl.DataFrame, and dict (with string keys).

from datetime import date, time

conn.sync(
    ".gw.query",
    "table",
    {
        "date": date(2023, 11, 21),
        "syms": pl.Series("", ["sym0", "sym1"], kola.QType.Symbol),
        "startTime": time(9),
        "endTime": time(11, 30),
    },
)

Send DataFrame

# Polars DataFrame
conn.sync("upsert", "table", pl_df)

# Pandas DataFrame (cast to Polars first)
conn.sync("upsert", "table", pl.DataFrame(pd_df))

Async Query

conn.asyn("upsert", "table", pl_df)

Subscribe

from kola import QType

conn.sync(".u.sub", pl.Series("", ["table1", "table2"], QType.Symbol), "")

# with symbol filter
conn.sync(
    ".u.sub",
    pl.Series("", ["table1", "table2"], QType.Symbol),
    pl.Series("", ["sym1", "sym2"], QType.Symbol),
)

while True:
    # returns ("upd", "table", pl.DataFrame)
    upd = conn.receive()
    print(upd)

Generate IPC Bytes

Serialize data as kdb+ IPC bytes without a connection.

from kola import serialize_as_ipc_bytes6

df = pl.DataFrame(
    {
        "sym": pl.Series("sym", ["a", "b", "c"], pl.Categorical),
        "price": [1, 2, 3],
    }
)

# without compression
buffer = serialize_as_ipc_bytes6("sync", False, ["upd", "table", df])

# with compression
buffer = serialize_as_ipc_bytes6("sync", True, ["upd", "table", df])

msg_type: "async" | "sync" | "response"

Use the Operator enum to serialize K101 unary primitives and K102 operators:

from kola import Operator, serialize_as_ipc_bytes6

buffer = serialize_as_ipc_bytes6("sync", False, Operator.SUM)
assert buffer[8:] == bytes([101, 25])

Operators also work as query arguments and inside lists and dictionaries. Members include Operator.SUM, Operator.AVG, Operator.PLUS (unary +:), and Operator.PROJECTION_NULL (::). The .value attribute holds the q name; Operator("sum") also resolves to Operator.SUM. Unknown names raise ValueError. Ordinary strings serialize as symbols; None serializes as generic null. Received K101 and K102 operators are returned as Operator enum members.

K102 members include Operator.BINARY_PLUS (+), Operator.IN, Operator.WAVG, and Operator.DIV. For example:

buffer = serialize_as_ipc_bytes6("sync", False, Operator.BINARY_PLUS)
assert buffer[8:] == bytes([102, 1])

Named unary aliases include Operator.FLIP, Operator.NEG, Operator.FIRST, Operator.COUNT, Operator.TYPE, and Operator.VALUE. They retain the existing symbolic values: Operator.FLIP is Operator.PLUS, and both encode as [101, 1]. The mappings follow jkdb's K101/K102 lists; named unary aliases were checked against q 3.6. This does not claim exhaustive coverage across q versions.

The 177 keywords on the KX reference card were checked against q 3.6 on 2026-09-22. The per-keyword runtime type and serialized type are recorded in test/q_keyword_types.json. Run python scripts/check_q_keywords.py from the repository root to repeat the check with your installed q version. The script resolves and serializes values without applying the functions.

Of those keywords, 58 serialize directly as K101/K102 values. The others include lambdas, projections, compositions, derived functions, the csv character, and seven syntax keywords that cannot be resolved as standalone values. Operator.LSQ and Operator.MMU alias K102 ! and $. Use BINARY_AND and BINARY_OR for the q keywords and and or; the original AND and OR enum members retain their unary &: and |: meanings.

In q 3.6, hopen, var, dev, cov, and cor have primitive runtime types but serialize as compatibility lambdas. Their current enum encodings use the direct jkdb primitive codes and do not reproduce those lambda encodings. <>, <=, and >= serialize as K105 compositions and are not yet supported.

Read Binary Table

Read a kdb+ binary table (splayed/flat file) directly into a Polars DataFrame.

from kola import read_binary6

df = read_binary6("/path/to/binary/table")

Error Handling

from kola import KolaError, KolaIOError, KolaAuthError

try:
    conn.sync("select from trade")
except KolaAuthError:
    print("Authentication failed")
except KolaIOError:
    print("Connection error")
except KolaError:
    print("General kola error")

QType

kola.QType provides Polars dtype aliases for q types, useful when constructing pl.Series for functional queries.

Data Type Mapping

Deserialization (q → Python)

Atom

List / Table

Guid is deserialized as a 16-byte fixed binary array. Use .hex() to convert to string if needed:

df.with_columns(pl.col("uuid").apply(lambda u: u.hex()))

real/float 0n is mapped to Polars null, not NaN.

short/int/long null and infinity values (0Nh/i/j, 0Wh/i/j, -0Wh/i/j) are mapped to null.

Serialization (Python → q)

Basic Data Type

Series, DataFrame, and Dictionary

Dictionary serialization requires str keys.

Polars Documentation

• User Guide
• API Reference