Skip to content

Query User-Defined Analytics (UDAs) using the CLI

kxi query uda lets you discover and run User-Defined Analytics directly from the CLI.

Note

To create and configure UDAs, refer to User-Defined Analytics.

Listing UDAs

kxi query uda

With no arguments, lists all UDAs available in the connected environment in a rich table showing name, description, accepted tables, and the packages each UDA is loaded in.

╭─ User-Defined Analytics ──────────────────────────────────────────────────────────────────────╮
│ Name             │ Params                  │ Description          │ Loaded in        │ Tables │
├──────────────────┼─────────────────────────┼──────────────────────┼──────────────────┼────────┤
│ .myuda.getQuote  │ table  symbol  ✓        │ Get latest quote     │ my-pkg (rdb,hdb) │ quote  │
│                  │ sym    symbol           │ for sym              │                  │        │
│                  │ → Table                 │                      │                  │        │
├──────────────────┼─────────────────────────┼──────────────────────┼──────────────────┼────────┤
│ .myuda.getTrade  │ table  symbol  ✓        │ Get trade data       │ my-pkg (rdb,hdb) │ trade  │
│                  │ n      long             │                      │                  │        │
│                  │ → Table                 │                      │                  │        │
╰──────────────────┴─────────────────────────┴──────────────────────┴──────────────────┴────────╯

Example

Write the UDA list to CSV: 

kxi query uda --output-format csv --output-file udas.csv

Running a UDA

kxi query uda .ns.func [PARAM=VALUE ...] [OPTIONS]

Parameters are passed as KEY=VALUE pairs. Values are JSON-decoded automatically — numbers, booleans, and JSON objects are parsed; plain strings are left as-is.

Example:

kxi query uda .myuda.uda table=trades startTS=2026-05-20T09:32:20.017713245

                         time sym     price  size      label
2026-05-20T09:32:20.017713245 AAA 301.19070   980 Hello, AAA
2026-05-20T09:32:20.017713245 BBB  31.71000   320 Hello, BBB

Example

Save results as a pandas pickle file: 

kxi query uda .myuda.uda table=trades --output-format pandas --output-file result.pkl

UDA help

kxi query uda .ns.func --help

Shows UDA-specific help: the usage line, a Signature panel with parameter names, types, and defaults, Runtime Info panels (Loaded In / Tables side-by-side), and the standard CLI options.

Usage: kxi query uda .myuda.getTrade [PARAM=VALUE ...]

  Get trade data

╭─ UDA Signature ────────────────────────────────────────────────────────────────╮
│ Param   Type    Req   Default   Param Desc.                                    │
│ table   symbol   ✓              Table to query                                 │
│ n       long                    Number of rows (default all)                   │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ Loaded In ────────────────────────────╮╭─ Tables ──────────────────────────────╮
│ my-pkg (rdb, hdb)                      ││ trade                                 │
╰────────────────────────────────────────╯╰───────────────────────────────────────╯

Options:
  --scope JSON         Target a specific assembly/database, tier, or DAP.
  --labels JSON        Filter DAPs by label.
  --opts JSON          Override request options.
  --use-qe             Route to the Query Environment.
  --output-format      [tabular|csv|json|json_records|pandas]
  --output-file TEXT   Write results to a file instead of console.

Routing options

These options route and filter the request through the gateway:

Option Description
--scope JSON Target a specific assembly/database, tier, or DAP. For example, '{"assembly": "my-pkg"}' or '{"assembly": "my-pkg", "tier": "hdb"}'
--labels JSON Filter DAPs by label. For example, '{"region": "amer"}'
--opts JSON Override request options. For example, '{"aggFn": "myAggFn"}'
--use-qe Route to the Query Environment(s) instead of main query path (requires Query Environment(s) to be enabled)

Note

If a UDA is loaded inside an agg instance within a package, --scope defaults to {"assembly": "<that-package>"} automatically. This ensures the aggregator is used during query execution — without it, the query may time out. The default is visible in kxi query uda .ns.func --help under the Options section.

Example

Target a specific tier: 

kxi query uda .myuda.uda table=trades --scope '{"assembly": "my-pkg", "tier": "hdb"}'
Route to the Query Environment(s): 
kxi query uda .myuda.uda table=trades --use-qe

Output formats

--output-format and --output-file control how query results are returned. Place them before or after the UDA name.

--output-format --output-file Wire format Action
tabular / unset — JSON Print tabular text to console
tabular / unset ✓ OCTET_STREAM Write serialized q bytes to file
pandas ✓ OCTET_STREAM Write pandas pickle to file
csv either JSON Write / print CSV
json either JSON Write / print columnar JSON
json_records either JSON Write / print one JSON object per row

Reading binary output files

pandas pickle (--output-format pandas --output-file mytab.pkl):

import pandas
pandas.read_pickle("mytab.pkl")

Serialized q bytes (--output-format tabular --output-file qflattab):

-9!read1 `:qflattab

Comparison with kxi query --sql

kxi query uda supports the same output formats as kxi query --sql. pandas requires --output-file for both; it is additionally available without a file when running a named UDA.

Format --sql uda (list) uda .ns.func
tabular ✓ ✓ ✓
csv ✓ ✓ ✓
json ✓ ✓ ✓
json_records ✓ ✓ ✓
pandas ✓ (file only) — ✓ (file only)
Back to top