kdb+/q IPC client · v0.1.8

xqdb moves q tables into DataFrames and Arrow.

One Rust implementation of the q IPC protocol with two bindings: Python returns Narwhals DataFrames over PyArrow, pandas, or Polars, and Node.js returns Apache Arrow tables from a native worker thread.

Packages

Package	Registry	Runtime	Install
xqdb	PyPI	CPython 3.10 to 3.14	python -m pip install xqdb
@xbbg/xqdb	npm	Node.js 20 or newer, ESM	npm install @xbbg/xqdb

Both packages are built from the underloam/xqdb repository and share the same Rust core, so the protocol support, limits, and decoding rules on these pages apply to both unless a section says otherwise. These pages describe release 0.1.8.

What it covers

Queries

Synchronous requests, asynchronous messages, and functional calls with up to eight arguments. q operators and lambdas can be passed as values.

DataFrames

Python results are Narwhals DataFrames and Series backed by PyArrow (the default), pandas, or Polars. Any eager frame or Series can be sent back as a q table or list.

Arrow in Node.js

Tables and typed lists arrive as apache-arrow Table and Vector objects. q longs are bigint, and temporal atoms keep nanoseconds.

TLS and authentication

q username and password authentication, plus TLS 1.2 or 1.3 that checks the server certificate and hostname against the operating system's trust store.

Subscriptions

receive() returns the next message the server pushes, such as tickerplant updates, on a connection you dedicate to the feed.

Files and bytes

Read q binary table files, including LZ4-compressed files, straight into a DataFrame or Arrow table. Encode q IPC messages without opening a connection.

How a request flows

1. 01Encode

   Python frames cross into Rust through the Arrow C Stream interface. In Node.js, Arrow values cross as Arrow IPC streams. Both are encoded as q IPC.

2. 02Transport

   Each connection owns one TCP socket, optionally wrapped in TLS. Python releases the GIL while it waits. Node.js runs each connection on its own native worker thread.

3. 03Decode

   The Rust core decodes the response and builds Arrow columns, decoding a table's columns in parallel.

4. 04Hand-off

   Python wraps tables in Narwhals objects for the backend you chose. Node.js gets apache-arrow objects, bigints, and nanosecond wrapper classes.

Start here

Installation

Supported Python versions, wheels, optional backends, and Node.js native packages.

Quick Start

Connect, query a table, call a function, and send rows from Python and Node.js.

Connections and TLS

Connection options, lifecycle, authentication, TLS verification, and threads.

Timeouts and Retries

Python and Node.js handle timeout and retries differently. Read this before using either in production.

Type Mapping

How every q type maps to Python, Arrow, and JavaScript, including nulls and infinities.

Benchmarks

Client-side measurements against jkdb, node-q, kola, and qconnect on one fixed server.

Generated API references cover every export: the Python API and the Node.js API. Release notes are in the changelog.

Independence and license

Independence

xqdb is independent and not affiliated with or endorsed by KX. kdb+ is a trademark of KX.

xqdb began as a fork of the kola q client. It is released under the BSD-3-Clause license, which permits use in proprietary and commercial applications. xqdb does not include a q runtime: queries need a kdb+ or KDB-X process to connect to.