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:

Parameter	Type	Default	Description
`host`	`str`		Hostname of the q process
`port`	`int`		Port of the q process
`user`	`str`	`""`	Username (defaults to OS login user)
`passwd`	`str`	`""`	Password
`enable_tls`	`bool`	`False`	Enable TLS encryption
`retries`	`int`	`0`	Number of retries with exponential backoff
`timeout`	`int`	`0`	Connection timeout in seconds (0 = no timeout)

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)

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"

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.

QType	Polars dtype
`Boolean`	`pl.Boolean`
`Guid`	`pl.Array(pl.Binary, 16)`
`Byte`	`pl.UInt8`
`Short`	`pl.Int16`
`Int`	`pl.Int32`
`Long`	`pl.Int64`
`Real`	`pl.Float32`
`Float`	`pl.Float64`
`Char`	`pl.UInt8`
`String`	`pl.Utf8`
`Symbol`	`pl.Categorical`
`Timestamp`	`pl.Datetime("ns")`
`Date`	`pl.Date`
`Datetime`	`pl.Datetime("ms")`
`Timespan`	`pl.Duration("ns")`
`Time`	`pl.Time`

Data Type Mapping

Deserialization (q → Python)

Atom

q type	n	size	Python type	Note
`boolean`	1	1	`bool`
`guid`	2	16	`str`
`byte`	4	1	`int`
`short`	5	2	`int`
`int`	6	4	`int`
`long`	7	8	`int`
`real`	8	4	`float`
`float`	9	8	`float`
`char`	10	1	`str`
`string`	10	1	`str`
`symbol`	11	*	`str`
`timestamp`	12	8	`datetime`
`month`	13	4	`-`
`date`	14	4	`date`	0001.01.01 - 9999.12.31
`datetime`	15	8	`datetime`
`timespan`	16	8	`timedelta`
`minute`	17	4	`time`	00:00 - 23:59
`second`	18	4	`time`	00:00:00 - 23:59:59
`time`	19	4	`time`	00:00:00.000 - 23:59:59.999

List / Table

q type	n	size	Polars dtype
`boolean list`	1	1	`pl.Boolean`
`guid list`	2	16	`pl.Array(pl.Binary, 16)`
`byte list`	4	1	`pl.UInt8`
`short list`	5	2	`pl.Int16`
`int list`	6	4	`pl.Int32`
`long list`	7	8	`pl.Int64`
`real list`	8	4	`pl.Float32`
`float list`	9	8	`pl.Float64`
`char list`	10	1	`pl.Utf8`
`string list`	10	1	`pl.Utf8`
`symbol list`	11	*	`pl.Categorical`
`timestamp list`	12	8	`pl.Datetime("ns")`
`month list`	13	4	`-`
`date list`	14	4	`pl.Date`
`datetime list`	15	8	`pl.Datetime("ms")`
`timespan list`	16	8	`pl.Duration("ns")`
`minute list`	17	4	`pl.Time`
`second list`	18	4	`pl.Time`
`time list`	19	4	`pl.Time`
`table`	98	*	`pl.DataFrame`
`dictionary`	99	*	`-`
`keyed table`	99	*	`pl.DataFrame`

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

Python type	q type	Note
`bool`	`boolean`
`int`	`long`
`float`	`float`
`str`	`symbol`
`bytes`	`string`
`datetime`	`timestamp`
`date`	`date`	0001.01.01 - 9999.12.31
`timedelta`	`timespan`
`time`	`time`	00:00:00.000 - 23:59:59.999

Series, DataFrame, and Dictionary

Polars dtype	q type
`dict`	dict
`pl.Boolean`	boolean
`pl.Array(pl.Binary, 16)`	guid
`pl.UInt8`	byte
`pl.Int16`	short
`pl.Int32`	int
`pl.Int64`	long
`pl.Float32`	real
`pl.Float64`	float
`pl.Utf8`	char
`pl.Categorical`	symbol
`pl.Datetime`	timestamp
`pl.Date`	date
`pl.Duration`	timespan
`pl.Time`	time
`pl.DataFrame`	table

Dictionary serialization requires str keys.

Polars Documentation

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kola-2.5.0.tar.gz (64.4 kB view details)

Uploaded Aug 5, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

kola-2.5.0-cp310-abi3-win_amd64.whl (3.2 MB view details)

Uploaded Aug 5, 2026 CPython 3.10+Windows x86-64

kola-2.5.0-cp310-abi3-manylinux_2_28_x86_64.whl (3.9 MB view details)

Uploaded Aug 5, 2026 CPython 3.10+manylinux: glibc 2.28+ x86-64

kola-2.5.0-cp310-abi3-macosx_11_0_arm64.whl (2.9 MB view details)

Uploaded Aug 5, 2026 CPython 3.10+macOS 11.0+ ARM64

kola-2.5.0-cp310-abi3-macosx_10_12_x86_64.whl (3.4 MB view details)

Uploaded Aug 5, 2026 CPython 3.10+macOS 10.12+ x86-64

File details

Details for the file kola-2.5.0.tar.gz.

File metadata

Download URL: kola-2.5.0.tar.gz
Upload date: Aug 5, 2026
Size: 64.4 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for kola-2.5.0.tar.gz
Algorithm	Hash digest
SHA256	`12a69ec36f4a6d5b7338da466a194faee9e48b37b336f48ab1b608e736ccff0f`
MD5	`f1ec4186cdd2d29f9fc22572759470dc`
BLAKE2b-256	`95a0d59f7ee938099604d802f199c34193b8421971e7c1dc3d457fa5ec76240c`

See more details on using hashes here.

File details

Details for the file kola-2.5.0-cp310-abi3-win_amd64.whl.

File metadata

Download URL: kola-2.5.0-cp310-abi3-win_amd64.whl
Upload date: Aug 5, 2026
Size: 3.2 MB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for kola-2.5.0-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`bc3aef4dc78c6bc5ce3731ac20dd0494587f4a67666b7ed2ec26d39047d7a9e8`
MD5	`cd1548d0c68b982e1e80a46e8fcc1bd4`
BLAKE2b-256	`9cc13e20c90beda0cf6e07aa7199d72fb2c82a19607a8735d3186d0a3f381a84`

See more details on using hashes here.

File details

Details for the file kola-2.5.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: kola-2.5.0-cp310-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 5, 2026
Size: 3.9 MB
Tags: CPython 3.10+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for kola-2.5.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`8425e9cfd06c8967c379a675247edaca71069cc5f510f89ec66da39c8f59cc27`
MD5	`3adb01c339aeadb02ed6bc9ddaae928a`
BLAKE2b-256	`933de083005c8c9879869ab152ce78f6fa317b8ab7972abd8d2eaa668f10ca71`

See more details on using hashes here.

File details

Details for the file kola-2.5.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: kola-2.5.0-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Aug 5, 2026
Size: 2.9 MB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for kola-2.5.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`d66ceda80fe9f9b728689eb3c526395a69c7c41afaf489e2f236de923e3e2406`
MD5	`a27abf02d08fa4bb77e088814ea2f0bb`
BLAKE2b-256	`010f20dc0fa8b124cc1a3ebf5b1eaf4aeed13adf3a77a26fb2e57bb880e42631`

See more details on using hashes here.

File details

Details for the file kola-2.5.0-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: kola-2.5.0-cp310-abi3-macosx_10_12_x86_64.whl
Upload date: Aug 5, 2026
Size: 3.4 MB
Tags: CPython 3.10+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: uv/0.12.1 {"installer":{"name":"uv","version":"0.12.1","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for kola-2.5.0-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`b4ad47961a4476a1bd18dc0c7a35690c5ade3dc9d971f81b7597acb116bfa0c7`
MD5	`fc5978999e8f2864daa2dd2c207bde9c`
BLAKE2b-256	`d79894ab942ef93d95ae6a19ebb1f53c014caf455a646730abbc8ed5a2886b3c`