kola

PyPI Python

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)

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:

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 operators are returned as Operator enum members.

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

Project links

Data verified by PyPI on Sep 21, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.6.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for delphiash from gravatar.com delphiash

Credits

Author: Jo Shinonome

GitHub Statistics

Data verified by PyPI on Sep 21, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.10

Tags

q kdb polars dataframe arrow

Classifiers

Report project as malware

Metadata

Project links

Data verified by PyPI on Sep 21, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.6.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for delphiash from gravatar.com delphiash

Credits

Author: Jo Shinonome

GitHub Statistics

Data verified by PyPI on Sep 21, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.10

Tags

q kdb polars dataframe arrow

Classifiers

Report project as malware

Release files for kola 2.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kola 2.6.0
File Size Uploaded
kola-2.6.0.tar.gz 69.0 kB Details

Built distributions (wheels)

Table of built distributions (wheels) for kola 2.6.0
File
kola-2.6.0-cp310-abi3-win_amd64.whl 3.2 MB CPython 3.10 abi3 Windows x86-64 Details
kola-2.6.0-cp310-abi3-manylinux_2_28_x86_64.whl 3.9 MB CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details
kola-2.6.0-cp310-abi3-macosx_11_0_arm64.whl 2.9 MB CPython 3.10 abi3 macOS 11.0+ ARM64 Details
kola-2.6.0-cp310-abi3-macosx_10_12_x86_64.whl 3.4 MB CPython 3.10 abi3 macOS 10.12+ x86-64 Details

Total release size: 13.5 MB

Release files / kola-2.6.0.tar.gz

Download URL kola-2.6.0.tar.gz
Size 69.0 kB
Tags Source
SHA-256 checksum
How to use checksums 		90ff3ca6efe1fa60222eca761f92090a050401df5f7475fac5895177cb579d7b
BLAKE2b-256 checksum
How to use checksums 		3c5aaa56616cb4f8f30d2a7946c11bb4a21745cfaec7d0fd6d0ef6b29fdab1f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		Yes
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}

Release files / kola-2.6.0-cp310-abi3-win_amd64.whl

Download URL kola-2.6.0-cp310-abi3-win_amd64.whl
Size 3.2 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums 		0c06afc32c1be8653439559fd922e4fae60767710c0591a02ee530a0064be82f
BLAKE2b-256 checksum
How to use checksums 		cd2841138b132811691536e551460795688110accc1ddc82dad889b83705b995
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		Yes
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}

Release files / kola-2.6.0-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL kola-2.6.0-cp310-abi3-manylinux_2_28_x86_64.whl
Size 3.9 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums 		db262e950adaf1799755359be1784288ce83c2dc896a5e7d97a2c321e8fd3328
BLAKE2b-256 checksum
How to use checksums 		809727026d2c784a41d258d03acff4727f6e65745bf8efec4d0b4cf94a34c1c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		Yes
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}

Release files / kola-2.6.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL kola-2.6.0-cp310-abi3-macosx_11_0_arm64.whl
Size 2.9 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums 		63d2f93e865d5265b1074e8d45d4362c3229480ae08b66227be15b5c69b498a0
BLAKE2b-256 checksum
How to use checksums 		56491795aaaf4f16d5db817d46969d2f9151e9dc09fcbff4cda1de68d4b73495
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		Yes
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}

Release files / kola-2.6.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL kola-2.6.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 3.4 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums 		c5b4d06c60351752b70047bb62f4171b0c98ebe1d915b2da499c0cb019d11ecc
BLAKE2b-256 checksum
How to use checksums 		b81d59281263cac19ee259d5339182c2fdecdcde1332e33c536ce85b8905fef4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing? 		Yes
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","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}
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page