Skip to content

kdb Insights Python Library

kxi is the Python client library for kdb Insights Enterprise. It provides interfaces for querying data, managing users and entitlements, monitoring workloads, and administering the platform. It requires Python 3.10 or later.

Get started

  1. Install — install kxi and its dependencies
  2. Quickstart — connect and run your first query in minutes
  3. Querying guide — full reference for SQL and getData queries
  4. API Reference — complete API documentation for all modules

Installation

Tip

Install kxi inside a virtual environment to avoid dependency conflicts. See the Python venv documentation.

Set the KX PyPI credentials as environment variables:

export KX_PYPI_USER=<your-username>
export KX_PYPI_PASS=<your-password>

Contact pykx@kx.com to obtain credentials.

Standard install

pip install --extra-index-url=https://portal.dl.kx.com/assets/pypi kxi

Full install (includes pykx, pyarrow, pandas)

pip install --extra-index-url=https://portal.dl.kx.com/assets/pypi "kxi[all]"

The [all] extras add pykx, pyarrow, and pandas. pykx enables binary Q/IPC response deserialization and is recommended for production use.

Dependencies

Required

Package Version
httpx ~0.28.0
httpx-retries 0.5.0
pydantic >=2.7.0,<3
pydantic-settings 2.14.0
PyYAML >=6.0
toml any
rich >=13.7.1
python-dateutil 2.9.0
typing-extensions >=4.5.0

Optional (kxi[all])

Package Version Purpose
pykx >=3.1.4,<4 Q/IPC binary deserialization
pyarrow >=14.0.1 Arrow format support
pandas >=1.3.5 DataFrame integration

Configuration

kxi reads connection settings from environment variables or a TOML configuration file (~/.insights/config.toml). The kxi.config.settings singleton provides access to the active configuration.

The key environment variables are:

Variable Description
INSIGHTS_URL Base URL of the kdb Insights Enterprise instance
INSIGHTS_CLIENT_ID Keycloak client ID for authentication
INSIGHTS_CLIENT_SECRET Keycloak client secret for authentication
INSIGHTS_REALM Keycloak realm name (default: insights)

See kxi.config for full configuration reference.

Quickstart

This section walks through connecting to a kdb Insights Enterprise instance and running your first query.

Prerequisites

1. Set connection credentials

The simplest way to configure kxi is via environment variables:

export INSIGHTS_URL=https://my-insights.kx.com
export INSIGHTS_CLIENT_ID=my-client-id
export INSIGHTS_CLIENT_SECRET=my-client-secret

Verify the configuration loads correctly:

from kxi.config import settings

print(settings.host)          # https://my-insights.kx.com
print(settings.client_id)     # my-client-id

2. Connect and query

Use kxi.query.Query to open an authenticated connection and run queries:

import kxi.query

conn = kxi.query.Query()

# SQL query — returns a pykx.Table
result = conn.sql("SELECT * FROM my_table LIMIT 10")
print(result)

import kxi.query

conn = kxi.query.Query(data_format="application/json")

# SQL query — returns a dict with a 'payload' key
result = conn.sql("SELECT * FROM my_table LIMIT 10")
print(result["payload"])

3. Use getData

getData provides time-range and filter-based access to kdb+ tables:

import kxi.query

conn = kxi.query.Query()

# Retrieve the last hour of data with a filter
result = conn.get_data(
    "my_table",
    start_time="2024.01.01D09:00:00.000000000",
    end_time="2024.01.01D17:00:00.000000000",
    filter=[["=", "sym", "AAPL"]],
)

4. Inspect available data

Use get_meta to discover tables, schemas, and APIs available on your deployment:

meta = conn.get_meta()
print(meta["assembly"])   # deployed assemblies
print(meta["api"])        # available API endpoints
print(meta["schema"])     # table schemas

Next steps

What's included

Module Description
kxi.query Query kdb Insights Enterprise via SQL or the getData API
kxi.config Read and manage connection configuration and profiles
kxi.observability Fetch logs, events, and pod status from deployments
kxi.package_manager Deploy and manage kdb Insights packages
kxi.entitlement Manage access entitlements on entities
kxi.user Create and manage Keycloak users and roles
kxi.group Create and manage Keycloak groups
kxi.client Register and manage Keycloak auth clients
kxi.client_controller Enrol and remove clients via the Client Controller
kxi.information_service Query enrolled client details
kxi.workloads Send requests to KDB-X Group workload instances
kxi.exceptions Exception types raised by the library
kxi.publish.dbpublisher Publish data via Q IPC to a kdb+ TP port
kxi.publish.http_publisher Publish data via HTTP into a stream processing pipeline
kxi.publish.rtpublisher Publish data via the RT persistence layer
Back to top