Skip to content

q API

The q API for package interactions provides users with the ability to list and load the contents of a package. Users are presented with two interfaces under the .kxi namespace, packages and udfs, which allow users to interact with these entities independently.

Installation

To use the q packaging API requires a user to first install the kdb Insights CLI following the instruction guide here.

Once installed download the latest kxi_packages.x.y.z.kxi artifact from the packages/kx_packages directory on the KX Nexus where x.y.z represents the version of the kxi_packages functionality used.

Once downloaded install this *.kxi object using the kdb Insights CLI using the following command to generate a symlink to $QHOME. The use of this symlink is intended to make loading the package easier from command line.

$ kxi package install kxi_packages-x.y.z.kxi --add-symlink-to=$QHOME    # Replace x.y.z with the downloaded version available

The library for loading packages is now available for use and can be validated as follows:

$ q kxi_packages/x.y.z/init.q
q).kxi
        | ::
packages| ``util`file`list`loaded`load`rest!(::;``path`protectedLoadQPK`loadQ..
log     | ``info`warn`error`fatal!(::;locked;locked;locked;locked)
load    | ``lq!(::;locked)
udfs    | ``util`list`validate`loaded`load`rest!(::;``defaultCols`defaultFile..

Quickstart Example

The following example assumes the following pre-requisites

  1. A user has installed the kxi_packages q library following the instructions here
  2. A user has followed the quickstart guide presented for the CLI here and as such has a local package qpackage-1.0.0.kxi installed.

Note

The q API for package and UDF interactions make use of an experimental API for the generation of variadic functions, this API is outlined here.

Once the above pre-requisites have been met a user should follow the below instructions:

  • Start your q process, loading the kxi_packages library. In this example version 1.2.0 of the library is installed.

    $ q kxi_packages/1.2.0/init.q
q).kxi
        | ::
packages| ``util`file`list`loaded`load`rest!(::;``path`protectedLoadQPK`loadQ..
log     | ``info`warn`error`fatal!(::;locked;locked;locked;locked)
load    | ``lq!(::;locked)
udfs    | ``util`list`validate`loaded`load`rest!(::;``defaultCols`defaultFile..

  • List all packages available on the current local installation

    q).kxi.packages.list.all[]
name           versions
-----------------------
"kxi_packages" "1.2.0" 
"qpackage"    "1.0.0"

  • List UDFs associated with the specified installed packages

    q).kxi.udfs.list.search[::;"q*";"*"]
name     function       language file_path                                   ..
-----------------------------------------------------------------------------..
"sp_map" ".test.sp.map" ,"q"     "/tmp/packages/qpackage/1.0.0/src/sp.q"    ..

  • Load the package contents

    q).kxi.packages.load["qpackage";"1.0.0"]
q).test
variable| 1b
sp      | ``map!(::;{[table;params]
  select from table where x<10
  })

  • Retrieve the UDF as a named function

    q)test_udf:.kxi.udfs.load["sp_map";"qpackage";"1.0.0"]
q)test_udf
{[table;params]
  select from table where x<10
  }