Skip to content

Custom Code and User-Defined Functions (UDFs) in KDB-X DB Service

This page describes how to load custom q code into the KDB-X DB Service, and how the resulting user-defined functions (UDFs) are served over REST.

Custom q code can be loaded into the DB Service to serve custom API endpoints.

UDFs and UDAs

The DB Service is built on the Insights SDK, where user-defined functions (UDFs) were named user-defined analytics (UDAs). While the DB Service is in preview, the registration code and reference documentation use the older nomenclature.

To load custom q code, set the KXI_CUSTOM_FILE environment variable to the file path in the da and agg processes. The code directory is mounted alongside the data directory of your deployment; place your custom code there.

For detailed information on creating UDFs, refer to the Insights SDK UDA documentation.

A registered UDF is served over REST at /api/v0/<namespace>/<name>, derived from the function's fully qualified q name: the leading dot is dropped, and the remaining dots become slashes. For example, a UDF registered as .fx.spreadStats is served at /api/v0/fx/spreadStats. Pass parameters as a JSON object in the request body.

Examples are provided in the samples/code/ directory of the DB Service. You can copy these into code/.

Single UDF approach

Use this approach when all your custom code lives in one file. KXI_CUSTOM_FILE takes a single file path, so pointing it directly at that file is enough; to load more than one file, use an entry point instead.

The example analytic spreadStats.q registers .fx.spreadStats, which returns the average bid, ask, and spread with a quote count by sym. Copy it from samples/code/ into your local code directory, then point KXI_CUSTOM_FILE at the path as the container sees it — the code directory is mounted at /code.

.env:

export KXI_CUSTOM_FILE=/code/spreadStats.q

Start the service:

docker compose up -d

.fx.spreadStats is served at /api/v0/fx/spreadStats:

curl -s -X POST http://localhost:8080/api/v0/fx/spreadStats \
  -H 'Content-Type: application/json' \
  -d '{"table":"fxquote","startTS":"2026-03-01T00:00:00.000","endTS":"2026-03-03T00:00:00.000"}'

Multiple UDFs with an entry point

Point KXI_CUSTOM_FILE at one entry point file that loads each analytic with \l. Relative \l paths resolve against the entry point file's directory (/code), which remains the working directory for the whole load. code/custom.q loads both example analytics:

code/custom.q:

\l spreadStats.q
\l midStats.q

.env:

export KXI_CUSTOM_FILE=/code/custom.q

After docker compose up -d, both .fx.spreadStats and .fx.midStats are registered and callable:

curl -s -X POST http://localhost:8080/api/v0/fx/midStats \
  -H 'Content-Type: application/json' \
  -d '{"table":"fxquote","startTS":"2026-03-01T00:00:00.000","endTS":"2026-03-03T00:00:00.000"}'

Apply changes to your custom code

If the entry point file that KXI_CUSTOM_FILE points to is unchanged, edit the file in the local code directory, then restart the da and agg processes.

docker compose restart kx-db-da kx-db-agg

Next steps