Command Line Interface
The Command Line Interface (CLI) for interacting with Packages is fully integrated with the kdb Insights CLI
as outlined here. The package
command within the kdb Insights CLI
allows a user to create, package and manage packages locally and within a kdb Insights Enterprise installation. Installation of the kdb Insights CLI
can be achieved following the instructions outlined here.
The following is the list of available commands:
$ kxi package --help
Usage: kxi package [OPTIONS] COMMAND [ARGS]...
KX Package Import/Export CLI
Options:
--version Version Info
--artifact-store DIRECTORY Directory in which to store package
artifact;[default] $KX_ARTIFACT_PATH
--pkg-lib DIRECTORY Directory in which packages will be
installed;[default] $KX_PACKAGE_PATH
--debug Enable stacktrace prints for easier debugging
--help Show this message and exit
Commands:
When pulling/pushing to a remote deployment, use these commands:
pull Download an artifact from a running service to your local dir
push Publish a package artifact to a running service
remote-list List all installed packages or artifacts on the remote system
remote-remove Remove packages/artifacts from remote service specified as
'name/ver' and...
For local development, use these commands:
init Creates a bare package at the specified target path
install Install a package given a requirement or path
list List all installed packages or artifacts
packit Create a package artifact given source code directory
uninstall Locally remove packages/artifacts packages can be specified as
'name/ver'...
Interactions with packages are local or remote with the storage of packages and their associated artifacts with a user defined path at KX_PACKAGE_PATH
and KX_ARTIFACT_PATH
respectively both locally and on an Insights Installation.
Quickstart
This quickstart provides a step-by-step guide to:
- Initialise a package locally.
- Update this package to include user defined code.
- Package this entity to generate an artifact.
- Install this package locally allowing it to be loaded and used locally.
The quickstart assumes that a user has:
- Installed the kxicli package (version >= 1.0.0) following the instructions here
Generate a simple package locally
-
Create and define the artifact and package paths.
$ mkdir -p /tmp/packages $ mkdir -p /tmp/artifacts $ export KX_PACKAGE_PATH=/tmp/packages $ export KX_ARTIFACT_PATH=/tmp/artifacts
-
Initialize a package with minimal content.
$ kxi package init qpackage Creating package at location: qpackage Creating: manifest.json { "name": "qpackage", "version": "0.0.1", "entrypoints": { "default": "init.q" }, "metadata": { "description": "", "authors": { "username": { "email": null } } }, "dependencies": {} } Creating: init.q qpackage ├── init.q └── manifest.json
-
Create a file
src/sp.q
which contains a User Defined Function (UDF) and variable, documentation outlining the structure for this UDF is provided here.$ cat src/sp.q .test.variable:1b // @udf.name("sp_map") // @udf.tag("sp") // @udf.category("map") .test.sp.map:{[table;params] select from table where x<10 }
-
Update the
init.q
file to load thesrc/sp.q
file.$ cat init.q // Load the src/sp.q file relative to package root .kxi.packages.file.load["src/sp.q"]
-
Package the artifact defining the version of the package on command line.
Note
If the package has multiple dependencies you may want to specify
--all-deps
to create an archive with all of the sub-dependencies included.$ cd .. $ kxi package packit qpackage --version 1.0.0 --tag Creating package from /Users/username/qpackage Package created: /tmp/artifacts/qpackage-1.0.0.kxi { "qpackage-1.0.0.kxi": "CREATED" }
-
Install the package locally such that it can be loaded into processes using Python/q locally.
$ kxi package install qpackage-1.0.0.kxi Installing /tmp/artifacts/qpackage-1.0.0.kxi Getting qcode=1.0.0 from [local] /tmp/artifacts/qpackage-1.0.0.kxi Unpacking qcode: /tmp/packages/qpackage/1.0.0 Successfully installed qpackage { "qpackage": [ { "version": "1.0.0", "_status": "InstallationStatus.SUCCESS" } ] }
-
List the current artifacts available locally.
$ kxi package list --artifacts Listing artifacts at: /tmp/artifacts { "qpackage": [ "1.0.0" ] }