Skip to content

q API

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

Installation

To use the q packaging API requires you must first install the kdb Insights CLI following the instruction guide here.

Once the kdb Insights CLI is installed, download the latest kxi_packages.x.y.z.kxi artifact from the kx-insights-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. You have installed the kxi_packages q library following the instructions here.
  2. You have already followed the quickstart guide presented for the CLI here and have 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:

  1. 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..

  2. 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"

  3. 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"    ..

  4. 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
  })

  5. 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
  }